summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/text-en
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/text-en')
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-actions.tex530
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-animations.tex1492
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-arrows.tex962
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-decorations.tex979
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-design.tex146
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-external.tex502
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-images.tex274
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-internalregisters.tex127
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-layers.tex136
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-matrices.tex437
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-nodes.tex1305
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-paths.tex876
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-patterns.tex261
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-plots.tex587
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-points.tex683
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-quick.tex189
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-scopes.tex1027
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-shadings.tex762
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-transformations.tex1246
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-base-transparency.tex391
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-drivers.tex468
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-dv-axes.tex3822
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-dv-backend.tex34
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-dv-examples.tex95
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-dv-formats.tex645
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-dv-introduction.tex148
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-dv-main.tex828
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-dv-polar.tex458
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-dv-stylesheets.tex4033
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-dv-visualizers.tex818
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-algorithm-layer.tex832
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-algorithms-in-c.tex864
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-binding-layer.tex281
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-circular.tex29
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-display-layer.tex285
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-edge-routing.tex33
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-examples.tex14
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-force.tex43
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-layered.tex33
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-misc.tex30
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-ogdf.tex115
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-overview.tex310
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-phylogenetics.tex83
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-trees.tex39
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-usage-pgf.tex688
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-gd-usage-tikz.tex549
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-guidelines.tex651
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-installation.tex171
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-introduction.tex261
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-3d.tex245
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-angles.tex109
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-arrows.tex245
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-automata.tex335
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-babel.tex94
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-backgrounds.tex283
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-calc.tex7
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-calendar.tex976
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-chains.tex499
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-circuits.tex2236
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-decorations.tex2180
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-edges.tex330
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-er.tex155
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-external.tex1227
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-fadings.tex51
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-fit.tex161
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-fixedpoint.tex120
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-folding.tex255
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-fpu.tex714
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-lsystems.tex390
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-math.tex471
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-matrices.tex334
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-mindmaps.tex523
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-patterns.tex572
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-perspective.tex446
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-petri.tex380
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex694
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-marks.tex116
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-profiler.tex242
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-rdf.tex1040
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-shadings.tex220
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-shadows.tex291
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-shapes.tex2295
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-spy.tex463
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-svg-path.tex58
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-through.tex43
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-trees.tex196
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-turtle.tex117
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-library-views.tex127
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-license.tex1229
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-main-body.tex860
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-main-preamble.tex384
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-main.tex16
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-math-algorithms.tex231
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-math-commands.tex246
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-math-design.tex95
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-math-numberprinting.tex875
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-math-parsing.tex1414
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-module-parser.tex311
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-oo.tex690
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-pages.tex636
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-pgfcalendar.tex492
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-pgffor.tex418
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeys.tex1743
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeysfiltered.tex579
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-animations.tex1654
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-commands.tex1390
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-overview.tex79
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-paths.tex217
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-protocol.tex89
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-actions.tex1449
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-animations.tex2805
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-arrows.tex2559
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-coordinates.tex1330
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-decorations.tex559
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-design.tex274
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-graphs.tex3703
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-matrices.tex865
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-paths.tex1426
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-pics.tex645
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-plots.tex776
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-scopes.tex582
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-shapes.tex3061
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-transformations.tex499
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-transparency.tex895
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-trees.tex868
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-Euclid.tex692
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-chains.tex1067
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-map.tex1331
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-nodes.tex1020
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial.tex1400
-rw-r--r--graphics/pgf/base/doc/text-en/pgfmanual-en-xxcolor.tex85
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-asymptotic-example.gnuplot2
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-asymptotic-example.table204
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-exp.gnuplot2
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-exp.table29
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-parametric-example.gnuplot2
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-parametric-example.table29
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-sin.gnuplot2
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-sin.table29
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-tan-example.gnuplot2
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-tan-example.table104
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-x.gnuplot2
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgf-x.table29
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgfmanual-sine.gnuplot4
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgfmanual-sine.table24
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgfplotgnuplot-example.gnuplot2
-rw-r--r--graphics/pgf/base/doc/text-en/plots/pgfplotgnuplot-example.table104
147 files changed, 0 insertions, 90921 deletions
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-actions.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-actions.tex
deleted file mode 100644
index 8a6fff31cb..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-actions.tex
+++ /dev/null
@@ -1,530 +0,0 @@
-% 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{Using Paths}
-
-\subsection{Overview}
-
-Once a path has been constructed, it can be \emph{used} in different ways. For
-example, you can draw the path or fill it or use it for clipping.
-
-Numerous graph parameters influence how a path will be rendered. For example,
-when you draw a path, the line width is important as well as the dashing
-pattern. The options that govern how paths are rendered can all be set with
-commands starting with |\pgfset|. \emph{All options that influence how a path
-is rendered always influence the complete path.} Thus, it is not possible to
-draw part of a path using, say, a red color and drawing another part using a
-green color. To achieve such an effect, you must use two paths.
-
-In detail, paths can be used in the following ways:
-%
-\begin{enumerate}
- \item You can \emph{stroke} (also known as \emph{draw}) a path.
- \item You can add \emph{arrow tips} to a path.
- \item You can \emph{fill} a path with a uniform color.
- \item You can \emph{clip} subsequent renderings against the path.
- \item You can \emph{shade} a path.
- \item You can \emph{use the path as bounding box} for the whole picture.
-\end{enumerate}
-%
-You can also perform any combination of the above, though it makes no sense to
-fill and shade a path at the same time.
-
-To perform (a combination of) the first four actions, you can use the following
-command:
-%
-\begin{command}{\pgfusepath\marg{actions}}
- Applies the given \meta{actions} to the current path. Afterwards, the
- current path is (globally) empty. The following actions are possible:
- %
- \begin{itemize}
- \item \declare{|fill|} fills the path. See Section~\ref{section-fill}
- for further details.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{1cm}{0cm}}
- \pgfusepath{fill}
-\end{pgfpicture}
-\end{codeexample}
- %
- \item \declare{|stroke|} strokes the path. See
- Section~\ref{section-stroke} for further details.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{1cm}{0cm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
- \item \declare{|draw|} has the same effect as |stroke|.
- \item \declare{|clip|} clips all subsequent drawings against the path.
- Always suppresses arrow tips. See Section~\ref{section-clip} for
- further details.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{1cm}{0cm}}
- \pgfusepath{stroke,clip}
- \pgfpathcircle{\pgfpoint{1cm}{1cm}}{0.5cm}
- \pgfusepath{fill}
-\end{pgfpicture}
-\end{codeexample}
- %
- \item \declare{|discard|} discards the path, that is, it is not used at
- all. Giving this option (alone) has the same effect as giving an
- empty options list.
- \end{itemize}
- %
- When more than one of the first three actions are given, they are applied
- in the above ordering, regardless of their ordering in \meta{actions}.
- Thus, |{stroke,fill}| and |{fill,stroke}| have the same effect.
-\end{command}
-
-To shade a path, use the |\pgfshadepath| command, which is explained in
-Section~\ref{section-shadings}.
-
-
-\subsection{Stroking a Path}
-\label{section-stroke}
-
-When you use |\pgfusepath{stroke}| to stroke a path, several graphic parameters
-influence how the path is drawn. The commands for setting these parameters are
-explained in the following.
-
-Note that all graphic parameters apply to the path as a whole, never only to a
-part of it.
-
-All graphic parameters are local to the current |{pgfscope}|, but they persists
-past \TeX\ groups, \emph{except} for the interior rule (even-odd or nonzero)
-and the arrow tip kinds. The latter graphic parameters only persist till the
-end of the current \TeX\ group, but this may change in the future, so do not
-count on this.
-
-
-\subsubsection{Graphic Parameter: Line Width}
-
-\begin{command}{\pgfsetlinewidth\marg{line width}}
- This command sets the line width for subsequent strokes (in the current
- |pgfscope|). The line width is given as a normal \TeX\ dimension like
- |0.4pt| or |1mm|.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfsetlinewidth{1mm}
- \pgfpathmoveto{\pgfpoint{0mm}{0mm}}
- \pgfpathlineto{\pgfpoint{2cm}{0mm}}
- \pgfusepath{stroke}
- \pgfsetlinewidth{2\pgflinewidth} % double in size
- \pgfpathmoveto{\pgfpoint{0mm}{5mm}}
- \pgfpathlineto{\pgfpoint{2cm}{5mm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{textoken}{\pgflinewidth}
- You can access the current line width via the \TeX\ dimension
- |\pgflinewidth|. It will be set to the correct line width, that is, even
- when a \TeX\ group closed, the value will be correct since it is set
- globally, but when a |{pgfscope}| closes, the value is set to the correct
- value it had before the scope.
-\end{textoken}
-
-
-\subsubsection{Graphic Parameter: Caps and Joins}
-
-\begin{command}{\pgfsetbuttcap}
- Sets the line cap to a butt cap. See Section~\ref{section-cap-joins} for an
- explanation of what this is.
-\end{command}
-%
-\begin{command}{\pgfsetroundcap}
- Sets the line cap to a round cap. See again Section~\ref{section-cap-joins}.
-\end{command}
-\begin{command}{\pgfsetrectcap}
- Sets the line cap to a square cap. See again Section~\ref{section-cap-joins}.
-\end{command}
-%
-\begin{command}{\pgfsetroundjoin}
- Sets the line join to a round join. See again Section~\ref{section-cap-joins}.
-\end{command}
-%
-\begin{command}{\pgfsetbeveljoin}
- Sets the line join to a bevel join. See again Section~\ref{section-cap-joins}.
-\end{command}
-%
-\begin{command}{\pgfsetmiterjoin}
- Sets the line join to a miter join. See again Section~\ref{section-cap-joins}.
-\end{command}
-%
-\begin{command}{\pgfsetmiterlimit\marg{miter limit factor}}
- Sets the miter limit to \meta{miter limit factor}. See again
- Section~\ref{section-cap-joins}.
-\end{command}
-
-
-\subsubsection{Graphic Parameter: Dashing}
-
-\begin{command}{\pgfsetdash\marg{list of even length of dimensions}\marg{phase}}
- Sets the dashing of a line. The first entry in the list specifies the
- length of the first solid part of the list. The second entry specifies the
- length of the following gap. Then comes the length of the second solid
- part, following by the length of the second gap, and so on. The
- \meta{phase} specifies where the first solid part starts relative to the
- beginning of the line.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0cm}
- \pgfpathmoveto{\pgfpoint{0mm}{0mm}}
- \pgfpathlineto{\pgfpoint{2cm}{0mm}}
- \pgfusepath{stroke}
- \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.1cm}
- \pgfpathmoveto{\pgfpoint{0mm}{1mm}}
- \pgfpathlineto{\pgfpoint{2cm}{1mm}}
- \pgfusepath{stroke}
- \pgfsetdash{{0.5cm}{0.5cm}{0.1cm}{0.2cm}}{0.2cm}
- \pgfpathmoveto{\pgfpoint{0mm}{2mm}}
- \pgfpathlineto{\pgfpoint{2cm}{2mm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
-
- Use |\pgfsetdash{}{0pt}| to get a solid dashing.
-\end{command}
-
-
-\subsubsection{Graphic Parameter: Stroke Color}
-
-\begin{command}{\pgfsetstrokecolor\marg{color}}
- Sets the color used for stroking lines to \meta{color}, where \meta{color}
- is a \LaTeX\ color like |red| or |black!20!red|. Unlike the |\color|
- command, the effect of this command lasts till the end of the current
- |{pgfscope}| and not till the end of the current \TeX\ group.
-
- The color used for stroking may be different from the color used for
- filling. However, a |\color| command will always ``immediately override''
- any special settings for the stroke and fill colors.
-
- In plain \TeX, this command will also work, but the problem of
- \emph{defining} a color arises. After all, plain \TeX\ does not provide
- \LaTeX\ colors. For this reason, \pgfname\ implements a minimalistic
- ``emulation'' of the |\definecolor|, |\colorlet|, and |\color| commands.
- Only gray-scale and rgb colors are supported. For most cases this turns out
- to be enough.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfsetlinewidth{1pt}
- \color{red}
- \pgfpathcircle{\pgfpoint{0cm}{0cm}}{3mm} \pgfusepath{fill,stroke}
- \pgfsetstrokecolor{black}
- \pgfpathcircle{\pgfpoint{1cm}{0cm}}{3mm} \pgfusepath{fill,stroke}
- \color{red}
- \pgfpathcircle{\pgfpoint{2cm}{0cm}}{3mm} \pgfusepath{fill,stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetcolor\marg{color}}
- Sets both the stroke and fill color. The difference to the normal |\color|
- command is that the effect lasts till the end of the current |{pgfscope}|,
- not only till the end of the current \TeX\ group.
-\end{command}
-
-
-\subsubsection{Graphic Parameter: Stroke Opacity}
-
-You can set the stroke opacity using |\pgfsetstrokeopacity|. This command is
-described in Section~\ref{section-transparency}.
-
-
-\subsubsection{Inner Lines}
-
-When a path is stroked, it is possible to request that it is stroked twice, the
-second time with a different line width and a different color. This is a useful
-effect for creating ``double'' lines, for instance by setting the line width to
-2pt and stroking a black line and then setting the inner line width to 1pt and
-stroking a white line on the same path as the original path. This results in
-what looks like two lines, each of thickness 0.5pt, spaced 1pt apart.
-
-You may wonder why there is direct support for this ``double stroking'' in the
-basic layer. After all, this effect is easy to achieve ``by hand''. The main
-reason is that arrow tips must be treated in a special manner when such
-``double lines'' are present. First, the order of actions is important: First,
-the (thick) main line should be stroked, then the (thin) inner line, and only
-then should the arrow tip be drawn. Second, the way an arrow tip looks
-typically depends strongly on the width of the inner line, so the arrow tip
-code, which is part of the basic layer, needs access to the inner line
-thickness.
-
-Two commands are used to set the inner line width and color.
-
-\begin{command}{\pgfsetinnerlinewidth\marg{dimension}}
- This command sets the width of the inner line. Whenever a path is stroked
- (and only then), it will be stroked normally and, afterward, it is stroked
- once more with the color set to the inner line color and the line width set
- to \meta{dimension}.
-
- In case arrow tips are added to a path, the path is first stroked normally,
- then the inner line is stroked, and then the arrow tip is added. In case
- the main path is shortened because of the added arrow tip, this shortened
- path is double stroked, not the original path (which is exactly what you
- want).
-
- When the inner line width is set to 0pt, which is the default, no inner
- line is stroked at all (not even a line of width 0pt). So, in order to
- ``switch off'' double stroking, set \meta{dimension} to~|0pt|.
-
- The setting of the inner line width is local to the current \TeX\ group and
- \emph{not} to the current \pgfname\ scope.
-
- Note that inner lines will \emph{not} be drawn for paths that are also used
- for clipping. However, this may change in the future, so you should not
- depend on this.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{1cm}{0cm}}
- \pgfsetlinewidth{2pt}
- \pgfsetinnerlinewidth{1pt}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetinnerstrokecolor\marg{color}}
- This command sets the \meta{color} that is to be used when the inner line
- is stroked. The effect of this command is also local to the current \TeX\
- group.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{1cm}{0cm}}
- \pgfsetlinewidth{2pt}
- \pgfsetinnerlinewidth{1pt}
- \pgfsetinnerstrokecolor{red!50}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Arrow Tips on a Path}
-\label{section-tips}
-
-After a path has been drawn, \pgfname\ can add arrow tips at the ends,
-depending on how the |tips| key is set, on whether |stroke| or |clip| are used
-and on whether the path contains closed subpaths. The exact rules when arrow
-tips are added are explained in Section~\ref{section-arrow-tips-where}.
-
-\begin{command}{\pgfsetarrowsstart\marg{start arrow tip specification}}
- Sets the arrow tip kind used at the start of a (possibly curved) path. The
- syntax of the \meta{start arrow specification} is detailed in
- Section~\ref{section-arrow-spec}.
-
- To ``clear'' the start arrow, say |\pgfsetarrowsstart{}|.
- %
-\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}]
-\begin{pgfpicture}
- \pgfsetarrowsstart{Latex[length=10pt]}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1cm}{0cm}}
- \pgfusepath{stroke}
- \pgfsetarrowsstart{Computer Modern Rightarrow}
- \pgfpathmoveto{\pgfpoint{0cm}{2mm}}
- \pgfpathlineto{\pgfpoint{1cm}{2mm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
-
- The effect of this command persists only till the end of the current \TeX\
- scope.
-\end{command}
-
-\begin{command}{\pgfsetarrowsend\marg{end arrow tip specification}}
- Sets the arrow tip kind used at the end of a path.
- %
-\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}]
-\begin{pgfpicture}
- \pgfsetarrowsstart{Latex[length=10pt]}
- \pgfsetarrowsend{Computer Modern Rightarrow}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1cm}{0cm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetarrows\marg{argument}}
- The \meta{argument} can be of the form \meta{start arrow tip
- specification}|-|\meta{end arrow tip specification}. In this case, both the
- start and the end arrow specification are set:
- %
-\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}]
-\begin{pgfpicture}
- \pgfsetarrows{Latex[length=10pt]->>}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1cm}{0cm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
- Alternatively, \meta{argument} can be of the form |[|\meta{arrow keys}|]|.
- In this case, the \meta{arrow keys} will be set for all arrow tips in the
- current scope, see Section~\ref{section-arrow-scopes}.
-\end{command}
-
-\begin{command}{\pgfsetshortenstart\marg{dimension}}
- This command will shortened the start of every stroked path by the given
- dimension. This shortening is done in addition to automatic shortening done
- by a start arrow, but it can be used even if no start arrow is given.
-
- It is usually better to use the |sep| key with arrow tips.
-
- This command is useful if you wish arrows or lines to ``stop shortly
- before'' a given point.
- %
-\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}]
-\begin{pgfpicture}
- \pgfpathcircle{\pgfpointorigin}{5mm}
- \pgfusepath{stroke}
- \pgfsetarrows{Latex-}
- \pgfsetshortenstart{4pt}
- \pgfpathmoveto{\pgfpoint{5mm}{0cm}} % would be on the circle
- \pgfpathlineto{\pgfpoint{2cm}{0cm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetshortenend\marg{dimension}}
- Works like |\pgfsetshortenstart|.
-\end{command}
-
-
-\subsection{Filling a Path}
-\label{section-fill}
-
-Filling a path means coloring every interior point of the path with the current
-fill color. It is not always obvious whether a point is ``inside'' a path when
-the path is self-intersecting and/or consists or multiple parts. In this case
-either the nonzero winding number rule or the even-odd crossing number rule is
-used to decide which points lie ``inside''. These rules are explained in
-Section~\ref{section-rules}.
-
-
-\subsubsection{Graphic Parameter: Interior Rule}
-
-You can set which rule is used using the following commands:
-
-\begin{command}{\pgfseteorule}
- Dictates that the even-odd rule is used in subsequent fillings in the
- current \emph{\TeX\ scope}. Thus, for once, the effect of this command does
- not persist past the current \TeX\ scope.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfseteorule
- \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm}
- \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm}
- \pgfusepath{fill}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetnonzerorule}
- Dictates that the nonzero winding number rule is used in subsequent
- fillings in the current \TeX\ scope. This is the default.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfsetnonzerorule
- \pgfpathcircle{\pgfpoint{0mm}{0cm}}{7mm}
- \pgfpathcircle{\pgfpoint{5mm}{0cm}}{7mm}
- \pgfusepath{fill}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Graphic Parameter: Filling Color}
-
-\begin{command}{\pgfsetfillcolor\marg{color}}
- Sets the color used for filling paths to \meta{color}. Like the stroke
- color, the effect lasts only till the next use of |\color|.
-\end{command}
-
-
-\subsubsection{Graphic Parameter: Fill Opacity}
-
-You can set the fill opacity using |\pgfsetfillopacity|. This command is
-described in Section~\ref{section-transparency}.
-
-
-\subsection{Clipping a Path}
-\label{section-clip}
-
-When you add the |clip| option, the current path is used for clipping
-subsequent drawings. The same rule as for filling is used to decide whether a
-point is inside or outside the path, that is, either the even-odd rule or the
-nonzero rule.
-
-Clipping never enlarges the clipping area. Thus, when you clip against a
-certain path and then clip again against another path, you clip against the
-intersection of both.
-
-The only way to enlarge the clipping path is to end the |{pgfscope}| in which
-the clipping was done. At the end of a |{pgfscope}| the clipping path that was
-in force at the beginning of the scope is reinstalled.
-
-
-\subsection{Using a Path as a Bounding Box}
-\label{section-using-bb}
-
-When you add the |use as bounding box| option, the bounding box of the picture
-will be enlarged such that the path in encompassed, but any \emph{subsequent}
-paths of the current \TeX\ scope will not have any effect on the size of the
-bounding box. Typically, you use this command at the very beginning of a
-|{pgfpicture}| environment. Alternatively, you can use |\pgfresetboundingbox|,
-followed by |\pgfusepath{use as bounding box}| to overrule the picture's
-bounding box completely.
-%
-\begin{codeexample}[]
-Left
-\begin{pgfpicture}
- \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
- \pgfusepath{use as bounding box} % draws nothing
-
- \pgfpathcircle{\pgfpointorigin}{2ex}
- \pgfusepath{stroke}
-\end{pgfpicture}
-right.
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-animations.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-animations.tex
deleted file mode 100644
index e3b8ebca42..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-animations.tex
+++ /dev/null
@@ -1,1492 +0,0 @@
-% 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{Animations}
-\label{section-base-animations}
-
-\begin{pgfmodule}{animations}
- This module contains the basic layer support of animations, which is
- documented in the following.
-\end{pgfmodule}
-
-This section described the basic layer support of animations, the \tikzname\
-support is described in Section~\ref{section-tikz-animations}. As always,
-\tikzname\ mainly converts syntactic constructs (like the special colon or
-quote syntax) to appropriate basic layer commands, which are documented here.
-Note, however, that while many attributes and options are the same on both
-layers, some things are handled differently on the basic layer.
-
-
-\subsection{Overview}
-
-An \emph{animation} changes the way some part of a graphic looks like over
-time. The archetypical animation is, of course, a \emph{movement} of node, but
-a change of, say, the opacity of a path is also an animation. \pgfname\ allows
-you to specify such animations using a set of commands and keys that are
-documented in the following.
-%
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \pgfanimateattribute{opacity}{
- whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
-
-Differently from other packages, the animations created by \pgfname\ are not
-precomputed sequences of pictures that are displayed in rapid succession.
-Rather, an animation created by \pgfname\ consists mainly of an annotation in
-the output that a certain attribute of a certain object should change over time
-in some specific way when the object is displayed. It is the job of the
-document viewer application to actually compute and display the animation.
-Interestingly, this means that animations neither increase the size of the
-output files noticeably nor does it put a special burden on \TeX. The hard and
-complicated calculations are done by the viewer application, not by \TeX\ and
-\pgfname.
-
-Only few viewer applications and formats are currently ``up to the job'' of
-displaying animations. In particular, the popular \textsc{pdf} format does
-\emph{not} allow one to specify animations in this way (one can partly ``fake''
-animations at the high price of including a great number of precomputed
-pictures and using JavaScript in special viewers, but this is really not the
-same thing as what \pgfname\ does). Indeed, currently only the \textsc{svg}
-format allows one to specify animations in a sensible way. Thus, \pgfname's
-animations will only be displayed when \textsc{svg} is used as output format.
-
-Because of the shortcomings of the other formats and, also, for purposes of
-printing and depicting animations in a sequential manner, \pgfname\ also allows
-you to create ``snapshots'' of animations. As an example, the following code
-shows how the same drawing is shown at different ``time snapshots'':
-%
-\begin{codeexample}[
- width=3.9cm,
- preamble={\usetikzlibrary{animations}
-\def\pgfname{\textsc{pgf}}
-}]
-\tikz [make snapshot of=0.5s] \scoped :rotate = { 0s = "0", 2s = "90" }
- \node [draw=blue, very thick] {\pgfname};
-\tikz [make snapshot of=1s] \scoped :rotate = { 0s = "0", 2s = "90" }
- \node [draw=blue, very thick] {\pgfname};
-\tikz [make snapshot of=1.5s] \scoped :rotate = { 0s = "0", 2s = "90" }
- \node [draw=blue, very thick] {\pgfname};
-\tikz [make snapshot of=2s] \scoped :rotate = { 0s = "0", 2s = "90" }
- \node [draw=blue, very thick] {\pgfname};
-\end{codeexample}
-
-
-\subsection{Animating an Attribute}
-
-\subsubsection{The Main Command}
-
-Creating an animation is done using the command |\pgfanimateattribute|, which
-takes a to-be-animated attribute and options specifying the timeline:
-
-\begin{command}{\pgfanimateattribute\marg{attribute}\marg{options}}
- Adds an animation of the \meta{attribute} of a future \emph{object} to the
- current graphic. Attributes are things like the ``fill opacity'' or the
- transformation matrix or the line width.
-
- The \meta{options} are keys that configure how the attribute changes over
- time. Using the |entry| key multiple times, you specify which value the
- chosen attribute should have at different points in time. Unless special
- keys are used, ``outside'' the specified timeline the animation has no
- effect:
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2,2.5},
-]
-\tikz {
- \pgfanimateattribute{opacity}{
- whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
-
- Other keys, like |repeats|, allow you to specify how the animation behaves
- ``as a whole''. These keys are documented later in this section.
-
-
- \medskip
- \textbf{The Attributes}
-
- In detail, the |\pgfanimateattribute| command opens a \TeX-scope, looks up
- the \emph{type} values of the specified \meta{attribute} have (if you wish
- to animate the |opacity| of an object, the type is ``scalar'' meaning that
- entries must be scalar numbers; when you animate the |fill| attribute, the
- type is ``color'' and values must be colors, and so on), and then executes
- the \meta{options} with the path prefix |/pgf/animation|. Finally, an
- appropriate system layer command |\pgfsysanimate...| is called to create
- the actual animation and the scope is closed.
-
- The following \meta{attributes} are permissible:
-
- \begin{tabular}{ll}
- \emph{Attribute} & \emph{Type} \\
- |draw|, |fill| & color \\
- |line width| & dimension \\
- |motion| & scalar \\
- |opacity|, |fill opacity|, |draw opacity| & scalar \\
- |path| & path \\
- |rotate| & scalar \\
- |scale| & scaling \\
- |softpath| & softpath \\
- |translate| & point \\
- |view| & viewbox \\
- |visible| & boolean \\
- |stage| & boolean \\
- |xskew|, |yskew| & scalar \\
- \end{tabular}
-
- These attributes are detailed in Sections
- \ref{section-base-animation-painting}
- to~\ref{section-base-animation-views}, but here is a quick overview:
- %
- \begin{itemize}
- \item |draw| and |fill| refer to the color used to draw (stroke) and
- fill paths in an object, respectively. Typical values for this
- attribute are |red| or |black!10|.
- \item |line width| is, of course, the line width used in an object.
- Typical values are |0.4pt| or |1mm|. Note that you (currently)
- cannot use keys like |thin| or |thick| here, but this may change in
- the future.
- \item |motion| is a slightly special attribute: It allows you to
- specify a path along which the object should be moved (using the
- |along| key). The values given to the |entry| key for this
- attribute refer to a \emph{fraction of the distance along the
- path}. See the |along| key for details.
- \item |opacity| and the variants |fill opacity| and |draw opacity|
- animate the opacity of an object. Allowed values range between 0
- and 1.
- \item |path| allows you to animate a path (it will morph). The
- ``values'' are now paths themselves. See
- Section~\ref{section-base-animation-paths} for details.
- \item |rotate| refers to a rotation of the object. Values for the
- |entry| key are the rotation angles like |0| or |90|.
- \item |scale| refers to the scaling of the object. Values are either
- single scalars values (like |1| or |1.5|) or two numbers separated
- by a comma (like |1,1.5| or |0.5,2|), referring to the $x$-scaling
- and $y$-scaling.
- \item |softpath| is a special case of the |path| attribute, see
- Section~\ref{section-base-animation-paths} once more.
- \item |translate| shifts the object by a certain vector. Values are
- points like |\pgfpoint{1cm}{2cm}|.
- \item |view| allows you to animate the view box of a view, see
- Section~\ref{section-base-animation-views} for details.
- \item |visible| refers to the visibility of an object. Allowed values
- are |true| and |false|.
- \item |stage| is identical to |visible|, but when the object is not
- animated, it will be hidden by default.
- \item |xskew| and |yskew| skew the object. Attributes are angles like
- |0| or |45| or even |90|.
- \end{itemize}
-
-
- \medskip
- \textbf{The Target Object}
-
- As stated earlier, the \meta{options} are used to specify the object whose
- attribute for which an animation should be added to the picture. Indeed,
- you \emph{must} specify the object explicitly using the |whom| key and you
- must do so \emph{before} the object is created. Note that, in contrast, in
- \textsc{svg} you can specify an animation more or less anywhere and then
- use hyper-references to link the animation to the to-be-animated object;
- \pgfname\ insists that you specify the animation before the object. This is
- a bit of a bother in some situations, but it is the only way to ensure that
- \pgfname\ has a fighting chance to attach some additional code to the
- object (which is necessary for almost all animations of the transformation
- matrix).
-
- \begin{key}{/pgf/animation/whom=\meta{id}\opt{|.|\meta{type}}}
- You \emph{must} use this key once which each call of the
- |\pgfanimateattribute| command. The \meta{id} and the optional
- \meta{type} (which is whatever follows the first dot) will be passed to
- |\pgfidrefnextuse|, see that command for details.
- \end{key}
-
- As explained in the introduction of this chapter, an ``animation'' is just
- a bit of special text in the output document asking a viewer application to
- animate the object at some later time. The |\pgfanimateattribute| command
- inserts this special text immediately, even though it refers to an object
- created only later on. Normally, this is not a problem, but the special
- text should be on the same page as the to-be-animated object. To ensure
- this, it suffices to call |\pgfanimateattribute| no earlier than the
- beginning of the |pgfpicture| containing the object.
-
-
- \medskip
- \textbf{Naming the Animation}
-
- You can assign a name to an animation for later (or early) reference. In
- particular, it is possible to begin \emph{another} animation relative to
- the beginning or end of this animation and for referencing this animation
- must be assigned a name. See the |of| and |of next| keys for details.
-
- \begin{key}{/pgf/animation/name=\meta{name}}
- Assigns a name to the animation by which it can be referenced using the
- |of| and |of next| keys in another animation.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={.5,1,1.5,2,2.5,3,3.5,4,4.5,5,5.5,6},
-]
-\tikz [very thick] {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {end, of next = my move animation, delay = 1s},
- entry = {0s}{0}, entry = {2s}{90}, begin snapshot = 3s, }
- \pgfanimateattribute{translate}{
- name = my move animation, whom = node, begin on = {click},
- entry = {0s}{\pgfpointorigin}, entry = {2s}{\pgfpoint{0cm}{-5mm}} }
- \node (node) [fill = blue!20, draw = blue, circle] {Here!};
-}
-\end{codeexample}
- \end{key}
-\end{command}
-
-\begin{command}{\pgfanimateattributecode\marg{attribute}\marg{code}}
- The command works like |\pgfanimateattribute|, only instead of
- \meta{options} you specify some \meta{code} whose job is to setup the
- options.
-\end{command}
-
-
-\subsubsection{Specifying the Timeline}
-
-The core key for specifying how an attribute varies over time is the |entry|
-key:
-%
-\begin{key}{/pgf/animation/entry=\marg{time}\marg{value}}
- You use this key repeatedly to specify the different values that the
- \meta{attribute} should have over time. At the \meta{time} specified, the
- \meta{attribute} will have the value specified as \meta{value}:
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={.5,1,1.5,2},
-]
-\tikz {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {click},
- entry = {0s}{0}, entry = {1s}{90}, entry = {1.1s}{45}, entry = {2s}{90}
- }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
-
- You need to call |entry| once for each time in the timeline for which you
- want to specify a \meta{value} explicitly. Between these times, the values
- get interpolated (see below for details). You need to specify the
- \meta{time}s in non-decreasing order (it is permissible and sometimes also
- necessary to specify the same time twice, namely to create a ``jump'' of
- the value of some attribute).
-
- The \meta{time} is parsed using the command |\pgfparsetime| described
- later.
-
-
- \medskip
- \textbf{Start and end of the timeline.}
- The first and last times of the timeline are a bit special: The timeline
- starts on the first time and the duration of the timeline is the difference
- between the first and last time. ``Starting'' on the start time actually
- means that any beginnings (see the |begin| and |end| keys) get offset by
- the start time; similarly end times are offset by this value.
-
-
- \medskip
- \textbf{Syntax of the values.}
- The syntax of the \meta{value} varies according to the type of the
- \meta{attribute}. In detail, these are:
-
- \begin{tabular}{lp{12cm}}
- \emph{Type} & \emph{Syntax} \\
- color & Standard color syntax like |red| or |black!10| \\
- scalar & A value parsed using |\pgfmathparse| \\
- dimension & A dimension parsed using |\pgfmathparse| \\
- path & A sequence of path construction commands \\
- softpath & A sequence of soft path construction commands \\
- scaling & A scalar value or a pair of scalar values separated by a comma \\
- point & A \pgfname-point like |\pgfpoint{1cm}{5mm}| \\
- viewbox & Two \pgfname-points \\
- boolean & |true| or |false| \\
- \end{tabular}
-
-
- \medskip
- \textbf{Interpolation between key times.}
- You use the |entry| key repeatedly, namely once for each ``key time'',
- which is a time point for which you specify the value of the attribute
- explicitly. Between these key times, the attribute's value is interpolated.
- Normally, this is just a linear interpolation, but you can influence this
- using the following keys, see Section~\ref{section-anim-smooth} for
- details.
-
- \begin{key}{/pgf/animations/exit control=\marg{time fraction}\marg{value fraction}}
- Same as |/tikz/animate/options/exit control|.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}},
-]
-\tikz {
- \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
- \pgfanimateattribute{translate}{
- whom = node, begin on = {click},
- exit control={1}{0},
- entry = {0s}{\pgfpointorigin},
- linear, % revert to default
- entry = {1s}{\pgfpoint{0cm}{-5mm}},
- entry control={0}{1},
- entry = {2s}{\pgfpoint{0cm}{-10mm}} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/animations/entry control=\marg{time fraction}\marg{value fraction}}
- Works like |exit control|.
- \end{key}
-
- \begin{key}{/pgf/animations/linear}
- A shorthand for |exit control={0}{0}, entry control={1}{1}|. This will
- (re)install a linear curve.
- \end{key}
-
- \begin{key}{/pgf/animations/stay}
- Same as |/tikz/animate/options/stay|.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2,2.5},
-]
-\tikz {
- \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
- \pgfanimateattribute{translate}{
- whom = node, begin on = {click},
- entry = {0s}{\pgfpointorigin},
- stay,
- entry = {1s}{\pgfpoint{0cm}{-5mm}},
- linear,
- entry = {2s}{\pgfpoint{0cm}{-10mm}},
- entry = {3s}{\pgfpoint{0cm}{-15mm}} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/animations/jump}
- Same as |/tikz/animate/options/jump|.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
- \pgfanimateattribute{translate}{
- whom = node, begin on = {click},
- entry = {0s}{\pgfpointorigin},
- jump,
- entry = {1s}{\pgfpoint{0cm}{-1cm}},
- linear,
- entry = {2s}{\pgfpoint{0cm}{-2cm}} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- \end{key}
-\end{key}
-
-When the time of an animation lies outside the timeline specified by the
-|entry| keys, no animation is present. This means that the value of the
-attribute is the object's scope is used instead. Using the following key, you
-can set this value directly:
-
-\begin{key}{/tikz/animations/base=\meta{value}}
- The syntax of the \meta{value} is the same as for the |entry| key. The
- \meta{value} is installed as the value of the object's attribute whenever
- the timeline is not active. This makes it easy to specify the value of an
- attribute when the animation is ``not running''.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={-1,0,1,2,3},
-]
-\tikz {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {click},
- entry = {0s}{90}, entry = {2s}{180},
- base = 45
- }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- %
-\end{key}
-
-It may happen that there is more than one timeline active that is ``trying to
-modify'' a given attribute. In this case, the following rules are used to
-determine, which timeline ``wins'':
-%
-\begin{enumerate}
- \item If no animation is active at the current time (all animation either
- have not yet started or they have already ended), then the base value
- given in the animation encountered last in the code is used. (If there
- are no base values, the attribute is taken from the surrounding scope.)
- \item If there are several active animations, the one that has started last
- is used and the its value is used.
- \item If there are several active animations that have started at the same
- time, the one that comes last in the code is used.
-\end{enumerate}
-
-Note that these rules do not apply to transformations of the canvas since these
-are always additive (or, phrased differently, they are always all active and
-the effects accumulate).
-
-\begin{command}{\pgfparsetime\marg{time}}
- This command works like |\pgfmathparse| (indeed, it calls is internally),
- but returns the result in the macro |\pgftimeresult| rather than
- |\pgfmathresult|. Furthermore, the following changes are installed:
- %
- \begin{itemize}
- \item The postfix operator |s| is added, which has no effect.
- \item The postfix operator |ms| is added, which divides a number by
- 1000, so |2ms| equals 0.002s.
- \item The postfix operator |min| is added, which multiplies a number by
- 60.
- \item The postfix operator |h| is added, which multiplies a number by
- 3600.
- \item The infix operator |:| is redefined, so that it multiplies its
- first argument by 60 and adds the second. This implies that |1:20|
- equals 80s and |01:00:00| equals 3600s.
- \item The parsing of octal numbers is switched off to allow things like
- |01:08| for 68s.
- \end{itemize}
-\end{command}
-
-
-\subsubsection{``Anti-Animations'': Snapshots}
-
-There are a number of situations in which you want the ``opposite'' of an
-animation to happen: You want to create a ``still image''. For instance, when
-you want to print an animation you will typically wish to show one or more
-``temporal snapshots'' of the animation. Also, you may wish to specify a value
-for an object when it is \emph{not} being animated.
-
-Let us start with creating a snapshot:
-
-\begin{command}{\pgfsnapshot\marg{time}}
- When this command is used inside a \TeX\ scope, the behavior of
- |\pgfanimateattribute| changes: Instead of adding an animation to the
- object and the attribute, the object's attribute is set to value it would
- have during the animation at time \meta{time}. Note that when this command
- is used in a \TeX\ scope, no animation is created and no support by the
- driver is needed (so, it works with \textsc{pdf}).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
-\tikz [make snapshot of=1s,
- animate = { myself: = {
- :rotate = { 0s = "0", 2s = "90" },
- :color = { 0s = "red", 2s = "green" },
- :line width = { 0s = "0mm", 4s = "4mm" }
- }}]
- \node [fill=black!20, draw] { Node };
-\end{codeexample}
-
-
- \medskip\textbf{Timing and Events.}
- The timeline of an animation normally starts at a ``moment |0s|'' and the
- \meta{time} is considered relative to this time. For instance, if a
- timeline contains, say, the settings |entry={2s}{0}| and |entry={3s}{10}|
- and \marg{time} is set to |2.5s|, then the value the attribute will get is
- 5.
-
- It is, however, also possible to specify that animations begin and end at
- certain times relative to events like a |click| event. \emph{These events
- are not relevant with respect to snapshots.} However, there is one key that
- allows you to specify the beginning of the snapshot timeline:
- %
- \begin{key}{/tikz/animations/begin snapshot=\meta{begin time}}
- When this key is used inside the options of |\pgfanimateattribute|,
- with respect to snapshots, the timeline begins at \meta{begin time}.
- This means that, if the snapshot time is set to \meta{time} and the
- beginning of the snapshot's timeline is set to \meta{begin time}, the
- attribute is set to the value of the timeline at time $\meta{time} -
- \meta{begin time}$.
-
- The idea is that when you make a snapshot of several animations and all
- of them have started at different times because of different events,
- you use |begin snapshot| with each object and attribute to directly
- specify when these different events have happened.
- \end{key}
-
- Note that the |end| keys have no effect with snapshots, that is, with a
- snapshot all animations always run till the end of the timeline (which may
- or may not be ``forever'').
-
-
- \medskip\textbf{Limitations.}
- For snapshots, the value an animation has at time \meta{time} must be
- computed by \TeX. While in many cases this is easy to achieve, in some
- cases this is not trivial such as a timeline for a path with repeats plus
- smoothing via splines. An additional complication is the fact that an
- animation may be specified at a place far removed from the actual
- to-be-animated object. For these reasons, certain limitations apply to
- snapshots:
- %
- \begin{itemize}
- \item The |begin| and |begin on| keys have no effect (but
- |begin snapshot| has one.
- \item The |end| and |end on| keys have no effect.
- \item The |current value| may not be used in a timeline (since
- \pgfname\ cannot really determine this value).
- \item The |accumulating| specification may not be used with paths,
- views, or motions.
- \item Since the timing computations are done using \TeX\ code, they are
- not necessarily stable. For instance, when a time interval is very
- small and there are many repeats or when a spline is very
- complicated, the calculated values may not be fully accurate.
- \end{itemize}
-\end{command}
-
-\begin{command}{\pgfsnapshotafter\marg{time}}
- This command works exactly like |\pgfsnapshot| only the ``moment'' that
- \meta{time} refers to is conceptually $\meta{time} + \epsilon$: When
- timeline specifies several values for \meta{time}, this command will select
- the last value at \meta{time}, while |\pgfsnapshot| will select the first
- value at \meta{time}. Similarly, when a timeline ends at \meta{time},
- |\pgfsnapshot| will select the last value of the timeline while
- |\pgfsnapshotafter| will not apply the animation any more:
- %
-\begin{codeexample}[preamble={\usepgfmodule{animations}}]
-\foreach \t in {0,1,2,3,4} {
- \pgfsnapshot{\t}
- \tikz :rotate = { 0s = "0", 2s = "90", 2s = "180", 4s = "270" }
- \node [draw=blue, very thick] {f}; }
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usepgfmodule{animations}}]
-\foreach \t in {0,1,2,3,4} {
- \pgfsnapshotafter{\t}
- \tikz :rotate = { 0s = "0", 2s = "90", 2s = "180", 4s = "270" }
- \node [draw=blue, very thick] {f}; }
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Animating Color, Opacity, Visibility, and Staging}
-\label{section-base-animation-painting}
-
-\begin{animateattribute}{fill}
- You can animate the color of the target object of an animation using the
- attributes |fill| or |draw|, which animate the fill color and the drawing
- (stroking) color, respectively. To animate both the fill and draw color,
- you need to create two animations, one for each.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \pgfanimateattribute{fill}{
- whom = node.background, begin on = {click},
- entry = {0s}{white}, entry = {2s}{red} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- %
-\end{animateattribute}
-
-\begin{animateattribute}{draw}
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \pgfanimateattribute{draw}{
- whom = node.background, begin on = {click},
- entry = {0s}{white}, entry = {2s}{red} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
-\end{animateattribute}
-
-When the target of a color animation is a scope, you animate the color ``used
-in this scope'' for filling or stroking. However, when an object inside the
-scope has its color set explicitly, this color overrules the color of the
-scope:
-%
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
- animation bb={(1.5,-0.75) rectangle (3,0.75)},
-]
-\tikz {
- \pgfanimateattribute{fill}{
- whom = example, begin on = {click, of next=node},
- entry = {0s}{white}, entry = {2s}{red} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
- \begin{scope}[name = example]
- \fill (1.5,-0.75) rectangle ++ (1,1);
- \fill [blue] (2,-0.25) rectangle ++ (1,1);
- \end{scope}
-}
-\end{codeexample}
-
-Note that in certain cases, a graphic scope may contain graphic objects with
-their colors set explicitly ``in places where you do not expect it'': In
-particular, a node normally consists at least of a background path and a text.
-For both the text and for the background path, colors will be set for the text
-and also for the path explicitly. This means that when you pick the fill
-attribute of a node as the target of an animation, you will \emph{not} animate
-the color of the background path in case this color has been set explicitly.
-Instead, you must choose the background path of the node as the target of the
-animation. Fortunately, this is easy to achieve since when the background path
-of a node is created, the identifier type is set to |background|, which in turn
-allows you to access it as \meta{node}|.background| through the |whom| key.
-
-The text of a node also gets it color set explicitly, which means that a change
-of the node's scope's color has no effect on the text color. Instead, you must
-choose \meta{name}|.text| as the target (or, if the node has more parts, use
-the name of the part as the identifier type instead of |text|).
-%
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
- animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
-]
-\tikz {
- \pgfanimateattribute{fill}{
- whom = example, begin on = {click, of next=node},
- entry = {0s}{white}, entry = {2s}{red} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
- \node at (2,0) (example) [fill = blue!20, circle] {No effect}; }
-\end{codeexample}
-
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
- animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
-]
-\tikz {
- \pgfanimateattribute{fill}{
- whom = example.background, begin on = {click, of next=node},
- entry = {0s}{white}, entry = {2s}{red} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
- \node at (2,0) (example) [fill = blue!20, circle] {Effect}; }
-\end{codeexample}
-
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
- animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
-]
-\tikz {
- \pgfanimateattribute{fill}{
- whom = example.text, begin on = {click, of next=node},
- entry = {0s}{white}, entry = {2s}{red} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
- \node at (2,0) (example) [fill = blue!20, circle, font=\huge] {Text}; }
-\end{codeexample}
-
-Similarly to the color, you can also set the opacity used for filling and for
-drawing. You specify the opacity using a number between 0 (transparent) and 1
-(opaque).
-
-\begin{animateattribute}{fill opacity}
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \pgfanimateattribute{fill opacity}{
- whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
-\end{animateattribute}
-
-\begin{animateattribute}{draw opacity}
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \pgfanimateattribute{draw opacity}{
- whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
-\end{animateattribute}
-
-\begin{animateattribute}{opacity}
- Unlike colors, where there is no joint attribute for filling and stroking,
- there is a single |opacity| attribute in addition to the above two
- attributes. If supported by the driver, it treats the graphic object to
- which it is applied as a transparency group. In essence, ``this attribute
- does what you want'' at least in most situations.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \pgfanimateattribute{opacity}{
- whom = node, begin on = {click}, entry = {0s}{1}, entry = {2s}{0} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- %
-\end{animateattribute}
-
-\begin{animateattribute}{visible}
- The difference between the |visible| attribute and an opacity of |0| is
- that an invisible object cannot be clicked and does not need to be
- rendered. The (only) two possible values for this attribute are |false| and
- |true|.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={1,2,3,4},
-]
-\tikz {
- \pgfanimateattribute{visible}{
- whom = node, begin on = {click}, entry = {0s}{false}, entry = {2s}{false} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- %
-\end{animateattribute}
-
-\begin{animateattribute}{stage}
- This attribute is the same as the |visible| attribute, only |base=false| is
- set by default. This means that the object is \emph{only} visible when you
- explicitly during the time the entries are set to |true|. The idea behind
- the name ``stage'' is that the object is normally ``off stage'' and when
- you explicitly set the ``stage attribute'' to |true| the object ``enters''
- the stage and ``leaves'' once more when it is no longer ``on stage''.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={-1,0,1,2,3},
- animation bb={(1.3,-0.7) rectangle (2.7,0.7)},
-]
-\tikz {
- \pgfanimateattribute{stage}{
- whom = example, begin on = {click, of next=node},
- entry = {0s}{true}, entry = {2s}{true} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
- \node at (2,0) (example) [fill = blue!20, circle] {Effect}; }
-\end{codeexample}
- %
-\end{animateattribute}
-
-
-\subsection{Animating Paths and their Rendering}
-\label{section-base-animation-paths}
-
-You can animate the appearance of a path in the following ways:
-
-\begin{animateattribute}{line width}
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [very thick] {
- \pgfanimateattribute{line width}{
- whom = node, begin on = {click}, entry = {0s}{1pt}, entry = {2s}{5mm} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
-}
-\end{codeexample}
- %
- The possible values passed to the |entry| key are, of course, dimensions.
-\end{animateattribute}
-
-\begin{animateattribute}{dash}
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \pgfanimateattribute{dash}{
- whom = node, begin on = {click}, entry = {0s}{{{10pt}{1pt}}{0pt}},
- entry = {2s}{{{1pt}{10pt}}{0pt}} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \pgfanimateattribute{dash}{
- whom = node, begin on = {click}, entry = {0s}{{{1cm}{1pt}}{0pt}},
- entry = {2s}{{{1cm}{1pt}}{1cm}} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- %
- To specify the dash pattern, you specify a sequence of ``on and off''
- dimensions; see |\pgfsetdash| for details. Note that you \emph{must}
- specify the same number of elements in all patterns of a timeline: You
- cannot specify that the dash pattern for |1s| is |{1pt}{2pt}| and for |2s|
- is |{1pt}{3pt}{2pt}| since the number of elements would differ. In
- particular, you cannot (sensibly) use |current value| for the first entry
- since this corresponds to an empty dash pattern (even when you have
- specified a dash pattern for the target object: this pattern will not be
- attached to the to-be-animated scope or object but to a surrounding scope
- and, thus, the to-be-animated scope will not have any dash pattern
- installed).
-\end{animateattribute}
-
-\begin{animateattribute}{path}
- You can animate the path itself:
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \pgfanimateattribute{path}{
- whom = node.background.path, begin on = {click, of next=node},
- entry = {0s}{\pgfpathellipse{\pgfpointorigin}
- {\pgfpointxy{1}{0}}{\pgfpointxy{0}{1.5}}},
- entry = {2s}{\pgfpathellipse{\pgfpointxy{.5}{0}}
- {\pgfpointxy{.5}{.5}}{\pgfpointxy{0.25}{.25}}}}
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- %
- The path is specified by giving path construction commands as in the above
- example. They will be executed in a special protected scope to ensure that
- they have only little side effects.
-
- As for the dash pattern, you must ensure that all paths in the timeline
- have the same structure (same sequence of path construction commands); only
- the coordinates may differ. In particular, you cannot say that the path at
- |1s| is a rectangle using |\pgfpathrectangle| and at |2s| is a circle using
- |\pgfpathcircle|. Instead, you would have to ensure that at both times that
- path consists of appropriate Bézier curves.
-
- Unlike the dash pattern, the to-be-animated object is, indeed, the path
- itself and not some special scope. This means that you can use the
- |current value| for the start path. However, this also means that you
- really must pick \emph{the path object} as the target of the animation. In
- conjunction with \tikzname, this will be an object of type |path| as in the
- above example.
-
- When a path is animated, it cannot have ``normal'' arrows attached to it
- since due to the way \pgfname\ adds arrow tips to paths, these would not
- ``move along'' with the path (you get an error message if you try).
- However, it still \emph{is} possible to add arrow tips to an animated path,
- only you need to use the |arrows| key described next.
-
- Concerning the bounding box computation of the path, a bounding box for all
- paths mentioned for any time point is used as the overall bounding box.
-\end{animateattribute}
-
-\begin{key}{/pgf/animation/arrows=\meta{start tip spec}|-|\meta{end tip spec}}
- This key specifies arrow tips during the animation of the path. The syntax
- for the arrow tips is the same syntax as the |\pgfsetarrow| command or
- \tikzname's |arrows| key. The specified start and end arrow tips are
- rendered as ``markers'', which are added to the path \emph{only} during the
- animation. The markers are rotated along with the path in exactly the same
- way as normal arrow tips would be. To be precise, the rules used for the
- computation of where arrow tips go and in which direction they head is not
- always the same for ``static'' arrow tips (arrow tips added to a normal
- path) and the ``dynamic'' arrow tips based on markers; namely when the
- paths are very short or closed. For this reason, you should add arrow tips
- to animated paths only when the paths are ``nice and simple'' in the sense
- that they consist of a single segment whose ends are reasonably long.
-
- In addition to adding the arrow tips to the path during the animation, the
- path gets shortened as necessary to compensate for the extend of the arrow
- tips. However, for this to work, the arrow tips have to be specified before
- path values are specified (since the shortening is done immediately when a
- path value is parsed).
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0,1,2,3,4},
- animation bb={(0.9,-0.1)rectangle(2.1,1.1)},
-]
-\tikz {
- \pgfanimateattribute{path}{
- whom = p.path, begin on = {click, of next=node}, arrows = ->,
- entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}}
- \pgfpathlineto{\pgfpoint{2cm}{1cm}}},
- entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{2cm}{5mm}}}}
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
- \draw [very thick, blue, name=p] (1,0.5) -- (2,0.5);
-}
-\end{codeexample}
-
- Note that the markers that visualize the arrow tips are rendered only once
- per animation. In consequence, ``bending'' arrow tips cannot be rendered
- correctly: As a path ``morphs'' a bend arrow tip needs not only to rotate
- along, but must actually ``bend along'', which is not supported (neither by
- \pgfname\ nor by \textsc{svg}).
-
- As pointed out earlier, an animated path cannot have ``static'' arrow tips.
- However, when you specify a |base| value, which is the path used whenever
- there is no active animation, \emph{will} use the arrow tips. As a result,
- you can use this to animate a path with an arrow tip:
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0,1,2,3,4},
- animation bb={(0.9,-0.1)rectangle(2.1,1.1)},
-]
-\tikz {
- \pgfanimateattribute{path}{
- whom = p.path, begin on = {click, of next=node}, arrows = ->,
- base = {\pgfpathmoveto{\pgfpoint{1cm}{5mm}}
- \pgfpathlineto{\pgfpoint{2cm}{5mm}}},
- entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}}
- \pgfpathlineto{\pgfpoint{2cm}{1cm}}},
- entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{2cm}{5mm}}}}
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
- \draw [very thick, blue, name=p];
-}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/animation/shorten >=\meta{dimension}}
- Just like the normal \tikzname\ key |shorten >|, this key specifies an
- extra shortening of to-be-animated paths. Whenever a path is parsed as a
- value for a path animation, it gets shortened at the end by the
- \meta{dimension} (and, additionally, by the length of the attached arrow
- tip). Just like the |arrows| key, this key must be given before the path
- entries are specified.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0,1,2,3,4},
- animation bb={(0.9,-0.1)rectangle(2.1,1.1)},
-]
-\tikz {
- \pgfanimateattribute{path}{
- whom = p.path, begin on = {click, of next=node}, arrows = ->,
- shorten > = 2mm,
- base = {\pgfpathmoveto{\pgfpoint{1cm}{5mm}}
- \pgfpathlineto{\pgfpoint{2cm}{5mm}}},
- entry = {1s}{\pgfpathmoveto{\pgfpoint{1cm}{0cm}}
- \pgfpathlineto{\pgfpoint{2cm}{1cm}}},
- entry = {3s}{\pgfpathmoveto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{2cm}{5mm}}}}
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
- \draw (0.9,-0.1) grid (2.1,1.1);
- \draw [help lines] (0.9,-0.1) grid[step=1mm] (2.1,1.1);
- \draw [very thick, blue, name=p];
-}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/animation/shorten <=\meta{dimension}}
- Works like |shorten >|.
-\end{key}
-
-
-\subsection{Animating Transformations and Views}
-\label{section-base-animation-views}
-
-In order to animate the canvas transformation matrix, you do not animate an
-attribute called ``|transform|'' (or something similar). Rather, there are
-several keys that all manipulate the canvas transformation matrix in different
-ways. These keys, taken in appropriate combination, allow you to achieve any
-particular canvas transformation matrix. All keys that animate the
-transformation matrix \emph{always} accumulate.
-
-Some, but not all, of these keys also have an effect on the bounding box
-computation: The |translate| and |motion| attribute change the computation of
-the bounding box in such a way that it is chosen large enough as to include the
-whole picture during all stages of the animation (however, if there are
-multiple transformations active at the same time, the computation may not be
-correct). In contrast, |scale|, |rotate| and |skew| animations change the
-canvas transformation, but are ignored for the bounding box computation. When
-in doubt, please set the bounding box explicitly.
-
-Let us start with the basic keys that allow you to change the canvas
-transformation matrix directly:
-
-\begin{animateattribute}{scale}
- The |scale| attribute adds an animation of the scaling:
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [very thick] {
- \pgfanimateattribute{scale}{
- whom = node, begin on = {click},
- entry = {0s}{0.5}, entry = {2s}{0.75,1.5} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
-}
-\end{codeexample}
- %
- The values passed to the |entry| key must either be single scalar values or
- a pair of such numbers separated by a comma (which then refer to the $x$-
- and $y$-scaling).
-\end{animateattribute}
-
-\begin{animateattribute}{rotate}
- The |rotate| key adds an animation of the rotation:
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [very thick] {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {click},
- entry = {0s}{45}, entry = {2s}{90} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
-}
-\end{codeexample}
- %
- The values are scalar values representing a rotation in degrees.
-\end{animateattribute}
-
-\begin{animateattribute}{xskew}
- The |xskew| and |yskew| keys (and also |skew x| and |skew y|, which are
- aliases) add an animation of the skew (given in degrees, not as a slant):
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [very thick] {
- \pgfanimateattribute{xskew}{
- whom = node, begin on = {click}, entry = {0s}{0}, entry = {2s}{45} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
-}
-\end{codeexample}
- %
- The values are scalar values.
-\end{animateattribute}
-
-\begin{animateattribute}{yskew}
- See |xskew|.
-\end{animateattribute}
-
-\begin{animateattribute}{skew x}
- An alias of |xskew|.
-\end{animateattribute}
-
-\begin{animateattribute}{skew y}
- An alias of |yskew|.
-\end{animateattribute}
-
-\begin{animateattribute}{translate}
- The |translate| key adds an animation of the translation (shift):
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [very thick] {
- \pgfanimateattribute{translate}{
- whom = node, begin on = {click},
- entry = {0s}{\pgfpointorigin}, entry = {2s}{\pgfpoint{5mm}{-5mm}} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
-}
-\end{codeexample}
- %
- The values are \pgfname-points.
-
- Unlike for the previous canvas transformations, for this key the bounding
- box computation is changed: All points in the to-be-animated scope do not
- only contribute to the normal bounding box, but they also contribute
- shifted by all points in the entry list. The effect is that a bounding box
- is computed that encompasses the animated scope at all stages.
-\end{animateattribute}
-
-For all of these attributes, the following key is of importance:
-%
-\begin{key}{/pgf/animation/origin=\meta{pgf point}}
- An animation of the canvas transformation is added to all other
- transformations from surrounding or interior scopes. This means that, in
- particular, the origin of a canvas transformation is, by default, the
- origin of the canvas of the scope surrounding the transformation object.
-
- For some canvas animations, like a rotation or a scaling, you will
- typically wish to use a different origin (like the center of an object that
- is to be rotated or scaled). You can achieve this effect by surrounding the
- object by a scope that shifts the canvas to the desired origin, followed by
- a scope whose transformation matrix you animate, followed by a scope that
- shifts back the canvas.
-
- The |origin| key simplifies this process by allowing you to specify the
- origin of the transformation directly. Internally, however, all this key
- does is to create the above-mentioned scopes with the necessary shifts.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [very thick] {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {click},
- origin = \pgfpoint{-5mm}{0mm}, entry = {0s}{0}, entry = {2s}{90} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!};
-}
-\end{codeexample}
- %
-\end{key}
-
-\begin{animateattribute}{motion}
- A second way of changing the canvas transformation matrix is to use the
- |motion| attribute:
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [very thick] {
- \pgfanimateattribute{motion}{
- whom = node, begin on = {click},
- along = \pgfpathcircle{\pgfpointorigin}{5mm},
- entry = {0s}{.25}, entry = {2s}{.5} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
-\end{codeexample}
-
- Just like the |translate| attribute, this key also changes the bounding box
- computation.
- %
- \begin{key}{/pgf/animation/along=\meta{path}}
- This key must be used with |motion| attribute to specify a path along
- which the transformation matrix will be ``moved'' (that is, a shift
- transformation will be added to the different points on the path).
-
- The values passed to the |entry| key specify fractions of the distance
- along the \meta{path}. That means, when you provide a value of |0|, you
- reference the start point of the path, a value of |1| references the
- end of the path and |0.5| referenced the point halfway along the path.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.25,0.5,0.75,1,1.25,1.5,1.75,2,2.25,2.5},
-]
-\tikz [very thick] {
- \pgfanimateattribute{motion}{
- whom = node, begin on = {click},
- along = \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{0mm}{5mm}},
- entry = {0s}{0}, entry = {1s}{0.5}, entry = {2s}{0.25}, entry={3s}{1} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/animation/rotate along=\meta{Boolean} (default true)}
- When set to |true|, the |along| key additionally adds a rotation that
- varies in such a way that a tangent to the path always points right.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [very thick] {
- \pgfanimateattribute{motion}{
- whom = node, begin on = {click},
- rotate along = true,
- along = \pgfpathmoveto {\pgfpointorigin}
- \pgfpathcurveto{\pgfpoint{5mm}{0cm}}{\pgfpoint{5mm}{0cm}}
- {\pgfpoint{5mm}{5mm}},
- entry = {0s}{0}, entry = {2s}{1} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
-\end{codeexample}
- \end{key}
-\end{animateattribute}
-
-The final method of changing the transformation matrix is to animate a
-\emph{view.}
-
-\begin{animateattribute}{view}
- A view is a canvas transformation that shifts and scales the canvas in such
- a way that a certain rectangle ``matches'' another rectangle: The idea is
- that you ``look through'' a ``window'' (the view) and ``see'' a certain
- area of the canvas. View animation do not allow you to do anything that
- cannot also be done using the |translate| and |scale| keys in combination,
- but it often much more natural to animate which area of a graphic you wish
- to see than to compute and animate a scaling and shift explicitly.
-
- In order to use a view, you first need to create a view, which is done
- using a |{pgfviewboxscope}|, see Section~\ref{section-base-view}, which is
- used by the |views| library internally. You can then animate the view using
- the |view| attribute. The values passed to the |entry| key must be two
- \pgfname-points, each surrounded by parentheses.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}
-\usetikzlibrary{views}},
- animation list={0.5,1,1.5,2},
- animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
-]
-\tikz [very thick] {
- \pgfanimateattribute{view}{
- whom = me.view, begin on = {click, of next=node}, freeze at end,
- entry = {0s}{{\pgfpoint{0mm}{0mm}}{\pgfpoint{20mm}{20mm}}},
- entry = {2s}{{\pgfpoint{10mm}{10mm}}{\pgfpoint{15mm}{15mm}}} }
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-
- \draw [green!50!black] (1.2,-0.8) rectangle (2.7,0.8);
- \begin{scope}[name = me, view = {(0,0) (2,2) at (1.2,-0.8) (2.7,0.8)}]
- \draw [red] (10mm,10mm) rectangle (15mm,15mm);
- \node at (10mm,10mm) [circle, fill=red, text=white, font=\tiny] {red};
- \end{scope}
-}
-\end{codeexample}
-
-\begin{codeexample}[
- width=2cm,
- preamble={\usepgfmodule{animations}
-\usetikzlibrary{views}},
-]
-\tikz [very thick] {
- \pgfanimateattribute{view}{
- whom = me.view, begin on = {click, of next=n1}, freeze at end,
- entry = {0s}{\pgfpoint{0mm}{0mm}}{\pgfpoint{2cm}{2cm}},
- entry = {2s}{{\pgfpoint{5mm}{5mm}}{\pgfpoint{15mm}{20mm}}} }
- \pgfanimateattribute{view}{
- whom = me.view, begin on = {click, of next=n2}, freeze at end,
- entry = {0s}{\pgfpoint{0mm}{0mm}}{\pgfpoint{2cm}{2cm}},
- entry = {2s}{{\pgfpoint{10mm}{10mm}}{\pgfpoint{15mm}{15mm}}} }
- \node (n1) at (0,0) [fill = blue!20, draw = blue, circle] {Zoom blue};
- \node (n2) at (2,0) [fill = blue!20, draw = blue, circle] {Zoom red};
-
- \draw [green!50!black] (4,0) rectangle (6,2);
- \begin{scope}[name = me, view = {(0,0) (2,2) at (4,0) (6,2)}]
- \draw [blue] (5mm,5mm) rectangle (15mm,20mm);
- \node at (5mm,5mm) [circle, fill=blue, text=white] {blue};
-
- \draw [red] (10mm,10mm) rectangle (15mm,15mm);
- \node at (10mm,10mm) [circle, fill=red, text=white, font=\tiny] {red};
- \end{scope}
-}
-\end{codeexample}
- %
-\end{animateattribute}
-
-
-\subsection{Commands for Specifying Timing: Beginnings and Endings}
-
-Using the |entry| key repeatedly, you specify a timeline: The \meta{time} used
-with the first use of the |entry| key in a timeline is the start time and the
-\meta{time} in the last |entry| key is the stop time. However, this leaves open
-then question of when the whole timeline is to be started: The moment the
-document is opened? When the page is displayed? When the user scrolls to the
-to-be-animated object? When some other object is clicked? The key |begin|, and
-also the key |end|, allow you to specify answers to these questions.
-
-\begin{key}{/pgf/animation/begin=\meta{time}}
- This key specifies when the ``moment |0s|'' should be relative to the
- moment when the current graphic is first displayed. You can use this key
- multiple times, in this case the timeline is restarted for each of the
- times specified (if it is already running, it will be reset). If no |begin|
- key is given at all, the effect is the same as if |begin=0s| had been
- specified.
-
- It is permissible to set \meta{time} to a negative value.
-\end{key}
-
-\begin{key}{/pgf/animation/end=\meta{time}}
- This key will truncate the timeline so that it ends \meta{time} after the
- display of the graphic, provided the timeline begins before the specified
- end time. For instance, if you specify a timeline starting at 2\,s and
- ending at 5\,s and you set |begin| to 1\,s and |end| to 4\,s, the timeline
- will run, relative to the moment when the graphic is displayed from 3\,s to
- 4\,s.
- %
-\begin{codeexample}[preamble={\usepgfmodule{animations}},width=3cm]
-\tikz [very thick] {
- \pgfanimateattribute{rotate}{
- whom = node, begin = 2s, end = 4s,
- entry = {1s}{0}, entry = {2s}{90}, entry = {3s}{180}, entry = {4s}{270} }
- \node (node) [fill = blue!20, draw = blue, circle] {Turn after 3s!}; }
-\end{codeexample}
- %
-\end{key}
-
-It is not immediately clear what should happen with the attribute of an object
-when an animation ends: Should it revert to its original value ``as if there
-had never been an animation'' or should it ``stay at the last value''? The
-following key governs what should happen:
-
-\begin{key}{/pgf/animation/freeze at end=\meta{true or false} (default true, initially false)}
- When set to |true|, whenever a timeline ends (either because the last time
- of timeline has been reached or because an |end| or |end of| key have ended
- it prematurely), the last value the attribute had because of the animation
- ``stays put''. When set to |false|, which is the initial value, once an
- animation ends, its effect will be removed ``as if it never happened''.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0,1,2,3,4},
-]
-\tikz [very thick] {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {click}, freeze at end = false,
- entry = {0s}{0}, entry = {2s}{90} }
- \node (node) [fill = blue!20, draw = blue, circle] {Here!}; }
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={0,1,2,3,4},
-]
-\tikz [very thick] {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {click}, freeze at end,
- entry = {0s}{0}, entry = {2s}{90} }
- \node (node) [fill = blue!20, draw = blue, circle] {Here!}; }
-\end{codeexample}
- %
-\end{key}
-
-Instead of specifying the beginning of the timeline relative to the moment to
-to-be-animated graphic is displayed, you can also set the ``moment |0s|'' to
-the moment a specific \emph{event} happens using the following key:
-
-\begin{key}{/pgf/animation/begin on=\meta{options}}
- Has the same effect as |/tikz/animate/option/begin on|, see
- Section~\ref{section-anim-begin-end}.
-\end{key}
-
-When you use |begin on| to start an animation when a certain event is
-triggered, it is not clear what should happen when the event is triggered
-\emph{again}. Should this be ignored completely? Should it only be ignored
-while the animation is running? The following key allows you to specify when
-should happen:
-
-\begin{key}{/pgf/animation/restart=\meta{choice} (default true)}
- Has the same effect as |/tikz/animate/option/restart|, see
- Section~\ref{section-anim-begin-end}.
-\end{key}
-
-Just like |begin on| specifies when a timeline begins relative to some event,
-the |end on| allows you to stop is early when some event happens:
-
-\begin{key}{/pgf/animation/end on=\meta{options}}
- Works exactly like |begin on|, one possible end of the timeline is
- specified using the \meta{options}.
-\end{key}
-
-
-\subsection{Commands for Specifying Timing: Repeats}
-
-Normally, a timeline is displayed once and then ends. You can, however, request
-that the timeline should be repeated a certain number of times or indefinitely.
-
-\begin{key}{/pgf/animation/repeats=\meta{specification}}
- Use this key to specify that the timeline animation should repeat at the
- end. The \meta{specification} must consist of two parts, each of which may
- be empty. The first part is one of the following:
- %
- \begin{itemize}
- \item Empty, in which case the timeline repeats forever.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={1,2,3,4,5},
-]
-\tikz [very thick] {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {click}, repeats,
- entry = {0s}{0}, entry = {2s}{90} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
-\end{codeexample}
- %
- \item A \meta{number} (like |2| or |3.25|), in which case the timeline
- repeats \meta{number} times.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={1,2,3,4,5},
-]
-\tikz [very thick] {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {click}, repeats = 1.75,
- entry = {0s}{0}, entry = {2s}{90} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
-\end{codeexample}
- %
- \item The text ``|for| \meta{time}'' (like |for 2s| or |for 300ms|), in
- which case the timeline repeats however often necessary so that it
- stops exactly after \meta{time}.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={1,2,3,4,5},
-]
-\tikz [very thick] {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {click}, repeats = for 3.5s,
- entry = {0s}{0}, entry = {2s}{90} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
-\end{codeexample}
- \end{itemize}
- %
- The second part of the specification must be one of the following:
- %
- \begin{itemize}
- \item Empty, in which case each time the timeline is restarted, the
- attribute's value undergoes the same series of values it did
- previously.
- \item The text |accumulating|. This has the effect that each time the
- timeline is restarted, the attribute values specified by the
- timeline are \emph{added} to the value from the previous
- iteration(s). A typical example is an animation that shifts a scope
- by, say, 1\,cm over a time of 1\,s. Now, if you repeat this five
- times, normally the scope will shift 1\,cm for 1\,s then ``jump
- back'', shift again, jump back, and so on for five times. In
- contrast, when the repeats are accumulating, the scope will move by
- 5\,cm over 5\,s in total.
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={1,2,3,4,5},
-]
-\tikz [very thick] {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {click}, repeats = accumulating,
- entry = {0s}{0}, entry = {2s}{90} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usepgfmodule{animations}},
- animation list={1,2,3,4,5},
-]
-\tikz [very thick] {
- \pgfanimateattribute{rotate}{
- whom = node, begin on = {click}, repeats = 2 accumulating,
- entry = {0s}{0}, entry = {2s}{90} }
- \node (node) [fill = blue!20, draw = blue, circle] {Click me!}; }
-\end{codeexample}
- \end{itemize}
-\end{key}
-
-\begin{key}{/pgf/animation/repeat=\meta{specification}}
- This is an alias for |repeats|.
-\end{key}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-arrows.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-arrows.tex
deleted file mode 100644
index 5d81abf79d..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-arrows.tex
+++ /dev/null
@@ -1,962 +0,0 @@
-% 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{Defining New Arrow Tip Kinds}
-\label{section-arrows}
-
-\subsection{Overview}
-
-In present section we have a look at how you can define new arrow tips for use
-in \pgfname. The low-level commands for selecting which arrow tips are to be
-used have already been described in Section~\ref{section-tips}, the general
-syntax rules for using arrows are detailed in
-Section~\ref{section-tikz-arrows}. Although Section~\ref{section-tikz-arrows}
-describes the use of arrows in \tikzname, in reality, \tikzname\ itself does
-not actually do anything about arrow tips; all of the functionality is
-implemented on the \pgfname\ level in the commands described in
-Section~\ref{section-tikz-arrows}. Indeed, even the |/.tip| key handler
-described in Section~\ref{section-tikz-arrows} is actually implemented on the
-\pgfname\ layer.
-
-What has \emph{not} yet been covered is how you can actually define a complete
-new arrow tip. In \pgfname, arrows are ``meta-arrows'' in the same way that
-fonts in \TeX\ are ``meta-fonts''. When a meta-arrow is resized, it is not
-simply scaled, but a possibly complicated transformation is applied to the
-size.
-
-A meta-font is not one particular font at a specific size with a specific
-stroke width (and with a large number of other parameters being fixed). Rather,
-it is a ``blueprint'' (actually, more like a program) for generating such a
-font at a particular size and width. This allows the designer of a meta-font to
-make sure that, say, the font is somewhat thicker and wider at very small
-sizes. To appreciate the difference: Compare the following texts: ``Berlin''
-and ``\tikz{\node [scale=2,inner sep=0pt,outer sep=0pt]{\tiny Berlin};}''. The
-first is a ``normal'' text, the second is the tiny version scaled by a factor
-of two. Obviously, the first look better. Now, compare ``\tikz{\node
-[scale=.5,inner sep=0pt,outer sep=0pt]{Berlin};}'' and ``{\tiny Berlin}''. This
-time, the normal text was scaled down, while the second text is a ``normal''
-tiny text. The second text is easier to read.
-
-\pgfname's meta-arrows work in a similar fashion: The shape of an arrow tip can
-vary according to a great number of parameters, the line width of the arrow tip
-being one of them. Thus, an arrow tip drawn at a line width of 5pt will
-typically \emph{not} be five times as large as an arrow tip of line width 1pt.
-Instead, the size of the arrow will get bigger only slowly as the line width
-increases.
-
-To appreciate the difference, here are the |Latex| and
-|Classical TikZ Rightarrow| arrows, as drawn by \pgfname\ at four different
-sizes:
-
-\medskip
-\begin{tikzpicture}[1/.tip=Latex, 2/.tip=Classical TikZ Rightarrow]
- \draw[-1, line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt};
- \draw[-1, line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
- \draw[-1, line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
- \draw[-1, line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt};
-
- \draw[-2, line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt};
- \draw[-2, line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
- \draw[-2, line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
- \draw[-2, line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt};
-\end{tikzpicture}
-
-\medskip
-Here, by comparison, are the same arrows when they are simply ``resized'':
-
-\medskip
-\begin{tikzpicture}[1/.tip=Latex, 2/.tip=Classical TikZ Rightarrow]
- \draw[-{1[length=1pt]}, line width=0.1pt] (0pt,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt};
- \draw[-{1[length=4pt]}, line width=0.4pt] (0pt,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
- \draw[-{1[length=12pt]}, line width=1.2pt] (0pt,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
- \draw[-{1[length=32pt]}, line width=5pt] (0pt,-6em) -- +(3,0) node[thin,right] {line width is 5pt};
-
- \draw[-{2[length=0.455pt]}, line width=0.1pt] (6cm,0ex) -- +(3,0) node[thin,right] {line width is 0.1pt};
- \draw[-{2[length=1.82pt]}, line width=0.4pt] (6cm,-2em) -- +(3,0) node[thin,right] {line width is 0.4pt};
- \draw[-{2[length=5.46pt]}, line width=1.2pt] (6cm,-4em) -- +(3,0) node[thin,right] {line width is 1.2pt};
- \draw[-{2[length=14.56pt]}, line width=5pt] (6cm,-6em) -- +(3,0) node[thin,right] {line width is 5pt};
-\end{tikzpicture}
-
-\bigskip
-As can be seen, simple scaling produces arrow tips that are way too large at
-larger sizes and way too small at smaller sizes.
-
-In addition to the line width, other options may also influence the appearance
-of an arrow tip. In particular, the width of the inner line (the line used to
-create the effect of a double line) influences arrow tips as well as other
-options that are specific to the arrow tip.
-
-
-\subsection{Terminology}
-\label{section-arrow-terminology}
-
-Before we have a look at the exact commands used for defining arrow tips, we
-need to fix some terminology. Consider the following drawing of an arrow tip
-where the arrow tip is drawn transparently so that we can see what is
-``happening behind it'':
-%
-\begin{tikzpicture}
- \draw [red!50, ,line width=1cm] (0,0) -- (4,0);
- \path [tips, opacity=.25,line width=1cm, -{Stealth[black,line width=0pt,length=4cm, width=4cm, inset=1cm]}] (0,0) -- (6,0);
-
- \draw [->,thick] (1,0) -- (8,0) node [right] {$x$-axis};
- \draw [->,thick] (5,-2.25) -- (5,2.25) node [above] {$y$-axis};
-
- \foreach \i in {-3,-2,-1,1,2} \draw (\i+5,-1mm) -- (\i+5,1mm) node [above] {\small$\i$};
- \foreach \i in {-2,-1,1,2} \draw (49mm,\i) -- (51mm,\i) node [right] {\small$\i$};;
-\end{tikzpicture}
-
-I have also added a coordinate system. The code for drawing an arrow tip always
-draws it in the way shown above: Pointing right along the $x$-axis.
-
-We will use the following terminology:
-%
-\begin{itemize}
- \item The point where tip of the arrow ends is called the \emph{tip end}.
- It is at $(1,0)$ in our example and we always assume it to lie on the
- $x$-axis, so we just treat it as a distance, 1 in this case. This is
- the position where the original path was supposed to end (so if the
- arrow tip had not been added to the red path, it would have ended
- here).
- \item The \emph{back end} of the arrow is where a vertical line just to the
- left of the arrow intersects the $x$-axis. In our case, this is the
- point $(-3,0)$ and again we treat it as a distance, $-3$ in this case.
- \item The \emph{line end} is the position where the path now ends. This
- should be a position inside the arrow head that gets ``covered'' by the
- path. Note that a path may have a round or a rect head and should still
- be covered. Clearly, necessary shortening of the path will be the
- difference between the tip end and the line end.
- \item The \emph{visual back end} is the position where the path and the the
- arrow head ``meet last'' on the path. In our case, because of the
- inset, the visual back end is not the same as the back end: The arrow
- ends ``visually'' at $(-2,0)$. The difference between the back end and
- the visual back end is important when the arrow tip is flexed, see
- Section~\ref{section-arrow-flex} for an explanation of flexing.
- \item There is also a \emph{visual tip end}, the counterpart of the visual
- back end for the front. In our case, the visual tip end and the tip end
- obviously coincide, but if we were to reverse the arrow tip, the visual
- tip end would be different from the tip end (while the visual back end
- would then coincide with the new back end).
- \item There are four points that make up the \emph{convex hull} of the
- arrow tip: $(1,0)$, $(-3,2)$, and $(-3,-2)$.
-
- Normally, \pgfname\ automatically keeps track of a bounding box of
- everything you draw. However, since arrow tips are drawn so often,
- \pgfname\ caches the code needing for drawing arrow tips internally and
- because of this cache it cannot determine the size of the arrow tip
- just based on the drawing commands used for drawing the tip. Instead, a
- convex hull of the arrow tip must be explicitly provided in the
- definition.
-\end{itemize}
-
-When you design a new arrow tip, all of the above parameters must be defined.
-
-
-\subsection{Caching and Rendering of Arrows}
-
-As a last preparation for the description of the commands for declaring arrows,
-it is important to understand the exact process by which \pgfname\ draws
-arrows.
-%
-\begin{enumerate}
- \item First, you have to define an arrow tip kind using
- |\pgfdeclarearrow{name=foo,...|. This will tell \pgfname\ that |foo| is %}
- now the name of an arrow tip. In particular, the parser for arrow tip
- specifications will now treat |foo| as the name of an arrow tip and
- will not try to consider |f|, |o|, and |o| as the names of single-char
- shorthands.
-
- Other than storing the definitions in the declaration internally, this
- command has little other effect. In particular, no drawing or other
- processing takes place.
- \item Now assume that at some point the arrow tip |foo| is actually used.
- In this case, certain options may have been set, for instance the user
- may have requested the arrow tip |foo[length=5pt,open]|. What happens
- next depends on whether it is the first time the arrow tip |foo| is
- used with \emph{these exact options} or not.
- \item Assume that is the first time |foo| is requested at a length of 5pt
- and in an ``open'' version. \pgfname\ now retrieves the definition of
- the arrow tip kind that it stored in the first step and executes the
- so-called \emph{setup} code. When this code is executed, all the
- options will be in force (for instance, |\pgfarrowlength| will equal
- |5pt| in our case). The job of the setup code is two-fold: First, it
- needs to compute all of the parameters listed in
- Section~\ref{section-arrow-terminology}, that is, it has to compute
- where the tip end will lie in the arrow tip's coordinate system
- \emph{at the particular size of 5pt}, where the back end will be, where
- the convex hull points lie, and so on. Second, the setup code should
- precompute values that will be important for constructing the path of
- the arrow. In our example, there is little to do in this regard, but
- for more complicated arrows, all time-consuming preparations are done
- now.
-
- It is \emph{not} the job of the setup to actually draw the arrow tip,
- only to ``prepare'' this as much as possible.
-
- The setup code will always be executed only once for each arrow tip
- kind for a given set of options. Thus, when a user uses
- |foo[length=5pt,open]| once more later anywhere in the document, the
- setup code will not be executed again.
- \item The next thing that happens is that we have a look at the
- \emph{drawing code} stored in the |code| field of the arrow. In our
- example, the drawing code would consist of creating a filled path with
- four straight segments.
-
- In most cases, what happens now is that the drawing code is executed in
- a special sandbox in which the low-level driver commands that do the
- actual drawing are intercepted and stored away in a so-called
- \emph{cache}. Once such a cache has been created, its contents will be
- reused whenever |foo[length=5pt,open]| is requested by a user and just
- like the setup code, the drawing code will not be executed again.
-
- There are, however, two cases in which the drawing code gets executed
- each time the arrow is used: First, an arrow tip kind can specify that
- this should always happen by saying |cachable=false| in its definition.
- This is necessary if the drawing code contains low-level drawing
- commands that cannot be intercepted such as a use of |\pgftext| for
- arrow tips that ``contain text''. Second, when the |bend| option is
- used, the same arrow tip will look different each time it is used,
- namely in dependence on the exact curvature of the path to which it is
- added.
-
- Because the drawing code may be executed several times, while the setup
- code may not, we must find a way to ``communicate'' the values computed
- by the setup code to the drawing code. This is done by explicitly
- calling |\pgfarrowssave| inside the setup code. Whatever is ``saved''
- in this way is restored each time before the drawing code is executed.
-\end{enumerate}
-
-As can be seen, the process is a bit involved, but it leads to a reasonably
-fast arrow tip management.
-
-
-\subsection{Declaring an Arrow Tip Kind}
-
-\begin{command}{\pgfdeclarearrow\marg{config}}
- This command is both used to define a new arrow tip kind and to to declare
- a so-called shorthand. We have a look at the case that a complete new arrow
- tip kind is created and then have a look how the command can be used to
- create shorthands.
-
-
- \medskip
- \noindent\textbf{Defining a Complete New Arrow Tip Kind.}
- The \meta{config} is a key--value list in which different keys are used to
- setup the to-be defined arrow. The following keys can be given:
- %
- \begin{itemize}
- \item \declare{|name|}|=|\meta{name} or |name=|\meta{start
- name}|-|\meta{end name}
-
- This defines the name of the arrow tip. It is legal to define an
- arrow tip a second time, in this case the previous definition will
- be overwritten in the current \TeX\ scope. It is customary to use a
- name with an uppercase first letter for a ``complete'' arrow tip
- kind. Short names and lower case names should be used for
- shorthands that change their meaning inside a document, while arrow
- tips with uppercase first letters should not be redefined.
-
- If the name contains a hyphen, the second syntax is assumed and
- everything before the hyphen will be the name used in start arrow
- specifications, while the text after the hyphen is the name used in
- end specifications.
- \item \declare{|parameters|}|=|\marg{list of macros}
-
- As explained earlier, an arrow tip typically needs to be redrawn
- each time an option like |length| or |inset| is changed. However,
- for some arrow tips, the |inset| has no influence, while for other
- it is important whether the arrow is reversed or not. (How keys
- like |length| actually set \TeX\ dimensions like |\pgfarrowlength|
- is explained in Section~\ref{section-arrow-options}.)
-
- The job of the |parameters| key is to specify which dependencies
- the arrow tip has. Everything that will influence any of the
- parameters computed in the setup code or used in the drawing code
- should be listed here.
-
- The \meta{list of macros} will be used inside a
- |\csname|-|\endcsname| pair and should expand to the current values
- of the relevant parameters have. For example, if the arrow tip
- depends on the current value of |\pgfarrowlength| and
- |\pgfarrowwidth| only, then \meta{list of macros} should be set to
- |\the\pgfarrowlength,\the\pgfarrowwidth|. (Actually, the comma is
- optional, the \meta{list of macros} does not really have to be a
- list, just something that can be expanded unambiguously.)
-
- Note that the line width (|\pgflinewidth|) and the inner line width
- (|\pgfinnerlinewidth|) are always parameters and need not be
- specified in the |parameters|.
-
- It is important to get this parameter right. Otherwise, arrow tips
- may look wrong because \pgfname\ thinks that it can reuse some code
- when, in reality, this code actually depends on a parameter not
- listed here.
- \item \declare{|setup code|}|=|\marg{code}
-
- When an arrow tip is used, the value stored in |parameters| is
- expanded and it is tested whether the result was encountered
- before. If not, the \meta{code} gets executed (only this once). The
- code can now do arbitrarily complicated computations the prepare
- the later drawing of the arrow tip. Also the \meta{code} must
- specify the different tip and back ends and the convex hull points.
- This is done by calling the following macros inside the
- \meta{code}:
- %
- \begin{command}{\pgfarrowssettipend\marg{dimension}}
- When this command is called inside the setup code of an arrow
- tip, it specifies that the tip of the drawn arrow will end
- exactly at \meta{dimension}. For example, for our earlier
- example of the large arrow tip, where the tip end was at 1cm,
- we would call
- %
-\begin{codeexample}[code only]
-\pgfarrowssettipend{1cm}
-\end{codeexample}
- %
- Note that for efficiency reasons, the \meta{dimension} is not
- passed through |\pgfmathsetlength|; rather what happens is that
- |\pgf@x=|\meta{dimension} gets executed. In particular, you can
- pack further computations into the \meta{dimension} by simply
- starting it with a number and then appending some code that
- modifies |\pgf@x|. Here is an example where instead of 1cm we
- use $1\mathrm{cm} - \frac12\mathrm{linewidth}$ as the tip end:
- %
-\begin{codeexample}[code only]
-\pgfarrowssettipend{1cm\advance\pgf@x by-.5\pgflinewidth}
-\end{codeexample}
- %
- If the command is not called at all inside the setup code, the
- tip end is set to |0pt|.
- \end{command}
-
- \begin{command}{\pgfarrowssetbackend\marg{dimension}}
- Works like the command for the tip end, only it sets the back
- end. In our example we would call
- %
-\begin{codeexample}[code only]
-\pgfarrowssettipend{-3cm}
-\end{codeexample}
- %
- Defaults to |0pt|.
- \end{command}
-
- \begin{command}{\pgfarrowssetlineend\marg{dimension}}
- Sets the line end, so in the example we have
- |\pgfarrowssettipend{-1cm}|. Default to |0pt|.
- \end{command}
-
- \begin{command}{\pgfarrowssetvisualbackend\marg{dimension}}
- Sets the visual back end, |\pgfarrowssetvisualbackend{-2cm}| in
- our example. Default to the value of the normal back end.
- \end{command}
-
- \begin{command}{\pgfarrowssetvisualtipend\marg{dimension}}
- Sets the visual tip end. Default to the value of the normal tip
- end and, thus, we need not set it in our example.
- \end{command}
-
- \begin{command}{\pgfarrowshullpoint\marg{x dimension}\marg{y dimension}}
- Adds a point to the convex hull of the arrow tip. As for the
- previous commands, no math parsing is done; instead \pgfname\
- says |\pgf@x=|\meta{x dimension} and then |\pgf@y=|\meta{y
- dimension}. Thus, both ``dimensions'' can contain code for
- advancing and thus modifying |\pgf@x| and |\pgf@y|.
-
- In our example we would write
- %
-\begin{codeexample}[code only]
-\pgfarrowshullpoint{1cm}{0pt}
-\pgfarrowshullpoint{-3cm}{2cm}
-\pgfarrowshullpoint{-3cm}{-2cm}
-\end{codeexample}
- \end{command}
-
- \begin{command}{\pgfarrowsupperhullpoint\marg{x dimension}\marg{y dimension}}
- This command works like the previous command, only it normally
- adds \emph{two} points to the convex hull: First, the point
- $(\meta{x dimension},\meta{y dimension})$ and, secondly, the
- point $(\meta{x dimension},-\meta{y dimension})$. However, the
- second point is only added if the arrow is not a harpoon.
-
- Thus, in our example we could simplify the convex hull to
- %
-\begin{codeexample}[code only]
-\pgfarrowshullpoint{1cm}{0pt}
-\pgfarrowsupperhullpoint{-3cm}{2cm}
-\end{codeexample}
- %
- If the \meta{y dimension} is zero or less, only one point,
- namely $(\meta{x dimension},\meta{y dimension})$, is added to
- the hull. Thus, we could also have used the upper convex hull
- command in the first of the two of the above commands.
- \end{command}
-
- \begin{command}{\pgfarrowssave\marg{macro}}
- As explained earlier, the setup code needs to ``communicate''
- with the drawing code via ``saved values''. This command get
- the name of a macro and will store the value this macro had
- internally. Then, each time drawing code is executed, the value
- of this macro will be restored.
- \end{command}
-
- \begin{command}{\pgfarrowssavethe\marg{register}}
- Works like |\pgfarrowssave|, only the parameter must be a
- register and |\the|\meta{register} will be saved. Typically,
- you will write something like
- %
-\begin{codeexample}[code only]
-\pgfarrowssavethe{\pgfarrowlength}
-\pgfarrowssavethe{\pgfarrowwidth}
-\end{codeexample}
- %
- To ensure that inside the drawing code the the dimension
- registers |\pgfarrowlength| and |\pgfarrowwidth| are setup with
- the values they had during the setup.
- \end{command}
- \item \declare{|drawing code|}|=|\marg{code}
-
- This code will be executed at least once for each setting of the
- parameters when the time arrow tip is actually drawn. Usually, this
- one execution will be all and the low-level commands generated
- inside the \meta{code} will we stored in a special cache; but in
- some cases the \meta{code} gets executed each time the arrow tip is
- used, so do not assume anything about it. Inside the \meta{code},
- you have access to all values that were saved in the setup code as
- well as to the line width.
-
- The \meta{code} should draw the arrow tip ``going right along the
- $x$-axis''. \pgfname\ will take care of setting up a canvas
- transformation beforehand to a rotation such that when the drawing
- is rendered, the arrow tip that is actually drawn points in the
- direction of the line. Alternatively, when bending is switched on,
- even more complicated low-level transformations will be done
- automatically.
-
- The are some special considerations concerning the \meta{code}:
- %
- \begin{itemize}
- \item In the \meta{code} you may \emph{not} use |\pgfusepath|
- since this would try to add arrow tips to the arrow tip and
- lead to a recursion. Use the ``quick'' versions
- |\pgfusepathqstroke| and so on instead, which never try to
- add arrow tips.
- \item If you stroke the path that you construct, you should
- first set the dashing to solid and set up fixed joins and
- caps, as needed. This will ensure that the arrow tip will
- always look the same.
- \item When the arrow tip code is executed, it is automatically
- put inside a low-level scope, so nothing will ``leak out''
- from the scope.
- \item The high-level coordinate transformation matrix will be
- set to the identity matrix when the code is executed for
- the first time.
- \end{itemize}
- \item \declare{|cache|}|=|\meta{true or false}
-
- When set to |true|, which is the default, the \meta{code} will be
- executed only once for a particular value of parameters and the
- low-level commands created by the drawing code (using the system
- layer protocol subsystem, see Section~\ref{section-protocols}) will
- be cached and reused later on. However, when the drawing code
- contains ``uncachable'' code like a call to |\pgftext|, caching
- must be switched off by saying |cache=false|.
- \item \declare{|bending mode|}|=|\meta{mode}
-
- This key is important only when the |bend| option is used with an
- arrow, see Section~\ref{section-arrow-flex} for an introduction to
- this option. The |bend| option asks us to, well, bend the arrow
- head. For some arrow head this is not possible or leads to very
- strange drawings (for instance, when the |\pgftext| command is
- used) and then it is better to switch bending off for the arrow
- head (|flex| will then be used instead). To achieve this, set
- \meta{mode} to |none|.
-
- For most arrow tips it does, however, make sense to bend them.
- There are (at least) two different mathematical ways of doing so,
- see Section~\ref{section-library-curvilinear} for details. Which of
- these ways is use can be configured by setting \meta{mode} to
- either |orthogonal| or to |polar|. It is best to try simply try out
- both when designing an arrow tip to see which works better. Since
- |orthogonal| is quicker and often gives good oder even better
- results, it is the default. Some arrow tips, however, profit from
- saying |bending mode=polar|.
- \item \declare{|defaults|}|=|\meta{arrow keys}
-
- The \meta{arrow keys} allow you to configure the default values for
- the parameters on which an arrow tip depends. The \meta{arrow keys}
- will be executed first before any other arrow tip options are
- executed, see Section~\ref{section-arrow-scopes} for the exact
- sequence. Also see Section~\ref{section-arrow-options} below for
- more details on arrow options.
- \end{itemize}
-
- This concludes the description of the keys you provide for the declaration
- of an arrow. Let us now have a look at a simple example that uses these
- features: We want to define an arrow tip kind |foo| that produces the arrow
- tip we used as our running example. However, to make things a bit more
- interesting, let us make it ``configurable'' insofar as the length of the
- arrow tip can be configured using the |length| option, which sets the
- |\pgfarrowlength|. By default, this length should be the gigantic 4cm we
- say in the example, but uses should be able to set it to anything they
- like. We will not worry about the arrow width or insets, of arrow line
- width, or harpoons, or anything else in this example to keep it simple.
-
- Here is the code:
- %
-\begin{codeexample}[code only]
-\pgfdeclarearrow{
- name = foo,
- parameters = { \the\pgfarrowlength },
- setup code = {
- % The different end values:
- \pgfarrowssettipend{.25\pgfarrowlength}
- \pgfarrowssetlineend{-.25\pgfarrowlength}
- \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
- \pgfarrowssetbackend{-.75\pgfarrowlength}
- % The hull
- \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
- \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
- \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
- % Saves: Only the length:
- \pgfarrowssavethe\pgfarrowlength
- },
- drawing code = {
- \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}}
- \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}}
- \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}}
- \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}}
- \pgfpathclose
- \pgfusepathqfill
- },
- defaults = { length = 4cm }
-}
-\end{codeexample}
- %
- We can now use it:
- %
-\pgfdeclarearrow{
- name = foo,
- parameters = { \the\pgfarrowlength },
- setup code = {
- % The different end values:
- \pgfarrowssettipend{.25\pgfarrowlength}
- \pgfarrowssetlineend{-.25\pgfarrowlength}
- \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
- \pgfarrowssetbackend{-.75\pgfarrowlength}
- % The hull
- \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
- \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
- \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
- % Saves: Only the length:
- \pgfarrowssavethe\pgfarrowlength
- },
- drawing code = {
- \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}}
- \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}}
- \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}}
- \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}}
- \pgfpathclose
- \pgfusepathqfill
- },
- defaults = { length = 4cm }
-}
-\begin{codeexample}[
- preamble={\usetikzlibrary{arrows.meta}},
- pre={\pgfdeclarearrow{
- name = foo,
- parameters = { \the\pgfarrowlength },
- setup code = {
- % The different end values:
- \pgfarrowssettipend{.25\pgfarrowlength}
- \pgfarrowssetlineend{-.25\pgfarrowlength}
- \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
- \pgfarrowssetbackend{-.75\pgfarrowlength}
- % The hull
- \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
- \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
- \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
- % Saves: Only the length:
- \pgfarrowssavethe\pgfarrowlength
- },
- drawing code = {
- \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}}
- \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}}
- \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}}
- \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}}
- \pgfpathclose
- \pgfusepathqfill
- },
- defaults = { length = 4cm }
-}},
-]
-\tikz \draw [-foo] (0,0) -- (8,0);
-\end{codeexample}
-\begin{codeexample}[
- preamble={\usetikzlibrary{arrows.meta,bending}},
- pre={\pgfdeclarearrow{
- name = foo,
- parameters = { \the\pgfarrowlength },
- setup code = {
- % The different end values:
- \pgfarrowssettipend{.25\pgfarrowlength}
- \pgfarrowssetlineend{-.25\pgfarrowlength}
- \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
- \pgfarrowssetbackend{-.75\pgfarrowlength}
- % The hull
- \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
- \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
- \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
- % Saves: Only the length:
- \pgfarrowssavethe\pgfarrowlength
- },
- drawing code = {
- \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}}
- \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}}
- \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}}
- \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}}
- \pgfpathclose
- \pgfusepathqfill
- },
- defaults = { length = 4cm }
-}},
-]
-\tikz \draw [-{foo[length=2cm,bend]}] (0,0) to [bend left] (3,0);
-\end{codeexample}
-
-
- \medskip
- \noindent\textbf{Defining a Shorthand.}
- The |\pgfdeclarearrow| command can also used to define
- \emph{shorthands}. This works as follows:
- \begin{itemize}
- \item First, you must provide a |name| just in the same way as when you
- define a full-flung new arrow tip kind.
- \item Second, instead of all of the other options listed above, you
- just use one more option:
-
- \smallskip
- \declare{|means|}|=|\meta{end arrow specification}
-
- This sets up things so that whenever \meta{name} is now used in an
- arrow specification, it will be replaced by the \meta{end arrow
- specification} (the problems resulting form the \meta{name} begin
- used in a start arrow specification are taken care of
- automatically). See also Section~\ref{section-arrow-tip-macro} for
- details on the order in which options get executed in such cases.
-
- Note that the \meta{end arrow specification} will be executed
- immediately to build the so-called arrow option caches, a concept
- explored in more detail in
- Section~\ref{section-arrow-option-cache}. In practice, this has
- mainly two effects: First, all arrow tips referred to in the
- specification must already exist (at least as ``dummy'' versions).
- Second, all dimensions mentioned in options of the \meta{end arrow
- specification} will be evaluated immediately. For instance, when
- you write
- %
-\begin{codeexample}[code only]
-\pgfdeclarearrow{ name=foo, means = bar[length=2cm+\mydimen] }
-\end{codeexample}
- %
- The value |2cm+\mydimen| is evaluated immediately. When |foo| is
- used later on and |\mydimen| has changed, this has no effect.
- \end{itemize}
-\end{command}
-
-
-\subsection{Handling Arrow Options}
-\label{section-arrow-options}
-
-When you declare an arrow tip, your drawing code should take into account the
-different arrow keys set for it (like the arrow tip length, width, or
-harpooning). The different arrow keys that are available have been described in
-detail in Section~\ref{section-arrow-config}; but how do we access the values
-set by an option like |length| or |harpoon| or |bend| in the drawing code? In
-the present section we have a look at how this works.
-
-
-\subsubsection{Dimension Options}
-
-Most arrow keys, like |length| or |width'|, simple set a \TeX\ dimension
-register to a certain value. For example, |length| sets the value of the \TeX\
-dimension register |\pgfarrowlength|. Note that |length| takes several values
-as input with a complicated semantics as explained for the |length| key on
-page~\pageref{length-arrow-key}. All of these settings are not important for
-the setup code: When it gets executed, the code behind the |length| key will
-have computed a simple number that is stored in |\pgfarrowlength|. Indeed,
-inside the setup code you do not have access to the exact value given to the
-|length| key; just to the final computed value.
-
-The following \TeX\ dimensions are available to the setup code:
-%
-\begin{itemize}
- \item |\pgfarrowslength|. It gets set by the arrow keys |length| and
- |angle|.
- \item |\pgfarrowswidth|. It gets set by |width|, |width'|, and |angle|.
- \item |\pgfarrowsinset|. It gets set by |inset| and |inset'|.
- \item |\pgfarrowslinewidth|. It gets set by |line width| and |line width'|.
-\end{itemize}
-
-If your setup code depends on any of them, add them to the |parameters| key of
-the arrow tip.
-
-
-\subsubsection{True--False Options}
-
-A number of arrow keys just do a yes/no switch, like |reversed|. All of them
-setup a \TeX-if that you can access in the setup code:
-%
-\begin{itemize}
- \item |\ifpgfarrowreversed| is setup by |reversed|.
- \item |\ifpgfarrowswap| is setup by |swap| and also |right|.
- \item |\ifpgfarrowharpoon| is setup by |harpoon| and also |left| and
- |right|.
- \item |\ifpgfarrowroundcap| is set to true by |line cap=round| and set to
- false by |line cap=butt|. It also gets (re)set by |round| and |sharp|.
- \item |\ifpgfarrowroundjoin| is set to true by |line join=round| and set to
- false by |line join=miter|. It also gets (re)set by |round| and
- |sharp|.
- \item |\ifpgfarrowopen| is set to true by |fill=none| and by |open| (which
- is a shorthand for |fill=none|) and set to false by |color| and all
- other |fill=|\meta{color}.
-\end{itemize}
-
-If you code depends on any of these, you must add them to the |parameters| in
-such a way that the parameters are different when the \TeX-if is set from when
-it is not set. An easy way to achieve this is to write something like
-%
-\begin{codeexample}[code only]
- parameters = { \the\pgfarrowlength,...,
- \ifpgfarrowharpoon h\fi\
- \ifpgfarrowroundjoin j\fi}
-\end{codeexample}
-%
-In other words, for each set parameter on which the arrow tip depends, a
-specific letter is added to the parameters, making them unique.
-
-The first two of the above keys are a bit special: Reversing and swapping an
-arrow tip can be done just by fiddling with the transformation matrix: a
-reverse is a ``flip'' along the $y$-axis and a swap is a flip along the
-$x$-axis. This is done automatically by \pgfname.
-
-Nevertheless, you may wish to modify you code in dependence especially of the
-|reverse| key: When |\ifpgfarrowreverse| is true, \pgfname\ will flip the
-coordinate system along the $y$-axis, will negate all end values (like line
-end, tip end, and so on) and will exchange the meaning of back end and tip end
-as well as of visual back end and visual back end. Usually, this is exactly
-what one need; \emph{except} that the line end may no longer be appropriate.
-After all, the line end should be chosen so that it is completely covered by
-the arrow. Now, when the arrow tip is open, a reversed arrow should no longer
-have the line end near the old visual back end, but near to the old visual tip
-end.
-
-For these reasons, you may need to make the computation of the line end
-dependent on whether the arrow is reversed or not. Note that when you specify a
-different line end for a reversed arrow tip, the transformation and inverting
-of the coordinate system will still be done, meaning that if |reverse| is true,
-you need to specify a line end in the ``old'' coordinate system that is at the
-position where, after everything is inverted, it will be at the correct
-position. Usually that means that if the |reverse| option is set, you need to
-\emph{increase} the line end.
-
-
-\subsubsection{Inaccessible Options}
-
-There are some options that influence the way an arrow tip looks, but that you
-cannot access inside the setup code. Handling these options lies entirely with
-\pgfname. If you wish your setup code to handle these options, you have to
-setup your own ``parallel'' options.
-%
-\begin{itemize}
- \item |quick|, |flex|, |flex'|, and |bend| are all handled automatically.
- You can, however, set the |bending mode| to avoid bending of your arrow
- tip.
- \item The colors set by |color| and |fill|. You can, however, access them
- indirectly, namely through the current stroke and fill colors.
- \item |sep|
-\end{itemize}
-
-
-\subsubsection{Defining New Arrow Keys}
-\label{section-arrow-option-cache}
-
-The set of predefined options is already quite long and most arrow tips will
-not need more than the predefined options. However, sometimes an arrow tip may
-need to introduce a new special-purpose option. For instance, suppose we wish
-to introduce a new fictive arrow key |depth|. In such cases, you must do two
-things:
-%
-\begin{enumerate}
- \item Introduce a new dimension register or macro that will hold the
- configuration value and which will be accessed by the setup code. The
- could be achieved by saying
- %
-\begin{codeexample}[code only]
-\newdimen\pgfarrowdepth
-\end{codeexample}
- %
- \item Introduce a new arrow key option |/pgf/arrow keys/depth| that allows
- users to configure the new macro or register.
-\end{enumerate}
-
-When an arrow is selected via for instance |foo[depth=5pt]|, the key--value
-pairs between the square brackets are executed with the path prefix
-|/pgf/arrow keys|. Thus, in the example, our depth key would get executed.
-Thus, it is tempting to write something like
-%
-\begin{codeexample}[code only]
-\pgfkeys{/pgf/arrow keys/depth/.code = \pgfmathsetlength{\pgfarrowdepth}{#1}}
-\end{codeexample}
-
-Sadly, this will not work. The reason is that there is yet another level of
-caching involved when \pgfname\ processes arrow tips: The option cache! The
-problem is each time an arrow tip is used, even when the drawing code of the
-arrow tip is nicely cached, we still need to process the options in
-|foo[length=5pt]| to find out which version in the cache we would like to
-access. To make matters worse, |foo| might be a shorthand that calls other
-arrow tips, which add more options, and so on. Unfortunately, executing keys is
-quite an expensive operation (\pgfname's key--value parser is powerful, but
-that power comes at a price). So, whenever possible, we do \emph{not} want the
-key--value parser to be started.
-
-For these reasons, when something like |foo[|\meta{options}|]| is encountered
-inside a shorthand, the \meta{options} are executed only once. They should now
-setup the \emph{arrow option cache}, which is some code that, when executed,
-should setup the values that the \meta{options} configure. In our example, the
-|depth| key should add something to the arrow option cache that sets
-|\pgfarrowdepth| to the given value.
-
-Adding something to the arrow option cache is done using the following command:
-
-\begin{command}{\pgfarrowsaddtooptions\marg{code}}
- This command should be called by keys with the prefix |/pgf/arrow keys| to
- add code to the arrow option cache. For our |depth| key example, we could
- use this key as follows:
- %
-\begin{codeexample}[code only]
-\pgfkeys{/pgf/arrow keys/depth/.code=
- \pgfarrowsaddtooptions{\pgfmathsetlength{\pgfarrowdepth}{#1}}
-\end{codeexample}
- %
- Actually, this is still not optimal since the expensive |\pgfmathsetlength|
- command is now called each time an arrow tip is used with the |depth|
- option set. The trick is to do the expensive operation only once and then
- store only very quick code in the arrow option cache:
- %
-\begin{codeexample}[code only]
-\pgfkeys{/pgf/arrow keys/depth/.code=
- \pgfmathsetlength{\somedimen}{#1}
- \pgfarrowsaddtooptions{\pgfarrowdepth=\somedimen} % buggy
-\end{codeexample}
- %
- The above code will not (yet) work since |\somedimen| will surely have a
- different value when the cache is executed. The trick is to use some
- |\expandafter|s:
- %
-\begin{codeexample}[code only]
-\pgfkeys{/pgf/arrow keys/depth/.code=
- \pgfmathsetlength{\somedimen}{#1}
- \expandafter\pgfarrowsaddtooptions\expandafter{\expandafter\pgfarrowdepth\expandafter=\the\somedimen}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfarrowsaddtolateoptions\marg{code}}
- This command works like |\pgfarrowsaddtooptions|, only the \meta{code} will
- be executed ``later'' than the code added by the normal version of the
- command. This is useful for keys that depend on the length of an arrow:
- Keys like |width'| want to define the arrow width as a multiple of the
- arrow length, but when the |width'| key is given, the length may not yet
- have been specified. By making the computation of the width a ``late''
- option, we ensure that |\pgfarrowlength| will have been setup correctly.
-\end{command}
-
-If you define a new option that sets a dimensions and if that dimension should
-change in accordance to the setting of either |scale length| or |scale width|,
-you need to make \pgfname\ ``aware'' of this using the following key:
-
-\begin{command}{\pgfarrowsaddtolengthscalelist\marg{dimension register}}
- Each time an arrow tip is used, the given \meta{dimension register} will be
- multiplied by the |scale length| factor prior to the actual drawing. You
- call this command only once in the preamble somewhere.
-\end{command}
-
-\begin{command}{\pgfarrowsaddtowidthscalelist\marg{dimension register}}
- Works like |\pgfarrowsaddtolengthscalelist|, only for width parameters.
-\end{command}
-
-
-\begin{command}{\pgfarrowsthreeparameters\marg{line-width dependent size specification}}
- This command is useful for parsing the values given to keys like |length|
- or |width| the expect a dimension followed optionally for some numbers.
- This command converts the \meta{line-width dependent size specification},
- which may consist of one, two, or three numbers, into a triple of three
- numbers in curly braces, which gets stored in the macro
- |\pgfarrowstheparameters|. Here is an example, where |\showvalueofmacro| is
- used in this example to show the value stored in a macro:
- %
-\begin{codeexample}[setup code,hidden]
- \makeatletter
- \def\showvalueofmacro#1{%
- \texttt{\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\pgfutil@gobble\expandafter\expandafter\expandafter\string\expandafter\csname#1\endcsname}
- }%
-\end{codeexample}
-%
-\begin{codeexample}[]
-\pgfarrowsthreeparameters{2pt 1}
-\showvalueofmacro\pgfarrowstheparameters
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfarrowslinewidthdependent\marg{dimension}\marg{line width factor}\marg{outer factor}}
- This command takes three parameters and does the ``line width dependent
- computation'' described on page~\pageref{length-arrow-key} for the |length|
- key. The result is returned in |\pgf@x|.
-
- The idea is that you can setup line-width dependent keys like |length| or
- |width| using code like the following:
- %
-\begin{codeexample}[code only]
-\pgfkeys{/pgf/arrow keys/depth/.code={%
- \pgfarrowsthreeparameters{#1}%
- \expandafter\pgfarrowsaddtolateoptions\expandafter{%
- \expandafter\pgfarrowslinewidthdependent\pgfarrowstheparameters% compute...
- \pgfarrowdepth\pgf@x% ... and store.
- }%
-}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfarrowslengthdependent\marg{dimension}\marg{length factor}\marg{dummy}}
- This command takes three parameters, of which the last one is ignored, and
- does the ``length dependent computation'' described for the |width'| and
- |inset'| keys. The result is returned in |\pgf@x|.
-
- You can setup length dependent keys using code like the following:
- %
-\begin{codeexample}[code only]
-\pgfkeys{/pgf/arrow keys/depth'/.code={%
- \pgfarrowsthreeparameters{#1}%
- \expandafter\pgfarrowsaddtolateoptions\expandafter{%
- \expandafter\pgfarrowslengthdependent\pgfarrowstheparameters% compute...
- \pgfarrowdepth\pgf@x% ... and store.
- }%
-}
-\end{codeexample}
- %
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-decorations.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-decorations.tex
deleted file mode 100644
index 50d4c370fe..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-decorations.tex
+++ /dev/null
@@ -1,979 +0,0 @@
-% Copyright 2019 by Till Tantau and Mark Wibrow
-%
-% 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{Decorations}
-\label{section-base-decorations}
-
-\begin{pgfmodule}{decorations}
- The commands for creating decorations are defined in this module, so you
- need to load this module to use decorations. This module is automatically
- loaded by the different decoration libraries.
-\end{pgfmodule}
-
-
-\subsection{Overview}
-
-Decorations are a general way of creating graphics by ``moving along'' a path
-and, while doing so, either drawing something or constructing a new path. This
-could be as simple as extending a path with a ``zigzagged'' line\ldots
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
-\tikz \draw decorate[decoration=zigzag] {(0,0) -- (3,0)};
-\end{codeexample}
-%
-\ldots but could also be as complex as typesetting text along a path:
-%
-{\catcode`\|12
-\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.text}}]
-\tikz \path decorate [decoration={text along path,
- text={Some text along a path}}]
- { (0,2) .. controls (2,2) and (1,0) .. (3,0) };
-\end{codeexample}
-}
-
-The workflow for using decorations is the following:
-%
-\begin{enumerate}
- \item You define a decoration using the |\pgfdeclaredecoration| command.
- Different useful decorations are already declared in libraries like
- |decorations.shapes|.
- \item You use normal path construction commands like |\pgfpathlineto| to
- construct a path. Let us call this path the \emph{to-be-decorated}
- path.
- \item You place the path construction commands inside the environment
- |{pgfdecoration}|. This environment takes the name of a previously
- declared decoration as a parameter. It will then start ``walking
- along'' the to-be-decorated path. As it does this, a special finite
- automaton called a \emph{decoration automaton} produces new path
- commands as its output (or even other outputs). These outputs replace
- the to-be-decorated path; indeed, after the to-be-decorated path has
- been fully walked along it is thrown away, only the output of the
- automaton persists.
-\end{enumerate}
-
-In the present section the process of how decoration automata work is explained
-first. Then the command(s) for declaring decoration automata and for using them
-are covered.
-
-
-\subsection{Decoration Automata}
-
-Decoration automata (and the closely related meta-decoration automata) are a
-general concept for creating graphics ``along paths''. For straight lines, this
-idea was first proposed by Till Tantau in an earlier version of \pgfname, the
-idea to extend this to arbitrary path was proposed and implemented by Mark
-Wibrow. Further versatility is provided by ``meta-decorations''. These are
-automata that decorate a path with decorations.
-
-In the present subsection the different ideas underlying decoration automata
-are presented.
-
-
-\subsubsection{The Different Paths}
-
-In order to prevent confusion with different types of paths, such as those that
-are extended, those that are decorated and those that are created, the
-following conventions will be used:
-%
-\begin{itemize}
- \item The \emph{preexisting} path refers to the current path in existence
- before a decoration environment. (Possibly this path has been created
- by another decoration used earlier, but we will still call this path
- the preexisting path also in this case.)
- \item The \emph{input} path refers to the to-be-decorated path that the
- decoration automaton moves along. The input path may consist of many
- line and curve input segments (for example, a circle or an ellipse
- consists of four curves). It is specified inside the decoration
- environment.
- \item The \emph{output} path refers to the path that the decoration
- creates. Depending on the decoration, this path may or may not be empty
- (a decoration can also choose to use side-effects instead of producing
- an output path). The input path is always consumed by the decoration
- automaton, that is, it is no longer available in any way after the
- decoration automaton has finished.
-\end{itemize}
-
-The effect of a decoration environment is the following: The input path, which
-is specified inside the environment, is constructed and stored. This process
-does not alter the preexisting path in any way. Then the decoration automaton
-is started (as described later) and it produces an output path (possibly
-empty). Whenever part of the output path is produced, it is concatenated with
-the preexisting path. After the environment, the current path will equal the
-original preexisting path followed by the output path.
-
-It is permissible that a decoration issues a |\pgfusepath| command. As usual,
-this causes the current path to be filled or stroked or some other action to be
-taken and the current path is set to the empty path. As described above, when
-the decoration automaton starts, the current path is the preexisting path and
-as the automaton progresses, the current path is constantly being extended by
-the output path. This means that first time a |\pgfusepath| command is used on
-a decoration, the preexisting path is part of the path this command operates
-on; in subsequent calls only the part of the output path constructed since the
-last |\pgfusepath| command will be used.
-
-You can use this mechanism to stroke or fill different parts of the output path
-in different colors, line widths, fills and shades; all within the same
-decoration. Alternatively, a decoration can choose to produce no output path at
-all: the |text| decoration simply typesets text along a path.
-
-
-\subsubsection{Segments and States}
-
-The most common use of a decoration is to ``repeat something along a path''
-(for example, the |zigzag| decoration repeats
-%
-\tikz\draw decorate[decoration=zigzag] {(0,0)--(\pgfdecorationsegmentlength,0)};
-%
-along a path). However, it not necessarily the case that only one thing is
-repeated: a decoration can consist of different parts, or \emph{segments},
-repeated in a particular order.
-
-When you declare a decoration, you provide a description of how their different
-segments will be rendered. The description of each segment should be given in a
-way as if the ``$x$-axis'' of the segment is the tangent to the path at a
-particular point, and that point is the origin of the segment. Thus, for
-example, the segment of the |zigzag| decoration might be defined using the
-following code:
-%
-\begin{codeexample}[code only]
-\pgfpathlineto{\pgfpoint{5pt}{5pt}}
-\pgfpathlineto{\pgfpoint{15pt}{-5pt}}
-\pgfpathlineto{\pgfpoint{20pt}{0pt}}
-\end{codeexample}
-
-\pgfname\ will ensure that an appropriate coordinate transformation is in place
-when the segment is rendered such that the segment actually points in the right
-direction. Also, subsequent segments will be transformed such that they are
-``further along the path'' toward the end of the path. All transformations are
-set up automatically.
-
-Note that we did not use a |\pgfpathmoveto{\pgfpointorigin}| at the beginning
-of the segment code. Doing so would subdivide the path into numerous subpaths.
-Rather, we assume that the previous segment caused the current point to be at
-the origin.
-
-The width of a segment can (and must) be specified explicitly. \pgfname\ will
-use this width to find out the start point of the next segment and the correct
-rotation. The width the you provide need not be the ``real'' width of the
-segment, which allows decoration segments to overlap or to be spaced far apart.
-
-The |zigzag| decoration only has one segment that is repeated again and again.
-However, we might also like to have \emph{different} segments and use rules to
-describe which segment should be used where. For example, we might have special
-segments at the start and at the end.
-
-Decorations use a mechanism known in theoretical in computer science as
-\emph{finite state automata} to describe which segment is used at a particular
-point. The idea is the following: For the first segment we start in a special
-\emph{state} called the \emph{initial state}. In this state, and also in all
-other states later, \pgfname\ first computes how much space is left on the
-input path. That is, \pgfname\ keeps track of the distance to the end of the
-input path. Attached to each state there is a set of rules of the following
-form: ``If the remaining distance on the input path is less than $x$, switch to
-state~$q$.'' \pgfname\ checks for each of these rules whether it applies and,
-if so, immediately switches to state~$q$.
-
-Only if none of the rules tell us to switch to another state, \pgfname\ will
-execute the state's code. This code will (typically) add a segment to the
-output path. In addition to the rules there is also a width parameter attached
-to each state. \pgfname\ then translates the coordinate system by this width
-and reduces the remaining distance on the input path. Then, \pgfname\ either
-stays in the current state or switches to another state, depending on yet
-another property attached of the state.
-
-The whole process stops when a special state called |final| is reached. The
-segment of this state is immediately added to the output path (it is often
-empty, though) and the process ends.
-
-
-\subsection{Declaring Decorations}
-
-The following command is used to declare a decoration. Essentially, this
-command describes the decoration automaton.
-
-\begin{command}{\pgfdeclaredecoration\marg{name}\marg{initial state}\marg{states}}
- This command declares a new decoration called \meta{name}. The
- \meta{states} argument contains a description of the decoration automaton's
- states and the transitions between them. The \meta{initial state} is the
- state in which the automaton starts.
-
- When the automaton is later applied to an input path, it keeps track of a
- certain position on the input path. This current point will ``travel along
- the path'', each time being moved along by a certain distance. This will
- also work if the path is not a straight line. That is, it is permissible
- that the path curves are veers at a sharp angle. It is also permissible
- that while traveling along the input path, the current input segment ends
- and a new input segment starts. In this case, the remaining distance on the
- first input segment is subtracted from the \meta{dimension} and then we
- travel along the second input segment for the remaining distance. This
- input segment may also end early, in which case we travel along the next
- input segment, and so on. Note that it cannot happen that we travel past
- the end of the input path since this would have caused an immediate switch
- to the |final| state.
-
- Note that the computation of the path lengths has only a low accuracy
- because of \TeX's small math capabilities. Do not expect high accuracy
- alignments when using decorations (unless the input path consists only of
- horizontal and vertical lines).
-
- The \meta{states} argument should consist of |\state| commands, one for
- each state of the decoration automaton. The |\state| command is defined
- only when the \meta{states} argument is executed.
-
- \begin{command}{\state\marg{name}\oarg{options}\marg{code}}
- This command declares a new state inside the current decoration
- automaton. The state is named \meta{name}.
-
- When the decoration automaton is in state \meta{name}, the following
- things happen:
- %
- \begin{enumerate}
- \item The \meta{options} are parsed. This may lead to a state
- switch, see below. When this happens, the following steps are
- not executed. The \meta{options} are executed one after the
- other in the given order. If an option causes a state switch,
- the switch is immediate, even if later options might cause a
- different state switch.
- \item The \meta{code} is executed in a \TeX-group with the current
- transformation matrix set up in such a way that the origin is
- on the input path at the current point (the point at the
- distance traveled up to now) and the coordinate system is
- rotated in such a way that the positive $x$-axis points in the
- direction of the tangent to the input path at the current
- point, while the positive $y$-axis points to the left of this
- tangent.
-
- As described earlier, the \meta{code} can have two different
- effects: If it just contains path construction commands, the
- decoration will produce an output path, that is, it extends the
- preexisting path. Here is an example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations}}]
-\pgfdeclaredecoration{example}{initial}
-{
- \state{initial}[width=10pt]
- {
- \pgfpathlineto{\pgfpoint{0pt}{5pt}}
- \pgfpathlineto{\pgfpoint{5pt}{5pt}}
- \pgfpathlineto{\pgfpoint{5pt}{-5pt}}
- \pgfpathlineto{\pgfpoint{10pt}{-5pt}}
- \pgfpathlineto{\pgfpoint{10pt}{0pt}}
- }
- \state{final}
- {
- \pgfpathlineto{\pgfpointdecoratedpathlast}
- }
-}
-\tikz[decoration=example]
-{
- \draw [decorate] (0,0) -- (3,0);
- \draw [red,decorate] (0,0) to [out=45,in=135] (3,0);
-}
-\end{codeexample}
-
- Alternatively, the \meta{code} can also contain the
- |\pgfusepath| command. This will use the path in the usual
- manner, where ``the path'' is the preexisting path plus a part
- of the output path for the first invocation and the different
- parts of the rest of the output path for the following
- invocation. Here is an example:
- %
-\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{decorations,shapes.geometric}}]
-\pgfdeclaredecoration{stars}{initial}{
- \state{initial}[width=15pt]
- {
- \pgfmathparse{round(rnd*100)}
- \pgfsetfillcolor{yellow!\pgfmathresult!orange}
- \pgfsetstrokecolor{yellow!\pgfmathresult!red}
- \pgfnode{star}{center}{}{}{\pgfusepath{stroke,fill}}
- }
- \state{final}
- {
- \pgfpathmoveto{\pgfpointdecoratedpathlast}
- }
-}
-\tikz\path[decorate, decoration=stars, star point ratio=2, star points=5,
- inner sep=0, minimum size=rnd*10pt+2pt]
- (0,0) .. controls (0,2) and (3,2) .. (3,0)
- .. controls (3,-3) and (0,0) .. (0,-3)
- .. controls (0,-5) and (3,-5) .. (3,-3);
-\end{codeexample}
- %
- \item After the \meta{code} has been executed (possibly more than
- once, if the |repeat state| option is used), the state switches
- to whatever state has been specified inside the \meta{options}
- using the |next state| option. If no |next state| has been
- specified, the state stays the same.
- \end{enumerate}
-
- The \meta{options} are executed with the key path set to
- |/pgf/decoration automaton|. The following keys are defined:
- %
- \begin{key}{/pgf/decoration automaton/switch if less than=\meta{dimension}\texttt{ to }\meta{new state}}
- When this key is encountered, \pgfname\ checks whether the
- remaining distance to the end of the input path is less than
- \meta{dimension}. If so, an immediate state switch to \meta{new
- state} occurs.
- \end{key}
- %
- \begin{key}{/pgf/decoration automaton/switch if input segment less than=\\\meta{dimension}\texttt{ to }\meta{new state}}
- When this key is encountered, \pgfname\ checks whether the
- remaining distance to the end of the current input segment of the
- input path is less than \meta{dimension}. If so, an immediate state
- switch to \meta{new state} occurs.
- \end{key}
- %
- \begin{key}{/pgf/decoration automaton/width=\meta{dimension}}
- First, this option causes an immediate switch to the state |final|
- if the remaining distance on the input path is less than
- \meta{dimension}. The effect is the same as if you had said
- |switch if less than=|\meta{dimension}| to final| just before the
- |width| option.
-
- If no switch occurs, this option tells \pgfname\ the width of the
- segment. The current point will travel along the input path (as
- described earlier) by this distance.
- \end{key}
- %
- \begin{key}{/pgf/decoration automaton/repeat state=\meta{repetitions} (initially 0)}
- Tells \pgfname\ how long the automaton stays ``normally'' in the
- current state. This count is reset to \meta{repetitions} each time
- one of the |switch if| keys causes a state switch. If no state
- switches occur, the \meta{code} is executed and the repetition
- counter is decreased. Then, there is once more a chance of a state
- change caused by any of the \meta{options}. If no repetition
- occurs, the \meta{code} is executed once more and the counter is
- decreased once more. When the counter reaches zero, the \meta{code}
- is executed once more, but, then, a different state is entered, as
- specified by the |next state| option.
-
- Note, that the maximum number of times the state will be executed
- is $\meta{repetitions}+1$.
- \end{key}
- %
- \begin{key}{/pgf/decoration automaton/next state=\meta{new state}}
- After the \meta{code} for state has been executed for the last
- time, a state switch to \meta{new state} is performed. If this
- option is not given, the next state is the same as the current
- state.
- \end{key}
-
- \begin{key}{/pgf/decoration automaton/if input segment is closepath=\meta{options}}
- This key checks whether the current input segment is a closepath
- operation. If so, the \meta{options} get executed; otherwise
- nothing happens. You can use this option to handle a closepath in
- some special way, for instance, switching to a new state in which
- |\pgfpathclose| is executed.
- \end{key}
-
- \begin{key}{/pgf/decoration automaton/auto end on length=\meta{dimension}}
- This key is just included for convenience, it does nothing that
- cannot be achieved using the previous options. The effect is the
- following: If the remaining input path's length is at most
- \meta{dimension}, the decorated path is ended with a straight line
- to the end of the input path and, possibly, it is closed, namely if
- the input path ended with a closepath operation. Otherwise, it is
- checked whether the current input segment is a closepath segment
- and whether the remaining distance on the current input segment is
- at most \meta{distance}. If so, then a closepath operation is used
- to close the decorated path and the automaton continues with the
- next subpath, remaining in the current state.
-
- In all other cases, nothing happens.
- \end{key}
-
- \begin{key}{/pgf/decoration automaton/auto corner on length=\meta{dimension}}
- This key has the following effect: Firstly, in case the \TeX-if
- |\ifpgfdecoratepathhascorners| is false, nothing happens.
- Otherwise, it is tested whether the remaining distance on the
- current input segment is at most \meta{dimension}. If so, a
- |lineto| operation is used to reach the end of this input segment
- and the automaton continues with the next input segment, but
- remains in the current state.
-
- The main idea behind this option is to avoid having decoration
- segments ``overshoot'' past a corner.
- \end{key}
-
- You may sometimes wish to do computations outside the transformational
- \TeX-group of the current segment, so that these results of these
- computations are available in the next state. For this, the following
- two options are useful:
-
- \begin{key}{/pgf/decoration automaton/persistent precomputation=\meta{precode}}
- If the \meta{code} of the state is executed, the \meta{precode} is
- executed first and it is executed outside the \TeX-group of the
- \meta{code}. Note that when the \meta{precode} is executed, the
- transformation matrix is not set up.
- \end{key}
-
- \begin{key}{/pgf/decoration automaton/persistent postcomputation=\meta{postcode}}
- Works like the |persistent precomputation| option, only the
- \meta{postcode} is executed after (and also outside) the \TeX-group
- of the main \meta{code}.
- \end{key}
-
- There are a number of macros and dimensions which may be useful inside
- a decoration automaton. The following macros are available:
-
- \begin{command}{\pgfdecoratedpathlength}
- The length of the input path. If the input path consists of several
- input segments, this number is the sum of the lengths of the input
- segments.
- \end{command}
-
- \begin{command}{\pgfdecoratedinputsegmentlength}
- The length of the current input segment of the input path.
- ``Current input segment'' refers to the input segment on which the
- current point lies.
- \end{command}
-
- \begin{command}{\pgfpointdecoratedpathlast}
- The final point of the input path.
- \end{command}
-
- \begin{command}{\pgfpointdecoratedinputsegmentlast}
- The final point of the current input segment of the input path.
- \end{command}
-
- \begin{command}{\pgfdecoratedangle}
- The angle of the tangent to the decorated path at the \emph{origin}
- of the current segment. The transformation matrix applied at the
- beginning of a state includes a rotation equivalent to this angle.
- \end{command}
-
- The following \TeX\ dimension registers are also available inside the
- automaton:
-
- \begin{command}{\pgfdecoratedremainingdistance}
- The remaining distance on the input path.
- \end{command}
-
- \begin{command}{\pgfdecoratedcompleteddistance}
- The completed distance on the input path.
- \end{command}
-
- \begin{command}{\pgfdecoratedinputsegmentremainingdistance}
- The remaining distance on the current input segment of the input path.
- \end{command}
-
- \begin{command}{\pgfdecoratedinputsegmentcompleteddistance}
- The completed distance on the current input segment of the input path.
- \end{command}
-
- Further keys and macros are defined and used by the decoration
- libraries, see Section~\ref{section-library-decorations}.
-
- The following example shows how these options can be used:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations}}]
-\pgfdeclaredecoration{complicated example decoration}{initial}
-{
- \state{initial}[width=5pt,next state=up]
- { \pgfpathlineto{\pgfpoint{5pt}{0pt}} }
-
- \state{up}[width=5pt,next state=down]
- {
- \ifdim\pgfdecoratedremainingdistance>\pgfdecoratedcompleteddistance
- % Growing
- \pgfpathlineto{\pgfpoint{0pt}{\pgfdecoratedcompleteddistance}}
- \pgfpathlineto{\pgfpoint{5pt}{\pgfdecoratedcompleteddistance}}
- \pgfpathlineto{\pgfpoint{5pt}{0pt}}
- \else
- % Shrinking
- \pgfpathlineto{\pgfpoint{0pt}{\pgfdecoratedremainingdistance}}
- \pgfpathlineto{\pgfpoint{5pt}{\pgfdecoratedremainingdistance}}
- \pgfpathlineto{\pgfpoint{5pt}{0pt}}
- \fi%
- }
- \state{down}[width=5pt,next state=up]
- {
- \ifdim\pgfdecoratedremainingdistance>\pgfdecoratedcompleteddistance
- % Growing
- \pgfpathlineto{\pgfpoint{0pt}{-\pgfdecoratedcompleteddistance}}
- \pgfpathlineto{\pgfpoint{5pt}{-\pgfdecoratedcompleteddistance}}
- \pgfpathlineto{\pgfpoint{5pt}{0pt}}
- \else
- % Shrinking
- \pgfpathlineto{\pgfpoint{0pt}{-\pgfdecoratedremainingdistance}}
- \pgfpathlineto{\pgfpoint{5pt}{-\pgfdecoratedremainingdistance}}
- \pgfpathlineto{\pgfpoint{5pt}{0pt}}
- \fi%
- }
- \state{final}
- {
- \pgfpathlineto{\pgfpointdecoratedpathlast}
- }
-}
-\begin{tikzpicture}[decoration=complicated example decoration]
- \draw decorate{ (0,0) -- (3,0)};
- \fill [red!50,rounded corners=2pt]
- decorate {(.5,-2) -- ++(2.5,-2.5)} -- (3,-5) -| (0,-2) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- \end{command}
-\end{command}
-
-
-\subsubsection{Predefined Decorations}
-
-The three decorations |moveto|, |lineto|, and |curveto| are predefined and
-``always available''. They are mostly useful in conjunction with
-meta-decorations. They are documented in
-Section~\ref{section-library-decorations} alongside the other decorations.
-
-
-\subsection{Using Decorations}
-
-Once a decoration has been declared, it can be used.
-
-\begin{environment}{{pgfdecoration}\marg{decoration list}}
- The \meta{environment contents} should contain commands for creating an
- path. This path is the basis for the \emph{input paths} for the decorations
- in the \meta{decoration list}. In detail, the following happens:
- %
- \begin{enumerate}
- \item The preexisting unused path is saved.
- \item The path commands specified in \meta{environment contents} are
- executed and this resulting path is saved. The path is then divided
- into different \emph{input paths} as follows: The format for each
- item in \marg{decoration list} is
- %
- \begin{quote}
- \marg{decoration}\marg{length}\opt{\marg{before code}\marg{after code}}
- \end{quote}
- %
- The \meta{before code} and the \meta{after code} are optional. The
- input path is divided into input paths as follows: The first input
- path consists of the first lines of the path specified in the
- \meta{environment contents} until the \meta{length} of the first
- element of the \meta{decoration list} is reached. If this length is
- reached in the middle of a line, the line is broken up at this
- exact position. Then the second input path has the \meta{length} of
- the second element in the \meta{decoration list} and consists of
- the lines making up the following \meta{length} part of the path in
- the \meta{environment contents}, and so on.
-
- If the lengths in the \meta{decoration list} do not add up to the
- total length of the path in the \meta{environment contents}, either
- some decorations are dropped (if their lengths add up to more than
- the length of the \meta{environment contents}) or the input path is
- not fully used (if their lengths add up to less).
- \item The preexisting path is reinstalled.
- \item The decoration automata move along the input paths, thus creating
- (and possibly using) the output paths. These output paths extend
- the current path (unless they are used).
- \end{enumerate}
-
- Some important points should be noted regarding the use of this
- environment:
- %
- \begin{itemize}
- \item If \meta{environment contents} does not begin with
- |\pgfpathmoveto|, the last known point on the preexisting path is
- assumed as the starting point.
- \item All except the last of any sequence of consecutive move-to
- commands in \meta{environment contents} are discarded.
- \item Any move-to commands at the end of \meta{environment contents}
- are ignored.
- \item Any close-path commands on the input path are interpreted as
- straight lines. Internally, something a little more complicated is
- going on, however, a closed path on the input path has no effect on
- the output path, other than causing the automaton to travel in a
- straight line towards the location of the last move-to command on
- the input path.
- \item Although tangent computations for the input path work with the
- last point on the preexisting path, no automatic move-to operations
- are issued for the output path. If an output path starts with a
- line-to or curve-to when the existing path is empty, an appropriate
- move-to command should be inserted before the decoration starts.
- \item If a decoration uses its own path, the first time this happens
- the preexisting path is part of the path that is used at this
- point.
- \end{itemize}
-
- Before the automata start to ``work on'' their respective inputs paths,
- \meta{before code} is executed. After the decoration automaton has
- finished, \meta{after code} is executed.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
-\begin{tikzpicture}[decoration={segment length=5pt}]
- \draw [help lines] grid (3,2);
- \begin{pgfdecoration}{{curveto}{1cm},{zigzag}{2cm},{curveto}{1cm}}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathcurveto
- {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}}
- \end{pgfdecoration}
-\pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
-
- When the lengths are evaluated, the dimension
- |\pgfdecoratedremainingdistance| holds the remaining distance on the entire
- decorated path, and |\pgfdecoratedpathlength| holds the total length of the
- path. Thus, it is possible to specify lengths like
- |\pgfdecoratedpathlength/3|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
-\begin{tikzpicture}[decoration={segment length=5pt}]
- \draw [help lines] grid (3,2);
- \begin{pgfdecoration}{
- {curveto}{\pgfdecoratedpathlength/3},
- {zigzag}{\pgfdecoratedpathlength/3},
- {curveto}{\pgfdecoratedremainingdistance}
- }
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathcurveto
- {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}}
- \end{pgfdecoration}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
-
- When \meta{before code} is executed, the following macro is useful:
- %
- \begin{command}{\pgfpointdecoratedpathfirst}
- Returns the point corresponding to the start of the current input path.
- \end{command}
- %
- When \meta{after code} is executed, the following macro can be used:
- %
- \begin{command}{\pgfpointdecoratedpathlast}
- Returns the point corresponding to the end of the current input path.
- \end{command}
- %
- This means that if decorations do not use their own path, it is possible to
- do something with them and continue from the correct place.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \begin{pgfdecoration}{
- {curveto}{\pgfdecoratedpathlength/3}
- {}
- {
- \pgfusepath{stroke}
- },
- {zigzag}{\pgfdecoratedpathlength/3}
- {
- \pgfpathmoveto{\pgfpointdecoratedpathfirst}
- \pgfdecorationsegmentlength=5pt
- }
- {
- \pgfsetstrokecolor{red}
- \pgfusepath{stroke}
- \pgfpathmoveto{\pgfpointdecoratedpathlast}
- \pgfsetstrokecolor{black}
- },
- {curveto}{\pgfdecoratedremainingdistance}
- }
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathcurveto
- {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}}
- \end{pgfdecoration}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
-
- After the |{decoration}| environment has finished, the following macros are
- available:
-
- \begin{command}{\pgfdecorateexistingpath}
- The preexisting path before the environment was entered.
- \end{command}
-
- \begin{command}{\pgfdecoratedpath}
- The (total) input path (that is, the path created by the environment
- contents).
- \end{command}
-
- \begin{command}{\pgfdecorationpath}
- The output path. If the path is used, this macro contains only the last
- unused part of the output path.
- \end{command}
-
- \begin{command}{\pgfpointdecoratedpathlast}
- The final point of the input path.
- \end{command}
-
- \begin{command}{\pgfpointdecorationpathlast}
- The final point of the output path.
- \end{command}
-
- The following style is executed each time a decoration is used. You may use
- it to set up default options for decorations.
- %
- \begin{stylekey}{/pgf/every decoration (initially \normalfont empty)}
- This style is executed for every decoration.
- \end{stylekey}
-\end{environment}
-
-\begin{plainenvironment}{{pgfdecoration}\marg{name}}
- The plain-\TeX{} version of the |{pgfdecorate}| environment.
- \todosp{`pgfdecorate' right or `pgfdecoration'? really no idea}
-\end{plainenvironment}
-
-\begin{contextenvironment}{{pgfdecoration}\marg{name}}
- The Con\TeX t version of the |{pgfdecoration}| environment.
-\end{contextenvironment}
-
-For convenience, the following macros provide a ``shorthand'' for decorations
-(internally, they all use the |{pgfdecoration}| environment).
-
-\begin{command}{\pgfdecoratepath\marg{name}\marg{path commands}}
- Decorate the path described by \meta{path commands} with the decoration
- \meta{name}. This is equivalent to
- %
-\begin{codeexample}[code only]
-\pgfdecorate{{name}{\pgfdecoratedpathlength}
- {\pgfdecoratebeforecode}{\pgfdecorateaftercode}}
- // the path commands.
-\endpgfdecorate
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfdecoratecurrentpath\marg{name}}
- Decorate the preexisting path with the decoration \meta{name}.
-\end{command}
-
-Both the above commands use the current definitions of the following macros:
-
-\begin{command}{\pgfdecoratebeforecode}
- Code executed as \meta{before code}, see the description of |\pgfdecorate|.
-\end{command}
-
-\begin{command}{\pgfdecorateaftercode}
- Code executed as \meta{after code}, see the description of |\pgfdecorate|.
-\end{command}
-
-It may sometimes be useful to add an additional transformation for each segment
-of a decoration. The following command allows you to define such a ``last
-minute transformation''.
-
-\begin{command}{\pgfsetdecorationsegmenttransformation\marg{code}}
- The \meta{code} will be executed at the very beginning of each segment.
- Note when applying multiple decorations, this will be reset between
- decorations, so it needs to be specified for each segment.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \begin{pgfdecoration}{
- {curveto}{\pgfdecoratedpathlength/3},
- {zigzag}{\pgfdecoratedpathlength/3}
- {
- \pgfdecorationsegmentlength=5pt
- \pgfsetdecorationsegmenttransformation{\pgftransformyshift{.5cm}}
- },
- {curveto}{\pgfdecoratedremainingdistance}
- }
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathcurveto
- {\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}{\pgfpoint{3cm}{0cm}}
- \end{pgfdecoration}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Meta-Decorations}
-\label{section-base-meta-decorations}
-
-A meta-decoration provides an alternative way to decorate a path with multiple
-decorations. It is, in essence, an automaton that decorates an input path with
-decoration automatons. In general, however, the end effect is still that a path
-is decorated with other paths, and the input path should be thought of as being
-divided into sub-input-paths, each with their own decoration. Like ordinary
-decorations, a meta-decoration must be declared before it can be used.
-
-
-\subsubsection{Declaring Meta-Decorations}
-
-\begin{command}{\pgfdeclaremetadecorate\marg{name}\marg{initial state}\marg{states}}
- This command declares a new meta-decoration called \meta{name}. The
- \meta{states} argument contains a description of the meta-decoration
- automaton's states and the transitions between them. The \meta{initial
- state} is the state in which the automaton starts.
-
- The |\state| command is similar to the one found in decoration
- declarations, and takes the same form:
-
- \begin{command}{\state\marg{name}\oarg{options}\marg{code}} Declares the
- state \meta{name} inside the current meta-decoration automaton. Unlike
- decorations, states in meta-decorations are not executed within a
- group, which makes the persistent computation options superfluous.
- Consider using an initial state with |width=0pt| to do precalculations
- that could speed the execution of the meta-decoration.
-
- The \meta{options} are executed with the key path set to
- |/pgf/meta-decorations automaton/|, and the following keys are defined
- for this path:
-
- \begin{key}{/pgf/meta-decoration automaton/switch if less than=\meta{dimension}| to |\meta{new state}}
- This causes \pgfname\ to check whether the remaining distance to
- the end of the input path is less than \meta{dimension}, and, if
- so, to immediately switch to the state \meta{new state}. When this
- key is evaluated, the macro |\pgfmetadecoratedpathlength| will be
- defined as the total length of the decoration path, allowing for
- values such as |\pgfmetadecoratedpathlength/8|.
- \end{key}
-
- \begin{key}{/pgf/meta-decoration automaton/width=\meta{dimension}}
- As always, this option will cause an immediate switch to the state
- |final| if the remaining distance on the input path is less than
- \meta{dimension}.
-
- Otherwise, this option tells \pgfname\ the width of the
- ``meta-segment'', that is, the length of the sub-input-path which
- the decoration automaton specified in \meta{code} will decorate.
- \end{key}
-
- \begin{key}{/pgf/meta-decoration automaton/next state=\meta{new state}}
- After the code for a state has been executed, a state switch to
- \meta{new state} is performed. If this option is not given, the
- next state is the same as the current state.
- \end{key}
-
- The code in \meta{code} is quite different from the code in a
- decoration state. In almost all cases only the following three macros
- will be required:
-
- \begin{command}{\decoration\marg{name}}
- This sets the decoration for the current state to \meta{name}. If
- this command is omitted, the |moveto| decoration will be used.
- \end{command}
-
- \begin{command}{\beforedecoration\marg{before code}}
- Defines \meta{before code} as (typically) \pgfname{} commands to be
- executed before the decoration is applied to the current segment.
- This command can be omitted. If you wish to set up some decoration
- specific parameters such as segment length, or segment amplitude,
- then they can be set in \meta{before code}.
- \end{command}
-
- \begin{command}{\afterdecoration\marg{after code}}
- Defines \meta{after code} as commands to be executed after the
- decoration has been applied to the current segment. This command
- can be omitted.
- \end{command}
-
- There are some macros that may be useful when creating meta-decorations
- (note that they are all macros):
-
- \begin{command}{\pgfpointmetadecoratedpathfirst}
- When the \meta{before code} is executed, this macro stores the
- first point on the current sub-input-path.
- \end{command}
-
- \begin{command}{\pgfpointmetadecoratedpathlast}
- When the \meta{after code} is executed, this macro stores the last
- point on the current sub-input-path.
- \end{command}
-
- \begin{command}{\pgfmetadecoratedpathlength}
- The entire length of the entire input path.
- \end{command}
-
- \begin{command}{\pgfmetadecoratedcompleteddistance}
- The completed distance on the entire input path.
- \end{command}
-
- \begin{command}{\pgfmetadecoratedremainingdistance}
- The remaining distance on the entire input path.
- \end{command}
-
- \begin{command}{\pgfmetadecoratedinputsegmentcompleteddistance}
- The completed distance on the current input segment of the entire
- input path.
- \end{command}
-
- \begin{command}{\pgfmetadecoratedinputsegmentremainingdistance}
- The remaining distance on the current input segment of the entire
- input path.
- \end{command}
- \end{command}
-
- Here is a complete example of a meta-decoration:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
-\pgfdeclaremetadecoration{arrows}{initial}{
- \state{initial}[width=0pt, next state=arrow]
- {
- \pgfmathdivide{100}{\pgfmetadecoratedpathlength}
- \let\factor\pgfmathresult
- \pgfsetlinewidth{1pt}
- \pgfset{/pgf/decoration/segment length=4pt}
- }
- \state{arrow}[
- switch if less than=\pgfmetadecorationsegmentlength to final,
- width=\pgfmetadecorationsegmentlength/3,
- next state=zigzag]
- {
- \decoration{curveto}
- \beforedecoration
- {
- \pgfmathparse{\pgfmetadecoratedcompleteddistance*\factor}
- \pgfsetcolor{red!\pgfmathresult!yellow}
- \pgfpathmoveto{\pgfpointmetadecoratedpathfirst}
- }
- }
- \state{zigzag}[width=\pgfmetadecorationsegmentlength/3, next state=end arrow]
- {
- \decoration{zigzag}
- }
- \state{end arrow}[width=\pgfmetadecorationsegmentlength/3, next state=move]
- {
- \decoration{curveto}
- \beforedecoration{\pgfpathmoveto{\pgfpointmetadecoratedpathfirst}}
- \afterdecoration
- {
- \pgfsetarrowsend{to}
- \pgfusepath{stroke}
- }
- }
- \state{move}[width=\pgfmetadecorationsegmentlength/2, next state=arrow]{}
- \state{final}{}
-}
-
-\tikz\draw[decorate,decoration={arrows,meta-segment length=2cm}]
- (0,0) .. controls (0,2) and (3,2) .. (3,0)
- .. controls (3,-2) and (0,-2) .. (0,-4)
- .. controls (0,-6) and (3,-6) .. (3,-8)
- .. controls (3,-10) and (0,-10) .. (0,-8);
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Predefined Meta-decorations}
-
-There are no predefined meta-decorations loaded with \pgfname{}.
-
-
-\subsubsection{Using Meta-Decorations}
-
-Using meta-decorations is ``simpler'' than using decorations, because you can
-only use one meta-decoration per path.
-
-\begin{environment}{{pgfmetadecoration}\marg{name}}
- This environment decorates the input path described in \meta{environment
- contents}, with the meta-decoration \meta{name}.
-\end{environment}
-
-\begin{plainenvironment}{{pgfmetadecoration}\marg{name}}
- The plain \TeX{} version of the |{pgfmetadecoration}| environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{pgfmetadecoration}\marg{name}}
- The Con\TeX t version of the |{pgfmetadecoration}| environment.
-\end{contextenvironment}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-design.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-design.tex
deleted file mode 100644
index fb7eacca2f..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-design.tex
+++ /dev/null
@@ -1,146 +0,0 @@
-% Copyright 2018 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{Design Principles}
-
-This section describes the basic layer of \pgfname. This layer is built on top
-of the system layer. Whereas the system layer just provides the absolute
-minimum for drawing graphics, the basic layer provides numerous commands that
-make it possible to create sophisticated graphics easily and also quickly.
-
-The basic layer does not provide a convenient syntax for describing graphics,
-which is left to frontends like \tikzname. For this reason, the basic layer is
-typically used only by ``other programs''. For example, the \textsc{beamer}
-package uses the basic layer extensively, but does not need a convenient input
-syntax. Rather, speed and flexibility are needed when \textsc{beamer} creates
-graphics.
-
-The following basic design principles underlie the basic layer:
-%
-\begin{enumerate}
- \item Structuring into a core and modules.
- \item Consistently named \TeX\ macros for all graphics commands.
- \item Path-centered description of graphics.
- \item Coordinate transformation system.
-\end{enumerate}
-
-
-\subsection{Core and Modules}
-
-The basic layer consists of a \emph{core package}, called |pgfcore|, which
-provides the most basic commands, and several \emph{modules} like commands for
-plotting (in the |plot| module). Modules are loaded using the |\usepgfmodule|
-command.
-
-If you say |\usepackage{pgf}| or |\input pgf.tex| or |\usemodule[pgf]|, the
-|plot| and |shapes| modules are preloaded (as well as the core and the system
-layer).
-
-
-\subsection{Communicating with the Basic Layer via Macros}
-
-In order to ``communicate'' with the basic layer you use long sequences of
-commands that start with |\pgf|. You are only allowed to give these commands
-inside a |{pgfpicture}| environment. (Note that |{tikzpicture}| opens a
-|{pgfpicture}| internally, so you can freely mix \pgfname\ commands and
-\tikzname\ commands inside a |{tikzpicture}|.) It is possible to ``do other
-things'' between the commands. For example, you might use one command to move
-to a certain point, then have a complicated computation of the next point, and
-then move there.
-%
-\begin{codeexample}[]
-\newdimen\myypos
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpoint{0cm}{\myypos}}
- \pgfpathlineto{\pgfpoint{1cm}{\myypos}}
- \advance \myypos by 1cm
- \pgfpathlineto{\pgfpoint{1cm}{\myypos}}
- \pgfpathclose
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
-
-The following naming conventions are used in the basic layer:
-%
-\begin{enumerate}
- \item All commands and environments start with |pgf|.
- \item All commands that specify a point (a coordinate) start with
- |\pgfpoint|.
- \item All commands that extend the current path start with |\pgfpath|.
- \item All commands that set/change a graphics parameter start with
- |\pgfset|.
- \item All commands that use a previously declared object (like a path,
- image or shading) start with |\pgfuse|.
- \item All commands having to do with coordinate transformations start with
- |\pgftransform|.
- \item All commands having to do with arrow tips start with |\pgfarrows|.
- \item All commands for ``quickly'' extending or drawing a path start with
- |\pgfpathq| or |\pgfusepathq|.
- \item All commands having to do with matrices start with |\pgfmatrix|.
-\end{enumerate}
-
-
-\subsection{Path-Centered Approach}
-
-In \pgfname\ the most important entity is the \emph{path}. All graphics are
-composed of numerous paths that can be stroked, filled, shaded, or clipped
-against. Paths can be closed or open, they can self-intersect and consist of
-unconnected parts.
-
-Paths are first \emph{constructed} and then \emph{used}. In order to construct
-a path, you can use commands starting with |\pgfpath|. Each time such a command
-is called, the current path is extended in some way.
-
-Once a path has been completely constructed, you can use it using the command
-|\pgfusepath|. Depending on the parameters given to this command, the path will
-be stroked (drawn) or filled or subsequent drawings will be clipped against
-this path.
-
-
-\subsection{Coordinate Versus Canvas Transformations}
-\label{section-design-transformations}
-
-\pgfname\ provides two transformation systems: \pgfname's own \emph{coordinate}
-transformation matrix and \pdf's or PostScript's \emph{canvas} transformation
-matrix. These two systems are quite different. Whereas a scaling by a factor
-of, say, $2$ of the canvas causes \emph{everything} to be scaled by this factor
-(including the thickness of lines and text), a scaling of two in the coordinate
-system causes only the \emph{coordinates} to be scaled, but not the line width
-nor text.
-
-By default, all transformations only apply to the coordinate transformation
-system. However, using the command |\pgflowlevel| it is possible to apply a
-transformation to the canvas.
-
-Coordinate transformations are often preferable over canvas transformations.
-Text and lines that are transformed using canvas transformations suffer from
-differing sizes and lines whose thickness differs depending on whether the line
-is horizontal or vertical. To appreciate the difference, consider the following
-two ``circles'' both of which have been scaled in the $x$-direction by a factor
-of $3$ and by a factor of $0.5$ in the $y$-direction. The left circle uses a
-canvas transformation, the right uses \pgfname's coordinate transformation
-(some viewers will render the left graphic incorrectly since they do no apply
-the low-level transformation the way they should):
-
-\begin{tikzpicture}[line width=5pt]
- \useasboundingbox (-1.75,-1) rectangle (14,1);
-
- \begin{scope}
- \pgflowlevel{\pgftransformxscale{3}}
- \pgflowlevel{\pgftransformyscale{.5}}
-
- \draw (0,0) circle (0.5cm);
- \draw (.55cm,0pt) node[right] {canvas};
- \end{scope}
- \begin{scope}[xshift=9cm,xscale=3,yscale=.5]
- \draw (0,0) circle (0.5cm);
- \draw (.55cm,0pt) node[right] {coordinate};
- \end{scope}
-\end{tikzpicture}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-external.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-external.tex
deleted file mode 100644
index c6df6dc442..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-external.tex
+++ /dev/null
@@ -1,502 +0,0 @@
-% 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{Externalizing Graphics}
-\label{section-external}
-
-\subsection{Overview}
-
-There are two fundamentally different ways of inserting graphics into a
-\TeX-document. First, you can create a graphic using some external program like
-|xfig| or |InDesign| and then include this graphic in your text. This is done
-using commands like |\includegraphics| or |\pgfimage|. In this case, the
-graphic file contains all the low-level graphic commands that describe the
-picture. When such a file is included, all \TeX\ has to worry about is the size
-of the picture; the internals of the picture are unknown to \TeX\ and it does
-not care about them.
-
-The second method of creating graphics is to use a special package that
-transforms \TeX-commands like |\draw| or |\psline| into appropriate low-level
-graphic commands. In this case, \TeX\ has to do all the hard work of
-``typesetting'' the picture and if a picture has a complicated internal
-structure this may take a lot of time.
-
-While \pgfname\ was created to facilitate the second method of creating
-pictures, there are two main reasons why you may need to employ the first
-method of image-inclusion, nevertheless:
-%
-\begin{enumerate}
- \item Typesetting a picture using \TeX\ can be a very time-consuming
- process. If \TeX\ needs a minute to typeset a picture, you do not want
- to wait this minute when you re\TeX\ your document after having changed
- a single comma.
- \item Some users, especially journal editors, may not be able to process
- files that contain \pgfname\ commands -- for the simple reason that the
- systems of many publishing houses do not have \pgfname\ installed.
-\end{enumerate}
-
-In both cases, the solution is to ``extract'' or ``externalize'' pictures that
-would normally be typeset every time a document is \TeX ed. Once the pictures
-have been extracted into separate graphics files, these graphic files can be
-reinserted into the text using the first method.
-
-Extracting a graphic from a file is not as easy as it may sound at first since
-\TeX\ cannot write parts of its output into different files and a bit of
-trickery is needed. The following macros simplify the workflow:
-%
-\begin{enumerate}
- \item You have to tell \pgfname\ which files will be used for which
- pictures. To do so, you enclose each picture that you wish to be
- ``externalized'' in a pair of |\beginpgfgraphicnamed| and
- |\endpgfgraphicnamed| macros.
- \item The next step is to generate the extracted graphics. For this you run
- \TeX\ with the |\jobname| set to the graphic file's name. This will
- cause |\pgfname| to behave in a very special way: All of your document
- will simply be thrown away, \emph{except} for the single graphic having
- the same name as the current jobname.
- \item After you have run \TeX\ once for each graphic that your wish to
- externalize, you can rerun \TeX\ on your document normally. This will
- have the following effect: Each time a |\beginpgfgraphicnamed| is
- encountered, \pgfname\ checks whether a graphic file of the given name
- exists (if you did step 2, it will). If this graphic file exists, it
- will be input and the text till the corresponding |\endpgfgraphicnamed|
- will be ignored.
-\end{enumerate}
-
-In the rest of this section, the above workflow is explained in more detail.
-
-
-\subsection{Workflow Step 1: Naming Graphics}
-
-In order to put each graphic in an external file, you first need to tell
-\pgfname\ the names of these files.
-
-\begin{command}{\beginpgfgraphicnamed\marg{file name prefix}}
- This command indicates that everything up to the next call of
- |\endpgfgraphicnamed| is part of a graphic that should be placed in a file
- named \meta{file name prefix}|.|\meta{suffix}, where the \meta{suffix}
- depends on your backend driver. Typically, \meta{suffix} will be |dvi| or
- |pdf|.
-
- Here is a typical example of how this command is used:
- %
-\begin{codeexample}[code only]
-% In file main.tex:
-...
-As we see in Figure~\ref{fig1}, the world is flat.
-\begin{figure}
- \beginpgfgraphicnamed{graphic-of-flat-world}
- \begin{tikzpicture}
- \fill (0,0) circle (1cm);
- \end{tikzpicture}
- \endpgfgraphicnamed
- \caption{The flat world.}
- \label{fig1}
-\end{figure}
-\end{codeexample}
-
- Each graphic to be externalized should have a unique name. Note that this
- name will be used as the name of a file in the file system, so it should
- not contain any funny characters.
-
- This command can have three different effects:
- %
- \begin{enumerate}
- \item The easiest situation arises if there does not yet exist a
- graphic file called \meta{file name prefix}|.|\meta{suffix}, where
- the \meta{suffix} is one of the suffixes understood by your current
- backend driver (so |pdf| or |jpg| if you use |pdftex|, |eps| if you
- use |dvips|, and so on). In this case, both this command and the
- |\endpgfgraphicnamed| command simply have no effect.
- \item A more complex situation arises when a graphic file named
- \meta{file name prefix}|.|\meta{suffix} \emph{does} exist. In this
- case, this graphic file is included using the |\includegraphics|
- command%
- %
- \footnote{Actually, the command key \texttt{/pgf/images/include
- external} is invoked which calls an appropriate
- \texttt{\textbackslash includegraphics} command.}.
- %
- Furthermore, the text between |\beginpgfgraphicnamed| and
- |\endpgfgraphicnamed| is ignored.
-
- When the text is ``ignored'', what actually happens is that all
- text up to the next occurrence of |\endpgfgraphicnamed| is thrown
- away without any macro expansion. This means, in particular, that
- (a) you cannot put |\endpgfgraphicnamed| inside a macro and (b) the
- macros used in the graphics need not be defined at all when the
- graphic file is included. \item The most complex behavior arises
- when current the |\jobname| equals the \meta{file name prefix} and,
- furthermore, the \emph{real job name} has been declared. The
- behavior for this case is explained later.
- \end{enumerate}
-
- Note that the |\beginpgfgraphicnamed| does not really have any effect until
- you have generated the graphic files named. Till then, this command is
- simply ignored. Also, if you delete the graphics file later on, the
- graphics are typeset normally once more.
-\end{command}
-
-\begin{command}{\endpgfgraphicnamed}
- This command just marks the end of the graphic that should be externalized.
-\end{command}
-
-
-\subsection{Workflow Step 2: Generating the External Graphics}
-
-We have now indicated all the graphics for which we would like graphic files to
-be generated. In order to generate the files, you now need to modify the
-|\jobname| appropriately. This is done in two steps:
-%
-\begin{enumerate}
- \item You use the following command to tell \pgfname\ the real name of your
- |.tex| file:
- %
- \begin{command}{\pgfrealjobname\marg{name}}
- Tells \pgfname\ the real name of your job. For instance, if you
- have a file called |survey.tex| that contains two graphics that you
- wish to be called |survey-graphic1| and |survey-graphic2|, then you
- should write the following.
- %
-\begin{codeexample}[code only]
-% This is file survey.tex
-\documentclass{article}
-...
-\usepackage{tikz}
-\pgfrealjobname{survey}
-\end{codeexample}
- \end{command}
- \item You run \TeX\ with the |\jobname| set to the name of the graphic for
- which you need an external graphic to be generated. To set the
- |\jobname|, you use the |--jobname=| option of \TeX:
- %
-\begin{codeexample}[code only, tikz syntax=false]
-bash> latex --jobname=survey-graphic1 survey.tex
-\end{codeexample}
- %
-\end{enumerate}
-
-The following things will now happen:
-%
-\begin{enumerate}
- \item |\pgfrealjobname| notices that the |\jobname| is not the ``real''
- jobname and, thus, must be the name of a graphic that is to be put in
- an external file.
- \item At the beginning of the document, \pgfname\ changes the definition of
- \TeX's internal |\shipout| macro. The new shipout macro simply throws
- away the output. This means that the document is typeset normally, but
- no output is produced.
- \item When the |\beginpgfgraphicnamed{|\meta{name}|}| command is
- encountered where the \meta{name} is the same as the current
- |\jobname|, then a \TeX-box is started and \meta{everything} up to the
- following |\endpgfgraphicnamed| command is stored inside this box.
-
- Note that, typically, \meta{everything} will contain just a single
- |{tikzpicture}| or |{pgfpicture}| environment. However, this need not
- be the case, you can use, say, a |{pspicture}| environment as
- \meta{everything} or even just some normal \TeX-text.
- \item At the |\endpgfgraphicnamed|, the box \emph{is} shipped out using the
- original |\shipout| command. Thus, unlike everything else, the contents
- of the graphic is made part of the output.
- \item When the box containing the graphic is shipped out, the paper size is
- modified such that it is exactly equal to the height and width of the
- box.
-\end{enumerate}
-
-The net effect of everything described above is that the two commands
-%
-\begin{codeexample}[code only, tikz syntax=false]
-bash> latex --jobname=survey-graphic1 survey.tex
-bash> dvips survey-graphic1
-\end{codeexample}
-%
-\noindent produce a file called |survey-graphic1.ps| that consists of a single
-page that contains exactly the graphic produced by the code between
-|\beginpgfgraphicnamed{survey-graphic1}| and |\endpgfgraphicnamed|.
-Furthermore, the size of this single page is exactly the size of the graphic.
-
-If you use pdf\TeX, producing the graphic is even simpler:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-bash> pdflatex --jobname=survey-graphic1 survey.tex
-\end{codeexample}
-%
-\noindent produces the single-page |pdf|-file |survey-graphic1.pdf|.
-
-
-\subsection{Workflow Step 3: Including the External Graphics}
-
-Once you have produced all the pictures in the text, including them into the
-main document is easy: Simply run \TeX\ again without any modification of the
-|\jobname|. In this case the |\pgfrealjobname| command will notice that the
-main file is, indeed, the main file. The main file will then be typeset
-normally and the |\beginpgfgraphicnamed| commands also behave normally, which
-means that they will try to include the generated graphic files -- which is
-exactly what you want.
-
-Suppose that you wish to send your survey to a journal that does not have
-\pgfname\ installed. In this case, you now have all the necessary external
-graphics, but you still need \pgfname\ to automatically include them instead of
-the executing the picture code! One way to solve this problem is to simply
-delete all of the \pgfname\ or \tikzname\ code from your |survey.tex| and
-instead insert appropriate |\includegraphics| commands ``by hand''. However,
-there is a better way: You input the file |pgfexternal.tex|.
-
-\begin{filedescription}{pgfexternal.tex}
- This file defines the command |\beginpgfgraphicnamed| and causes it to have
- the following effect: It includes the graphic file given as a parameter to
- it and then gobbles everything up to |\endpgfgraphicnamed|.
-
- Since |\beginpgfgraphicnamed| does not do macro expansion as it searches
- for |\endpgfgraphicnamed|, it is not necessary to actually include the
- packages necessary for \emph{creating} the graphics. So the idea is that
- you comment out things like |\usepackage{tikz}| and instead say
- |\input pgfexternal.tex|.
-
- Indeed, the contents of this file is simply the following line:
- %
-\begin{codeexample}[code only]
-\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{\includegraphics{#1}}
-\end{codeexample}
-
- Instead of |\input pgfexternal.tex| you could also include this line in
- your main file.
-\end{filedescription}
-
-As a final remark, note that the |baseline| option does not work directly with
-pictures written to an external graphic file. The simple reason is that there
-is no way to store this baseline information in an external graphic file. To
-allow the |baseline| option (or any \TeX\ construction with non-zero depth),
-the baseline information is stored into a separate file. This file is named
-\marg{image file}|.dpth| and contains something like |5pt|.
-
-So, if you need baseline information, you will have to keep the external
-graphic file together with its~|.dpth| file. Furthermore, the short command in
-|\input pgfexternal.tex| is no longer enough because it ignores any baseline
-information. You will need to use |\input pgfexternalwithdepth.tex| instead (it
-is shown below). It is slightly longer, but it can be used in the same way as
-|pgfexternal.tex|.
-
-\begin{key}{/pgf/images/include external (initially \textbackslash pgfimage\{\#1\})}
-\label{pgf:includeexternalkey}
-\index{External Graphics!Bounding Box Issues}
- This key constitutes the public interface to exchange the
- |\includegraphics| command used for the image inclusion.
-
- Redefining this key allows to provide bounding box or viewport options:
- %
-\begin{codeexample}[code only]
-\pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}}
-\end{codeexample}
- %
- Do not forget the |.code| here which redefines the command.
-
- One application could be image externalization and bounding box
- restrictions: As far as I know, a |.pdf| graphics with restricted bounding
- box is always cropped (which is not always desired). One solution could be
- to use |latex| and |dvips| which doesn't have this restriction. Another is
- to manually provide the |viewport| option as shown above.
-
- A possible value for |viewport| can be found in the |.pdf| image, search
- for |/MediaBox = [ ... ]|.
-\end{key}
-
-
-\subsection{A Complete Example}
-
-Let us now have a look at a simple, but complete example. We start out with a
-normal file called |survey.tex| that has the following contents:
-%
-\begin{codeexample}[code only]
-% This is the file survey.tex
-\documentclass{article}
-
-\usepackage{graphics}
-\usepackage{tikz}
-
-\begin{document}
-In the following figure, we see a circle:
-\begin{tikzpicture}
- \fill (0,0) circle (10pt);
-\end{tikzpicture}
-
-By comparison, in this figure we see a rectangle:
-\begin{tikzpicture}
- \fill (0,0) rectangle (10pt,10pt);
-\end{tikzpicture}
-\end{document}
-\end{codeexample}
-
-Now our editor tells us that the publisher will need all figures to be provided
-in separate PostScript or |.pdf|-files. For this, we enclose all figures in
-|...graphicnamed|-pairs and we add a call to the |\pgfrealjobname| macro:
-%
-\begin{codeexample}[code only]
-% This is the file survey.tex
-\documentclass{article}
-
-\usepackage{graphics}
-\usepackage{tikz}
-\pgfrealjobname{survey}
-
-\begin{document}
-In the following figure, we see a circle:
-\beginpgfgraphicnamed{survey-f1}
-\begin{tikzpicture}
- \fill (0,0) circle (10pt);
-\end{tikzpicture}
-\endpgfgraphicnamed
-
-By comparison, in this figure we see a rectangle:
-\beginpgfgraphicnamed{survey-f2}
-\begin{tikzpicture}
- \fill (0,0) rectangle (10pt,10pt);
-\end{tikzpicture}
-\endpgfgraphicnamed
-\end{document}
-\end{codeexample}
-
-After these changes, typesetting the file will still yield the same output as
-it did before -- after all, we have not yet created any external graphics.
-
-To create the external graphics, we run |pdflatex| twice, once for each
-graphic:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-bash> pdflatex --jobname=survey-f1 survey.tex
-This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6)
-entering extended mode
-(./survey.tex
-LaTeX2e <2005/12/01>
-...
-) [1] (./survey-f1.aux) )
-Output written on survey-f1.pdf (1 page, 1016 bytes).
-Transcript written on survey-f1.log.
-\end{codeexample}
-
-\begin{codeexample}[code only, tikz syntax=false]
-bash> pdflatex --jobname=survey-f2 survey.tex
-This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6)
-entering extended mode
-(./survey.tex
-LaTeX2e <2005/12/01>
-...
-(./survey-f2.aux) )
-Output written on survey-f2.pdf (1 page, 1002 bytes).
-Transcript written on survey-f2.log.
-\end{codeexample}
-
-We can now send the two generated graphics (|survey-f1.pdf| and
-|survey-f2.pdf|) to the editor. However, the publisher cannot use our
-|survey.tex| file, yet. The reason is that it contains the command
-|\usepackage{tikz}| and they do not have \pgfname\ installed.
-
-Thus, we modify the main file |survey.tex| as follows:
-%
-\begin{codeexample}[code only]
-% This is the file survey.tex
-\documentclass{article}
-
-\usepackage{graphics}
-\input pgfexternal.tex
-% \usepackage{tikz}
-% \pgfrealjobname{survey}
-
-\begin{document}
-In the following figure, we see a circle:
-\beginpgfgraphicnamed{survey-f1}
-\begin{tikzpicture}
- \fill (0,0) circle (10pt);
-\end{tikzpicture}
-\endpgfgraphicnamed
-
-By comparison, in this figure we see a rectangle:
-\beginpgfgraphicnamed{survey-f2}
-\begin{tikzpicture}
- \fill (0,0) rectangle (10pt,10pt);
-\end{tikzpicture}
-\endpgfgraphicnamed
-\end{document}
-\end{codeexample}
-%
-If we now run pdf\LaTeX, then, indeed, \pgfname\ is no longer needed:
-% In the following, we switch off typesetting of listings because the
-% parentheses confuse the pretty printer
-%
-\begin{codeexample}[code only,typeset listing/.code=#1]
-bash> pdflatex survey.tex
-This is pdfTeX, Version 3.141592-1.40.3 (Web2C 7.5.6)
-entering extended mode
-(./survey.tex
-LaTeX2e <2005/12/01>
-Babel <v3.8h> and hyphenation patterns for english, ..., loaded.
-(/usr/local/gwTeX/texmf.texlive/tex/latex/base/article.cls
-Document Class: article 2005/09/16 v1.4f Standard LaTeX document class
-(/usr/local/gwTeX/texmf.texlive/tex/latex/base/size10.clo))
-(/usr/local/gwTeX/texmf.texlive/tex/latex/graphics/graphics.sty
-(/usr/local/gwTeX/texmf.texlive/tex/latex/graphics/trig.sty)
-(/usr/local/gwTeX/texmf.texlive/tex/latex/config/graphics.cfg)
-(/usr/local/gwTeX/texmf.texlive/tex/latex/pdftex-def/pdftex.def))
-(/Users/tantau/Library/texmf/tex/generic/pgf/generic/pgf/utilities/pgfexternal.
-tex) (./survey.aux)
-(/usr/local/gwTeX/texmf.texlive/tex/context/base/supp-pdf.tex
-[Loading MPS to PDF converter (version 2006.09.02).]
-) <survey-f1.pdf, id=1, 23.33318pt x 19.99973pt> <use survey-f1.pdf>
-<survey-f2.pdf, id=2, 13.33382pt x 10.00037pt> <use survey-f2.pdf> [1{/Users/ta
-ntau/Library/texmf/fonts/map/pdftex/updmap/pdftex.map} <./survey-f1.pdf> <./sur
-vey-f2.pdf>] (./survey.aux) )</usr/local/gwTeX/texmf.texlive/fonts/type1/bluesk
-y/cm/cmr10.pfb>
-Output written on survey.pdf (1 page, 10006 bytes).
-Transcript written on survey.log.
-\end{codeexample}
-
-To our editor, we send the following files:
-%
-\begin{itemize}
- \item The last |survey.tex| shown above.
- \item The graphic file |survey-f1.pdf|.
- \item The graphic file |survey-f2.pdf|.
- \item The file |pgfexternal.tex|, whose contents is simply
- %
-\begin{codeexample}[code only]
-\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{\includegraphics{#1}}
-\end{codeexample}
- %
- (Alternatively, we can also directly add this line to our |survey.tex|
- file).
-\end{itemize}
-%
-In case we have used the |baseline| option, we also need to include any |.dpth|
-files and we need to use the file |pgfexternalwithdepth.tex| instead of
-|pgfexternal.tex|. This file also checks for the existence of |.dpth| files
-containing baseline information, its contents is
-%
-\begin{codeexample}[code only]
-\long\def\beginpgfgraphicnamed#1#2\endpgfgraphicnamed{%
- \begingroup
- \setbox1=\hbox{\includegraphics{#1}}%
- \openin1=#1.dpth
- \ifeof1 \box1
- \else
- \read1 to\pgfincludeexternalgraphicsdp\closein1
- \dimen0=\pgfincludeexternalgraphicsdp\relax
- \hbox{\lower\dimen0 \box1 }%
- \fi
- \endgroup
-}
-\end{codeexample}
-%
-Again, we could simply copy these lines to our |survey.tex| file.
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-images.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-images.tex
deleted file mode 100644
index d5ea0b5d2e..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-images.tex
+++ /dev/null
@@ -1,274 +0,0 @@
-% 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{Declaring and Using Images}
-\label{section-images}
-
-This section describes the commands for creating images.
-
-
-\subsection{Overview}
-
-To be quite frank, \LaTeX's |\includegraphics| is designed better than
-\pgfname's image mechanism. For this reason, \emph{I recommend that you use the
-standard image inclusion mechanism of your format}. Thus, \LaTeX\ users are
-encouraged to use |\includegraphics| to include images.
-
-However, there are reasons why you might need to use the image inclusion
-facilities of \pgfname:
-%
-\begin{itemize}
- \item There is no standard image inclusion mechanism in your format. For
- example, plain \TeX\ does not have one, so \pgfname's inclusion
- mechanism is ``better than nothing''.
-
- However, this applies only to the |pdftex| backend. For all other
- backends, \pgfname\ currently maps its commands back to the |graphicx|
- package. Thus, in plain \TeX, this does not really help. It might be a
- good idea to fix this in the future such that \pgfname\ becomes
- independent of \LaTeX, thereby providing a uniform image abstraction
- for all formats.
- \item You wish to use masking. This is a feature that is only supported by
- \pgfname, though I hope that someone will implement this also for the
- graphics package in \LaTeX\ in the future.
-\end{itemize}
-
-Whatever your choice, you can still use the usual image inclusion facilities of
-the |graphics| package.
-
-The general approach taken by \pgfname\ to including an image is the following:
-First, |\pgfdeclareimage| declares the image. This must be done prior to the
-first use of the image. Once you have declared an image, you can insert it into
-the text using |\pgfuseimage|. The advantage of this two-phase approach is
-that, at least for \textsc{pdf}, the image data will only be included once in
-the file. This can drastically reduce the file size if you use an image
-repeatedly, for example in an overlay. However, there is also a command called
-|\pgfimage| that declares and then immediately uses the image.
-
-To speedup the compilation, you may wish to use the following class option:
-%
-\begin{packageoption}{draft}
- In draft mode boxes showing the image name replace the images. It is
- checked whether the image files exist, but they are not read. If either
- height or width is not given, 1cm is used instead.
-\end{packageoption}
-
-
-\subsection{Declaring an Image}
-
-\begin{command}{\pgfdeclareimage\oarg{options}\marg{image name}\marg{filename}}
- Declares an image, but does not paint anything. To draw the image, use
- |\pgfuseimage{|\meta{image name}|}|. The \meta{filename} may not have an
- extension. For \textsc{pdf}, the extensions |.pdf|, |.jpg|, and |.png|
- will automatically tried. For PostScript, the extensions |.eps|, |.epsi|,
- and |.ps| will be tried.
-
- The following options are possible:
- %
- \begin{itemize}
- \item \declare{|height=|\meta{dimension}} sets the height of the image.
- If the width is not specified simultaneously, the aspect ratio of
- the image is kept.
- \item \declare{|width=|\meta{dimension}} sets the width of the image.
- If the height is not specified simultaneously, the aspect ratio of
- the image is kept.
- \item \declare{|page=|\meta{page number}} selects a given page number
- from a multipage document. Specifying this option will have the
- following effect: first, \pgfname\ tries to find a file named
- %
- \begin{quote}
- \meta{filename}|.page|\meta{page number}|.|\meta{extension}
- \end{quote}
- %
- If such a file is found, it will be used instead of the originally
- specified filename. If not, \pgfname\ inserts the image stored in
- \meta{filename}|.|\meta{extension} and if a recent version of
- |pdflatex| is used, only the selected page is inserted. For older
- versions of |pdflatex| and for |dvips| the complete document is
- inserted and a warning is printed.
- \item \declare{|interpolate=|\meta{true or false}} selects whether the
- image should be ``smoothed'' when zoomed. False by default.
- \item \declare{|mask=|\meta{mask name}} selects a transparency mask.
- The mask must previously be declared using |\pgfdeclaremask| (see
- below). This option only has an effect for |pdf|. Not all viewers
- support masking.
- \end{itemize}
- %
-\begin{codeexample}[code only]
-\pgfdeclareimage[interpolate=true,height=1cm]{image1}{brave-gnu-world-logo}
-\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]{image2}{brave-gnu-world-logo}
-\pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfaliasimage\marg{new image name}\marg{existing image name}}
- The \marg{existing image name} is ``cloned'' and the \marg{new image name}
- can now be used whenever the original image is used. This command is useful
- for creating aliases for alternate extensions and for accessing the last
- image inserted using |\pgfimage|.
-
- \example |\pgfaliasimage{image.!30!white}{image.!25!white}|
-\end{command}
-
-
-\subsection{Using an Image}
-
-\begin{command}{\pgfuseimage\marg{image name}}
- Inserts a previously declared image into the \emph{normal text}. If you
- wish to use it in a |{pgfpicture}| environment, you must put a |\pgftext|
- around it.
-
- If the macro |\pgfalternateextension| expands to some nonempty
- \meta{alternate extension}, \pgfname\ will first try to use the image named
- \meta{image name}|.|\meta{alternate extension}. If this image is not
- defined, \pgfname\ will next check whether \meta{alternate extension}
- contains a |!| character. If so, everything up to this exclamation mark and
- including it is deleted from \meta{alternate extension} and the \pgfname\
- again tries to use the image \meta{image name}|.|\meta{alternate
- extension}. This is repeated until \meta{alternate extension} no longer
- contains a~|!|. Then the original image is used.
-
- The |xxcolor| package sets the alternate extension to the current color
- mixin.
- %
-\begin{codeexample}[]
-\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]
- {image1}{brave-gnu-world-logo}
-\pgfdeclareimage[interpolate=true,width=1cm]{image2}{brave-gnu-world-logo}
-\pgfdeclareimage[interpolate=true,height=1cm]{image3}{brave-gnu-world-logo}
-\begin{pgfpicture}
- \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}}
- \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}}
- \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}}
-
- \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}}
- \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}}
- \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
-
- The following example demonstrates the effect of using |\pgfuseimage|
- inside a colormixin environment.
- %
-\begin{codeexample}[preamble={\usepackage{xxcolor}}]
-\pgfdeclareimage[interpolate=true,width=1cm,height=1cm]
- {image1.!25!white}{brave-gnu-world-logo.25}
-\pgfdeclareimage[interpolate=true,width=1cm]
- {image2.25!white}{brave-gnu-world-logo.25}
-\pgfdeclareimage[interpolate=true,height=1cm]
- {image3.white}{brave-gnu-world-logo.25}
-\begin{colormixin}{25!white}
-\begin{pgfpicture}
- \pgftext[at=\pgfpoint{1cm}{5cm},left,base]{\pgfuseimage{image1}}
- \pgftext[at=\pgfpoint{1cm}{3cm},left,base]{\pgfuseimage{image2}}
- \pgftext[at=\pgfpoint{1cm}{1cm},left,base]{\pgfuseimage{image3}}
-
- \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}}
- \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}}
- \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{colormixin}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfalternateextension}
- You should redefine this command to install a different alternate
- extension.
-
- \example |\def\pgfalternateextension{!25!white}|
-\end{command}
-
-\begin{command}{\pgfimage\oarg{options}\marg{filename}}
- Declares the image under the name |pgflastimage| and immediately uses it.
- You can ``save'' the image for later usage by invoking |\pgfaliasimage| on
- |pgflastimage|.
- %
-\begin{codeexample}[preamble={\usepackage{xxcolor}}]
-\begin{colormixin}{25!white}
-\begin{pgfpicture}
- \pgftext[at=\pgfpoint{1cm}{5cm},left,base]
- {\pgfimage[interpolate=true,width=1cm,height=1cm]{brave-gnu-world-logo}}
- \pgftext[at=\pgfpoint{1cm}{3cm},left,base]
- {\pgfimage[interpolate=true,width=1cm]{brave-gnu-world-logo}}
- \pgftext[at=\pgfpoint{1cm}{1cm},left,base]
- {\pgfimage[interpolate=true,height=1cm]{brave-gnu-world-logo}}
-
- \pgfpathrectangle{\pgfpoint{1cm}{5cm}}{\pgfpoint{1cm}{1cm}}
- \pgfpathrectangle{\pgfpoint{1cm}{3cm}}{\pgfpoint{1cm}{1cm}}
- \pgfpathrectangle{\pgfpoint{1cm}{1cm}}{\pgfpoint{1cm}{1cm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{colormixin}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Masking an Image}
-
-\begin{command}{\pgfdeclaremask\oarg{options}\marg{mask name}\marg{filename}}
- Declares a transparency mask named \meta{mask name} (called a \emph{soft
- mask} in the \textsc{pdf} specification). This mask is read from the file
- \meta{filename}. This file should contain a grayscale image that is as
- large as the actual image. A white pixel in the mask will correspond to
- ``transparent'', a black pixel to ``solid'', and gray values correspond to
- intermediate values. The mask must have a single ``color channel''. This
- means that the mask must be a ``real'' grayscale image, not an
- \textsc{rgb}-image in which all \textsc{rgb}-triples happen to have the
- same components.
-
- You can only mask images that are in a ``pixel format''. For drivers with
- \textsc{pdf} output, these are |.jpg| and |.png| image files; you cannot
- mask |.pdf| images in this way. Pixel images for the |dvips|+|ps2pdf|
- workflow must be provided as |.eps| or |.ps| files. Also, again, the mask
- file and the image file must have the same size.
-
- The following options may be given:
- %
- \begin{itemize}
- \item |matte=|\marg{color components} sets the so-called \emph{matte}
- of the actual image (strangely, this has to be specified together
- with the mask, not with the image itself). The matte is the color
- that has been used to preblend the image. For example, if the image
- has been preblended with a red background, then \meta{color
- components} should be set to |{1 0 0}|. The default is |{1 1 1}|,
- which is white in the rgb model.
-
- The matte is specified in terms of the parent's image color space.
- Thus, if the parent is a grayscale image, the matte has to be set
- to |{1}|.
- \end{itemize}
- %
- \example
- %
-\begin{codeexample}[]
-%% Draw a large colorful background
-\pgfdeclarehorizontalshading{colorful}{5cm}{color(0cm)=(red);
-color(2cm)=(green); color(4cm)=(blue); color(6cm)=(red);
-color(8cm)=(green); color(10cm)=(blue); color(12cm)=(red);
-color(14cm)=(green)}
-\hbox{\pgfuseshading{colorful}\hskip-14cm\hskip1cm
-\pgfimage[height=4cm]{brave-gnu-world-logo}\hskip1cm
-\pgfimage[height=4cm]{brave-gnu-world-logo-mask}\hskip1cm
-\pgfdeclaremask{mymask}{brave-gnu-world-logo-mask}
-\pgfimage[mask=mymask,height=4cm,interpolate=true]{brave-gnu-world-logo}}
-\end{codeexample}
- %
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-internalregisters.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-internalregisters.tex
deleted file mode 100644
index fe28a3c5e8..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-internalregisters.tex
+++ /dev/null
@@ -1,127 +0,0 @@
-% Copyright 2018 by Christian Feuersaenger
-%
-% 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{Adding libraries to \pgfname: temporary registers}
-\label{section-internal-registers}
-
-This section is intended for those who like to write libraries to extend
-\pgfname. Of course, this requires a good deal of knowledge about
-\TeX-programming and the structure of the \pgfname\ basic layer. Besides, one
-will encounter the need of temporary variables and, especially, temporary \TeX\
-registers. This section describes how to use a set of pre-allocated temporary
-registers of the basic layer without needing to allocate more of them.
-
-A part of these internals are already mentioned in
-section~\ref{section-internal-pointcmds}, but the basic layer provides more
-temporaries than |\pgf@x| and |\pgf@y|.
-
-\begin{internallist}[dimen register]{\pgf@x,\pgf@y}
- These registers are used to process point coordinates in the basic layer of
- \pgfname, see section~\ref{section-internal-pointcmds}. After a
- |\pgfpoint|$\dotsc$ command, they contain the final $x$ and $y$ coordinate,
- respectively.
-
- The values of |\pgf@x| and |\pgf@y| are set \emph{globally} in contrast to
- other available \pgfname\ registers. You should never assume anything about
- their value unless the context defines them explicitly.
-
- Please prefer the |\pgf@xa|, |\pgf@xb|, $\dotsc$ registers for temporary
- dimen registers unless you are writing point coordinate commands.
-\end{internallist}
-
-\begin{internallist}[dimen register]{
- \pgf@xa,
- \pgf@xb,
- \pgf@xc,
- \pgf@ya,
- \pgf@yb,
- \pgf@yc%
-}
- Temporary registers for \TeX\ dimensions which can be modified freely. Just
- make sure changes occur only within \TeX\ groups.
-
- \paragraph{Attention:}
- %
- \pgfname\ uses these registers to perform path operations. For reasons of
- efficiency, path commands do not always guard them. As a consequence, the
- code
- %
-\begin{codeexample}[code only]
-\pgfpointadd{\pgfpoint{\pgf@xa}{\pgf@ya}}{\pgfpoint{\pgf@xb}{\pgf@yb}}
-\end{codeexample}
- %
- \noindent may fail: Inside |\pgfpointadd|, the |\pgf@xa| and friend
- registers might be modified. In particular, it might happen that |\pgf@xb|
- is changed before |\pgfpoint{\pgf@xb}{\pgf@yb}| is evaluated. The right
- thing to do would be to first expand everything using |\edef| and process
- the values afterwards, resulting in unnecessary expensive operations. Of
- course, one can avoid this by simply looking into the source code of
- |\pgfpointadd| to see which registers are used.
-\end{internallist}
-
-\begin{internallist}[dimen register]{\pgfutil@tempdima,\pgfutil@tempdimb}
- Further multi-purpose temporary dimen registers. For \LaTeX, these
- registers are already allocated as |\@tempdima| and |\@tempdimb| and are
- simply |\let| to the |\pgfutil@|$\dotsc$ names.
-\end{internallist}
-
-\begin{internallist}[count register]{
- \c@pgf@counta,
- \c@pgf@countb,
- \c@pgf@countc,
- \c@pgf@countd%
-}
- These multiple-purpose count registers are used throughout \pgfname\ to
- perform integer computations. Feel free to use them as well, just make sure
- changes are scoped by local \TeX\ groups.
-\end{internallist}
-
-\begin{internallist}[openout handle]{\w@pgf@writea}
- An |\openout| handle which is used to generate complete output files within
- locally scoped parts of \pgfname\ (for example, to interact with
- |gnuplot|). You should always use |\immediate| in front of output
- operations involving |\w@pgf@writea| and you should always close the file
- before returning from your code.
- %
-\begin{codeexample}[code only]
-\immediate\openout\w@pgf@writea=myfile.dat
-\immediate\write\w@pgf@writea{...}%
-\immediate\write\w@pgf@writea{...}%
-\immediate\closeout\w@pgf@writea%
-\end{codeexample}
- %
-\end{internallist}
-
-\begin{internallist}[openin handle]{\r@pgf@reada}
- An |\openin| handle which is used to read files within locally scoped parts
- of \pgfname, for example to check if a file exists or to read data files.
- You should always use |\immediate| in front of output operations involving
- |\r@pgf@writea| and you should always close the file before returning from
- your code.
- %
-\begin{codeexample}[code only]
-\immediate\openin\r@pgf@reada=myfile.dat
-% do something with \macro
-\ifeof\r@pgf@reada
- % end of file or it doesn't exist
-\else
- % loop or whatever
- \immediate\read\r@pgf@reada to\macro
- ...
-\fi
-\immediate\closein\r@pgf@reada
-\end{codeexample}
- %
-\end{internallist}
-
-\begin{internallist}[box]{\pgfutil@tempboxa}
- A box for temporary use inside of local \TeX\ scopes. For \LaTeX, this box
- is the same as the already pre-allocated |\@tempboxa|.
-\end{internallist}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-layers.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-layers.tex
deleted file mode 100644
index deba15d80b..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-layers.tex
+++ /dev/null
@@ -1,136 +0,0 @@
-% Copyright 2018 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{Layered Graphics}
-\label{section-layers}
-
-\subsection{Overview}
-
-\pgfname\ provides a layering mechanism for composing graphics from multiple
-layers. (This mechanism is not to be confused with the conceptual ``software
-layers'' the \pgfname\ system is composed of.) Layers are often used in graphic
-programs. The idea is that you can draw on the different layers in any order.
-So you might start drawing something on the ``background'' layer, then
-something on the ``foreground'' layer, then something on the ``middle'' layer,
-and then something on the background layer once more, and so on. At the end, no
-matter in which ordering you drew on the different layers, the layers are
-``stacked on top of each other'' in a fixed ordering to produce the final
-picture. Thus, anything drawn on the middle layer would come on top of
-everything of the background layer.
-
-Normally, you do not need to use different layers since you will have little
-trouble ``ordering'' your graphic commands in such a way that layers are
-superfluous. However, in certain situations you only ``know'' what you should
-draw behind something else after the ``something else'' has been drawn.
-
-For example, suppose you wish to draw a yellow background behind your picture.
-The background should be as large as the bounding box of the picture, plus a
-little border. If you know the size of the bounding box of the picture at its
-beginning, this is easy to accomplish. However, in general this is not the case
-and you need to create a ``background'' layer in addition to the standard
-``main'' layer. Then, at the end of the picture, when the bounding box has been
-established, you can add a rectangle of the appropriate size to the picture.
-
-
-\subsection{Declaring Layers}
-
-In \pgfname\ layers are referenced using names. The standard layer, which is a
-bit special in certain ways, is called |main|. If nothing else is specified,
-all graphic commands are added to the |main| layer. You can declare a new layer
-using the following command:
-
-\begin{command}{\pgfdeclarelayer\marg{name}}
- This command declares a layer named \meta{name} for later use. Mainly, this
- will set up some internal bookkeeping.
-\end{command}
-
-The next step toward using a layer is to tell \pgfname\ which layers will be
-part of the actual picture and which will be their ordering. Thus, it is
-possible to have more layers declared than are actually used.
-
-\begin{command}{\pgfsetlayers\marg{layer list}}
- This command tells \pgfname\ which layers will be used in pictures. They
- are stacked on top of each other in the order given. The layer |main|
- should always be part of the list. Here is an example:
- %
-\begin{codeexample}[code only]
-\pgfdeclarelayer{background}
-\pgfdeclarelayer{foreground}
-\pgfsetlayers{background,main,foreground}
-\end{codeexample}
-
- This command should be given either outside of any picture or ``directly
- inside'' of a picture. Here, the ``directly inside'' means that there
- should be no further level of \TeX\ grouping between |\pgfsetlayers| and
- the matching |\end{pgfpicture}| (no closing braces, no |\end{...}|). It
- will also work if |\pgfsetlayers| is provided before |\end{tikzpicture}|
- (with similar restrictions).
-\end{command}
-
-
-\subsection{Using Layers}
-
-Once the layers of your picture have been declared, you can start to ``fill''
-them. As said before, all graphics commands are normally added to the |main|
-layer. Using the |{pgfonlayer}| environment, you can tell \pgfname\ that
-certain commands should, instead, be added to the given layer.
-
-\begin{environment}{{pgfonlayer}\marg{layer name}}
- The whole \meta{environment contents} is added to the layer with the name
- \meta{layer name}. This environment can be used anywhere inside a picture.
- Thus, even if it is used inside a |{pgfscope}| or a \TeX\ group, the
- contents will still be added to the ``whole'' picture. Using this
- environment multiple times inside the same picture will cause the
- \meta{environment contents} to accumulate.
-
- \emph{Note:} You can \emph{not} add anything to the |main| layer using this
- environment. The only way to add anything to the main layer is to give
- graphic commands outside all |{pgfonlayer}| environments.
- %
-\begin{codeexample}[]
-\pgfdeclarelayer{background layer}
-\pgfdeclarelayer{foreground layer}
-\pgfsetlayers{background layer,main,foreground layer}
-\begin{tikzpicture}
- % On main layer:
- \fill[blue] (0,0) circle (1cm);
-
- \begin{pgfonlayer}{background layer}
- \fill[yellow] (-1,-1) rectangle (1,1);
- \end{pgfonlayer}
-
- \begin{pgfonlayer}{foreground layer}
- \node[white] {foreground};
- \end{pgfonlayer}
-
- \begin{pgfonlayer}{background layer}
- \fill[black] (-.8,-.8) rectangle (.8,.8);
- \end{pgfonlayer}
-
- % On main layer again:
- \fill[blue!50] (-.5,-1) rectangle (.5,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{environment}
-
-\begin{plainenvironment}{{pgfonlayer}\marg{layer name}}
- This is the plain \TeX\ version of the environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{pgfonlayer}\marg{layer name}}
- This is the Con\TeX t version of the environment.
-\end{contextenvironment}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-matrices.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-matrices.tex
deleted file mode 100644
index c35a345753..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-matrices.tex
+++ /dev/null
@@ -1,437 +0,0 @@
-% 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{Matrices}
-\label{section-base-matrices}
-
-\begin{pgfmodule}{matrix}
-The present section documents the commands of this module.
-\end{pgfmodule}
-
-\subsection{Overview}
-
-Matrices are a mechanism for aligning several so-called cell pictures
-horizontally and vertically. The resulting alignment is placed in a normal node
-and the command for creating matrices, |\pgfmatrix|, takes options very similar
-to the |\pgfnode| command.
-
-In the following, the basic idea behind the alignment mechanism is explained
-first. Then the command |\pgfmatrix| is explained. At the end of the section,
-additional ways of modifying the width of columns and rows are discussed.
-
-
-\subsection{Cell Pictures and Their Alignment}
-
-A matrix consists of rows of \emph{cells}. Cells are separated using the
-special command |\pgfmatrixnextcell|, rows are ended using the command
-|\pgfmatrixendrow| (the command |\\| is set up to mean the same as
-|\pgfmatrixendrow| by default). Each cell contains a \emph{cell picture},
-although cell pictures are not complete pictures as they lack layers. However,
-each cell picture has its own bounding box like a normal picture does. These
-bounding boxes are important for the alignment as explained in the following.
-
-Each cell picture will have an origin somewhere in the picture (or even outside
-the picture). The position of these origins are important for the alignment: On
-each row the origins will be on the same horizontal line and for each column
-the origins will also be on the same vertical line. These two requirements mean
-that the cell pictures may need to be shifted around so that the origins wind
-up on the same lines. The top of a row is given by the top of the cell picture
-whose bounding box's maximum $y$-position is largest. Similarly, the bottom of
-a row is given by the bottom of the cell picture whose bounding box's minimum
-$y$-position is the most negative. Similarly, the left end of a column is given
-by the left end of the cell whose bounding box's $x$-position is the most
-negative; and similarly for the right end of a column.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[x=3mm,y=3mm,fill=blue!50]
- \def\atorig#1{\node[black] at (0,0) {\tiny #1};}
-
- \pgfmatrix{rectangle}{center}{mymatrix}
- {\pgfusepath{}}{\pgfpointorigin}{}
- {
- \fill (0,-3) rectangle (1,1);\atorig1 \pgfmatrixnextcell
- \fill (-1,0) rectangle (1,1);\atorig2 \pgfmatrixnextcell
- \fill (-1,-2) rectangle (0,0);\atorig3 \pgfmatrixnextcell
- \fill (-1,-1) rectangle (0,3);\atorig4 \\
- \fill (-1,0) rectangle (4,1);\atorig5 \pgfmatrixnextcell
- \fill (0,-1) rectangle (1,1);\atorig6 \pgfmatrixnextcell
- \fill (0,0) rectangle (1,4);\atorig7 \pgfmatrixnextcell
- \fill (-1,-1) rectangle (0,0);\atorig8 \\
- }
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{The Matrix Command}
-
-All matrices are typeset using the following command:
-
-\begin{command}{\pgfmatrix\marg{shape}\marg{anchor}\marg{name}\marg{usage}\marg{shift}\marg{pre-code}\marg{matrix cells}}
- This command creates a node that contains a matrix. The name of the node is
- \meta{name}, its shape is \meta{shape} and the node is anchored at
- \meta{anchor}.
-
- The \meta{matrix cell} parameter contains the cells of the matrix. In each
- cell drawing commands may be given, which create a so-called cell picture.
- For each cell picture a bounding box is computed and the cells are aligned
- according to the rules outlined in the previous section.
-
- The resulting matrix is used as the |text| box of the node. As for a normal
- node, the \meta{usage} commands are applied, so that the path(s) of the
- resulting node is (are) stroked or filled or whatever.
-
-
- \medskip
- \textbf{Specifying the cells and rows.\ }
- Even though this command uses |\halign| internally, there are two special
- rules for indicating cells:
- %
- \begin{enumerate}
- \item Cells in the same row must be separated using the macro
- |\pgfmatrixnextcell| rather than |&|. Using |&| will result in an
- error message.
-
- However, you can make |&| an active character and have it expand to
- |\pgfmatrixnextcell|. This way, it will ``look'' as if |&| is used.
- \item Rows are ended using the command |\pgfmatrixendrow|, but |\\| is
- set up to mean the same by default. However, some environments like
- |{minipage}| redefine |\\|, so it is good to have
- |\pgfmatrixendrow| as a ``fallback''.
- \item Every row \emph{including the last row} must be ended using the
- command |\\| or |\pgfmatrixendrow|.
- \end{enumerate}
-
- Both |\pgfmatrixnextcell| and |\pgfmatrixendrow| (and, thus, also |\\|)
- take an optional argument as explained in the
- Section~\ref{section-matrix-spacing}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \pgfmatrix{rectangle}{center}{mymatrix}
- {\pgfusepath{}}{\pgfpointorigin}{}
- {
- \node {a}; \pgfmatrixnextcell \node {b}; \pgfmatrixendrow
- \node {c}; \pgfmatrixnextcell \node {d}; \pgfmatrixendrow
- }
-\end{tikzpicture}
-\end{codeexample}
-
-
- \medskip
- \textbf{Anchoring matrices at nodes inside the matrix.\ }
- The parameter \meta{shift} is an additional negative shift for the node.
- Normally, such a shift could be given beforehand (that is, the shift could
- be preapplied to the current transformation matrix). However, when
- \meta{shift} is evaluated, you can refer to \emph{temporary} positions of
- nodes inside the matrix. In detail, the following happens: When the matrix
- has been typeset, all nodes in the matrix temporarily get assigned their
- positions in the matrix box. The origin of this coordinate system is at the
- left baseline end of the matrix box, which corresponds to the |text|
- anchor. The position \meta{shift} is then interpreted inside this
- coordinate system and then used for shifting.
-
- This allows you to use the parameter \meta{shift} in the following way: If
- you use |text| as the \meta{anchor} and specify
- |\pgfpointanchor{inner node}{some anchor}| for the parameter \meta{shift},
- where |inner node| is a node that is created in the matrix, then the whole
- matrix will be shifted such that |inner node.some anchor| lies at the
- origin of the whole picture.
-
-
- \medskip
- \textbf{Rotations and scaling.\ }
- The matrix node is never rotated or scaled, because the current coordinate
- transformation matrix is reset (except for the translational part) at the
- beginning of |\pgfmatrix|. This is intentional and will not change in the
- future. If you need to rotate or scale the matrix, you must install an
- appropriate canvas transformation yourself.
-
- However, nodes and stuff inside the cell pictures can be rotated and scaled
- normally.
-
-
- \medskip
- \textbf{Callbacks.\ }
- At the beginning and at the end of each cell the special macros
- |\pgfmatrixbegincode|, |\pgfmatrixendcode| and possibly
- |\pgfmatrixemptycode| are called. The effect is explained in
- Section~\ref{section-matrix-callbacks}.
-
-
- \medskip
- \textbf{Executing extra code.\ }
- The parameter \meta{pre-code} is executed at the beginning of the outermost
- \TeX-group enclosing the matrix node. It is inside this \TeX-group, but
- outside the matrix itself. It can be used for different purposes:
- %
- \begin{enumerate}
- \item It can be used to simplify the next cell macro. For example,
- saying |\let\&=\pgfmatrixnextcell| allows you to use |\&| instead
- of |\pgfmatrixnextcell|. You can also set the catcode of |&| to
- active.
- \item It can be used to issue an |\aftergroup| command. This allows you
- to regain control after the |\pgfmatrix| command. (If you do not
- know the |\aftergroup| command, you are probably blessed with a
- simple and happy life.)
- \end{enumerate}
-
-
- \medskip
- \textbf{Special considerations concerning macro expansion.\ }
- As said before, the matrix is typeset using |\halign| internally. This
- command does a lot of strange and magic things like expanding the first
- macro of every cell in a most unusual manner. Here are some effects you may
- wish to be aware of:
- %
- \begin{itemize}
- \item It is not necessary to actually mention |\pgfmatrixnextcell| or
- |\pgfmatrixendrow| inside the \meta{matrix cells}. It suffices that
- the macros inside \meta{matrix cells} expand to these macros
- sooner or later.
- \item In particular, you can define clever macros that insert columns
- and rows as needed for special effects.
- \end{itemize}
-\end{command}
-
-
-\subsection{Row and Column Spacing}
-\label{section-matrix-spacing}
-
-It is possible to control the space between columns and rows rather detailedly.
-Two commands are important for the row spacing and two commands for the column
-spacing.
-
-\begin{command}{\pgfsetmatrixcolumnsep\marg{sep list}}
- This macro sets the default separation list for columns. The details of the
- format of this list are explained in the description of the next command.
-\end{command}
-
-\begin{command}{\pgfmatrixnextcell\opt{\oarg{additional sep list}}}
- This command has two purposes: First, it is used to separate cells. Second,
- by providing the optional argument \meta{additional sep list} you can
- modify the spacing between the columns that are separated by this command.
-
- The optional \meta{additional sep list} may only be provided when the
- |\pgfmatrixnextcell| command starts a new column. Normally, this will only
- be the case in the first row, but sometimes a later row has more elements
- than the first row. In this case, the |\pgfmatrixnextcell| commands that
- start the new columns in the later row may also have the optional argument.
- Once a column has been started, subsequent uses of this optional argument
- for the column have no effect.
-
- To determine the space between the two columns that are separated by
- |\pgfmatrixnextcell|, the following algorithm is executed:
- %
- \begin{enumerate}
- \item Both the default separation list (as set up by
- |\pgfsetmatrixcolumnsep|) and the \meta{additional sep list} are
- processed, in this order. If the \meta{additional sep list}
- argument is missing, only the default separation list is processed.
- \item Both lists may contain dimensions, separated by commas, as well
- as occurrences of the keywords |between origins| and
- |between borders|.
- \item All dimensions occurring in either list are added together to
- arrive at a dimension $d$.
- \item The last occurrence of either of the keywords is located. If
- neither keyword is present, we proceed as if |between borders| were
- present.
- \end{enumerate}
- %
- At the end of the algorithm, a dimension $d$ has been computed and one of
- the two \emph{modes} |between borders| and |between origins| has been
- determined. Depending on which mode has been determined, the following
- happens:
- %
- \begin{itemize}
- \item For the |between borders| mode, an additional horizontal space of
- $d$ is added between the two columns. Note that $d$ may be
- negative.
- \item For the |between origins| mode, the spacing between the two
- columns is computed differently: Recall that the origins of the
- cell pictures in both pictures lie on two vertical lines. The
- spacing between the two columns is set up such that the horizontal
- distance between these two lines is exactly $d$.
-
- This mode may only be used between columns \emph{already introduced
- in the first row}.
- \end{itemize}
- %
- All of the above rules boil down to the following effects:
- %
- \begin{itemize}
- \item A default spacing between columns should be set up using
- |\pgfsetmatrixcolumnsep|. For example, you might say
- |\pgfsetmatrixcolumnsep{5pt}| to have columns spaced apart by
- |5pt|. You could say
- %
-\begin{verbatim}
-\pgfsetmatrixcolumnsep{1cm,between origins}
-\end{verbatim}
- %
- to specify that horizontal space between the origins of cell
- pictures in adjacent columns should be 1cm by default -- regardless
- of the actual size of the cell pictures.
- \item You can now use the optional argument of |\pgfmatrixnextcell| to
- locally overrule the spacing between two columns. By saying
- |\pgfmatrixnextcell[5pt]| you \emph{add} 5pt to the space between
- of the two columns, regardless of the mode.
-
- You can also (locally) change the spacing mode for these two
- columns. For example, even if the normal spacing mode is
- |between origins|, you can say
- %
-\begin{verbatim}
-\pgfmatrixnextcell[5pt,between borders]
-\end{verbatim}
- %
- to locally change the mode for these columns to |between borders|.
- \end{itemize}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[every node/.style=draw]
- \pgfsetmatrixcolumnsep{1mm}
- \pgfmatrix{rectangle}{center}{mymatrix}
- {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
- {
- \node {8}; \&[2mm] \node{1}; \&[-1mm] \node {6}; \\
- \node {3}; \& \node{5}; \& \node {7}; \\
- \node {4}; \& \node{9}; \& \node {2}; \\
- }
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[every node/.style=draw]
- \pgfsetmatrixcolumnsep{1mm}
- \pgfmatrix{rectangle}{center}{mymatrix}
- {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
- {
- \node {8}; \&[2mm] \node(a){1}; \&[1cm,between origins] \node(b){6}; \\
- \node {3}; \& \node {5}; \& \node {7}; \\
- \node {4}; \& \node {9}; \& \node {2}; \\
- }
- \draw [<->,red,thick,every node/.style=] (a.center) -- (b.center)
- node [above,midway] {11mm};
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[every node/.style=draw]
- \pgfsetmatrixcolumnsep{1cm,between origins}
- \pgfmatrix{rectangle}{center}{mymatrix}
- {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
- {
- \node (a) {8}; \& \node (b) {1}; \&[between borders] \node (c) {6}; \\
- \node {3}; \& \node {5}; \& \node {7}; \\
- \node {4}; \& \node {9}; \& \node {2}; \\
- }
- \begin{scope}[every node/.style=]
- \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {10mm};
- \draw [<->,red,thick] (b.east) -- (c.west) node [above,midway]
- {10mm};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-The mechanism for the between-row-spacing is the same, only the commands are
-called differently.
-
-\begin{command}{\pgfsetmatrixrowsep\marg{sep list}}
- This macro sets the default separation list for rows.
-\end{command}
-
-\begin{command}{\pgfmatrixendrow\opt{\oarg{additional sep list}}}
- This command ends a line. The optional \meta{additional sep list} is used
- to determine the spacing between the row being ended and the next row. The
- modes and the computation of $d$ is done in the same way as for columns.
- For the last row the optional argument has no effect.
-
- Inside matrices (and only there) the command |\\| is set up to mean the
- same as this command.
-\end{command}
-
-
-\subsection{Callbacks}
-\label{section-matrix-callbacks}
-
-There are three macros that get called at the beginning and end of cells. By
-redefining these macros, which are empty by default, you can change the
-appearance of cells in a very general manner.
-
-\begin{command}{\pgfmatrixemptycode}
- This macro is executed for empty cells. This means that \pgfname\ uses some
- macro magic to determine whether a cell is empty (it immediately ends with
- |\pgfmatrixemptycode| or |\pgfmatrixendrow|) and, if so, put this macro
- inside the cell.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \def\pgfmatrixemptycode{\node{empty};}
- \pgfmatrix{rectangle}{center}{mymatrix}
- {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
- {
- \node {a}; \& \& \node {b}; \\
- \& \node{c}; \& \node {d}; \& \\
- }
-\end{tikzpicture}
-\end{codeexample}
- %
- As can be seen, the macro is not executed for empty cells at the end of row
- when columns are added only later on.
-\end{command}
-
-\begin{command}{\pgfmatrixbegincode}
- This macro is executed at the beginning of non-empty cells.
- Correspondingly, |\pgfmatrixendcode| is added at the end of every non-empty
- cell.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \def\pgfmatrixbegincode{\node[draw]\bgroup}
- \def\pgfmatrixendcode{\egroup;}
- \pgfmatrix{rectangle}{center}{mymatrix}
- {\pgfusepath{}}{\pgfpointorigin}{\let\&=\pgfmatrixnextcell}
- {
- a \& b \& c \\
- d \& \& e \\
- }
-\end{tikzpicture}
-\end{codeexample}
- %
- Note that between |\pgfmatrixbegincode| and |\pgfmatrixendcode| there will
- \emph{not} only be the contents of the cell. Rather, \pgfname\ will add
- some (invisible) commands for book-keeping purposes that involve |\let| and
- |\gdef|. In particular, it is not a good idea to have |\pgfmatrixbegincode|
- end with |\csname| and |\pgfmatrixendcode| start with |\endcsname|.
-\end{command}
-
-\begin{command}{\pgfmatrixendcode}
- See the explanation above.
-\end{command}
-
-The following two counters allow you to access the current row and current
-column in a callback:
-
-\begin{command}{\pgfmatrixcurrentrow}
- This counter stores the current row of the current cell of the matrix. Do
- not even think about changing this counter.
-\end{command}
-
-\begin{command}{\pgfmatrixcurrentcolumn}
- This counter stores the current column of the current cell of the matrix.
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-nodes.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-nodes.tex
deleted file mode 100644
index 19499ec551..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-nodes.tex
+++ /dev/null
@@ -1,1305 +0,0 @@
-% Copyright 2019 by Till Tantau
-%
-% This file may be distributed and/or modified
-%
-% 1. under the LaTeX Project Public License and/or
-% 2. under the GNU Free Documentation License.
-%
-% See the file doc/generic/pgf/licenses/LICENSE for more details.
-
-
-\section{Nodes and Shapes}
-
-\label{section-shapes}
-
-This section describes the |shapes| module.
-
-\begin{pgfmodule}{shapes}
- This module defines commands both for creating nodes and for creating
- shapes. The package is loaded automatically by |pgf|, but you can load it
- manually if you have only included |pgfcore|.
-\end{pgfmodule}
-
-
-\subsection{Overview}
-
-\pgfname\ comes with a sophisticated set of commands for creating \emph{nodes}
-and \emph{shapes}. A \emph{node} is a graphical object that consists
-(typically) of (one or more) text labels and some additional stroked or filled
-paths. Each node has a certain \emph{shape}, which may be something simple like
-a |rectangle| or a |circle|, but it may also be something complicated like a
-|uml class diagram| (this shape is currently not implemented, though).
-Different nodes that have the same shape may look quite different, however,
-since shapes (need not) specify whether the shape path is stroked or filled.
-
-
-\subsubsection{Creating and Referencing Nodes}
-
-You create a node by calling the macro |\pgfnode| or the more general
-|\pgfmultipartnode|. This macro takes several parameters and draws the
-requested shape at a certain position. In addition, it will ``remember'' the
-node's position within the current |{pgfpicture}|. You can then, later on,
-refer to the node's position. Coordinate transformations are ``fully
-supported'', which means that if you used coordinate transformations to shift
-or rotate the shape of a node, the node's position will still be correctly
-determined by \pgfname. This is \emph{not} the case if you use canvas
-transformations instead.
-
-
-\subsubsection{Anchors}
-
-An important property of a node or a shape in general are its \emph{anchors}.
-Anchors are ``important'' positions in a shape. For example, the |center|
-anchor lies at the center of a shape, the |north| anchor is usually ``at the
-top, in the middle'' of a shape, the |text| anchor is the lower left corner of
-the shape's text label (if present), and so on.
-
-Anchors are important both when you create a node and when you reference it.
-When you create a node, you specify the node's ``position'' by asking \pgfname\
-to place the shape in such a way that a certain anchor lies at a certain point.
-For example, you might ask that the node is placed such that the |north| anchor
-is at the origin. This will effectively cause the node to be placed below the
-origin.
-
-When you reference a node, you always reference an anchor of the node. For
-example, when you request the ``|north| anchor of the node just placed'' you
-will get the origin. However, you can also request the ``|south| anchor of this
-node'', which will give you a point somewhere below the origin. When a
-coordinate transformation was in force at the time of creation of a node, all
-anchors are also transformed accordingly.
-
-
-\subsubsection{Layers of a Shape}
-
-The simplest shape, the |coordinate|, has just one anchor, namely the |center|,
-and a label (which is usually empty). More complicated shapes like the
-|rectangle| shape also have a \emph{background path}. This is a \pgfname-path
-that is defined by the shape. The shape does not prescribe what should happen
-with the path: When a node is created, this path may be stroked (resulting in a
-frame around the label), filled (resulting in a background color for the text),
-or just discarded.
-
-Although most shapes consist just of a background path plus some label text,
-when a shape is drawn, up to seven different layers are drawn:
-%
-\begin{enumerate}
- \item The ``behind the background layer''. Unlike the background path,
- which can be used in different ways by different nodes, the graphic
- commands given for this layer will always stroke or always fill the
- path they construct. They might also insert some text that is ``behind
- everything''.
- \item The background path layer. How this path is used depends on the
- arguments of the |\pgfnode| command.
- \item The ``before the background path layer''. This layer works like the
- first one, only the commands of this layer are executed after the
- background path has been used (in whatever way the creator of the node
- chose).
- \item The label layer. This layer inserts the node's text box(es).
- \item The ``behind the foreground layer''. This layer, like the first
- layer, once more contains graphic commands that are ``simply
- executed''.
- \item The foreground path layer. This path is treated in the same way as
- the background path, only it is drawn after the label text has been
- drawn.
- \item The ``before the foreground layer''.
-\end{enumerate}
-
-Which of these layers are actually used depends on the shape.
-
-
-\subsubsection{Node Parts}
-
-A shape typically does not consist only of different background and foreground
-paths, but it may also have text labels. Indeed, for many shapes the text
-labels are the more important part of the shape.
-
-Most shapes will have only one text label. In this case, this text label is
-simply passed as a parameter to the |\pgfnode| command. When the node is drawn,
-the text label is shifted around such that its lower left corner is at the
-|text| anchor of the node.
-
-More complicated shapes may have more than one text label. Nodes of such shapes
-are called \emph{multipart nodes}. The different \emph{node parts} are simply
-the different text labels. For example, a |uml class| shape might have a
-|class name| part, a |method| part and an |attributes| part. Indeed, single
-part nodes are a special case of multipart nodes: They only have one part named
-|text|.
-
-When a shape is declared, you must specify the node parts. There is a simple
-command called |\nodeparts| that takes a list of the part names as input. When
-you create a node of a multipart shape, for each part of the node you must have
-set up a \TeX-box containing the text of the part. For a part named |XYZ| you
-must set up the box |\pgfnodepartXYZbox|. The box will be placed at the anchor
-|XYZ|. See the description of |\pgfmultipartnode| for more details.
-
-
-\subsection{Creating Nodes}
-
-\subsubsection{Creating Simple Nodes}
-
-\begin{command}{\pgfnode\marg{shape}\marg{anchor}\marg{label text}\marg{name}\marg{path usage command}}
- This command creates a new node. The \meta{shape} of the node must have
- been declared previously using |\pgfdeclareshape|.
-
- The shape is shifted such that the \meta{anchor} is at the origin. In order
- to place the shape somewhere else, use the coordinate transformation prior
- to calling this command.
-
- The \meta{name} is a name for later reference. If no name is given, nothing
- will be ``saved'' for the node, it will just be drawn.
-
- The \meta{path usage command} is executed for the background and the
- foreground path (if the shape defines them).
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (4,3);
- {
- \pgftransformshift{\pgfpoint{1.5cm}{1cm}}
- \pgfnode{rectangle}{north}{Hello World}{hellonode}{\pgfusepath{stroke}}
- }
- {
- \color{red!20}
- \pgftransformrotate{10}
- \pgftransformshift{\pgfpoint{3cm}{1cm}}
- \pgfnode{rectangle}{center}
- {\color{black}Hello World}{hellonode}{\pgfusepath{fill}}
- }
-\end{tikzpicture}
-\end{codeexample}
-
- As can be seen, all coordinate transformations are also applied to the text
- of the shape. Sometimes, it is desirable that the transformations are
- applied to the point where the shape will be anchored, but you do not wish
- the shape itself to be transformed. In this case, you should call
- |\pgftransformresetnontranslations| prior to calling the |\pgfnode|
- command.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (4,3);
- {
- \color{red!20}
- \pgftransformrotate{10}
- \pgftransformshift{\pgfpoint{3cm}{1cm}}
- \pgftransformresetnontranslations
- \pgfnode{rectangle}{center}
- {\color{black}Hello World}{hellonode}{\pgfusepath{fill}}
- }
-\end{tikzpicture}
-\end{codeexample}
-
- The \meta{label text} is typeset inside the \TeX-box |\pgfnodeparttextbox|.
- This box is shown at the |text| anchor of the node, if the node has a
- |text| part. See the description of |\pgfmultipartnode| for details.
-\end{command}
-
-
-\subsubsection{Creating Multi-Part Nodes}
-
-\begin{command}{\pgfmultipartnode\marg{shape}\marg{anchor}\marg{name}\marg{path usage command}}
- This command is the more general (and less user-friendly) version of the
- |\pgfnode| command. While the |\pgfnode| command can only be used for
- shapes that have a single part (which is the case for most shapes), this
- command can also be used with multi-part nodes.
-
- When this command is called, for each node part of the node you must have
- set up one \TeX-box. Suppose the shape has two parts: The |text| part and
- the |lower| part. Then, prior to calling |\pgfmultipartnode|, you must have
- set up the boxes |\pgfnodeparttextbox| and |\pgfnodepartlowerbox|. These
- boxes may contain any \TeX-text. The shape code will then compute the
- positions of the shape's anchors based on the sizes of the these shapes.
- Finally, when the node is drawn, the boxes are placed at the anchor
- positions |text| and |lower|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes}}]
-\setbox\pgfnodeparttextbox=\hbox{$q_1$}
-\setbox\pgfnodepartlowerbox=\hbox{01}
-\begin{pgfpicture}
- \pgfmultipartnode{circle split}{center}{my state}{\pgfusepath{stroke}}
-\end{pgfpicture}
-\end{codeexample}
-
- \emph{Note:} Be careful when using the |\setbox| command inside a
- |{pgfpicture}| command. You will have to use |\pgfinterruptpath| at the
- beginning of the box and |\endpgfinterruptpath| at the end of the box to
- make sure that the box is typeset correctly. In the above example this
- problem was sidestepped by moving the box construction outside the
- environment.
-
- \emph{Note:} It is not necessary to use |\newbox| for every node part
- name. Although you need a different box for each part of a single shape,
- two different shapes may very well use the same box even when the names of
- the parts are different. Suppose you have a |circle split| shape that has a
- |lower| part and you have a |uml class| shape that has a |methods| part.
- Then, in order to avoid exhausting \TeX's limited number of box registers,
- you can say
- %
-\begin{codeexample}[code only]
-\newbox\pgfnodepartlowerbox
-\let\pgfnodepartmethodsbox=\pgfnodepartlowerbox
-\end{codeexample}
- %
- Also, when you have a node part name with spaces like |class name|, it may
- be useful to create an alias:
- %
-\begin{codeexample}[code only]
-\newbox\mybox
-\expandafter\let\csname pgfnodepartclass namebox\endcsname=\mybox
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfcoordinate\marg{name}\marg{coordinate}}
- This command creates a node of shape |coordinate| at the given
- \meta{coordinate}. Exactly the same effect can be achieved using first a
- shift of the coordinate system to \meta{coordinate}, followed by creating a
- node of shape |coordinate| named \meta{name}. However, this command is
- easier and more natural to use and, more importantly, it is much faster.
-\end{command}
-
-\begin{command}{\pgfnodealias\marg{new name}\marg{existing node}}
- This command does not actually create a new node. Rather, it allows you to
- subsequently access the node \meta{existing node} using the name \meta{new
- name}.
-\end{command}
-
-\begin{command}{\pgfnoderename\marg{new name}\marg{existing node}}
- This command renames an existing node.
-\end{command}
-
-There are a number of values that have an influence on the size of a node.
-These values are stored in the following keys.
-
-\begin{key}{/pgf/minimum width=\meta{dimension} (initially 1pt)}
-\keyalias{tikz}
- This key stores the \emph{recommended} minimum width of a shape. Thus, when
- a shape is drawn and when the shape's width would be smaller than
- \meta{dimension}, the shape's width is enlarged by adding some empty space.
-
- Note that this value is just a recommendation. A shape may choose to ignore
- this key.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (-2,0) grid (2,1);
-
- \pgfset{minimum width=3cm}
- \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/minimum height=\meta{dimension} (initially 1pt)}
-\keyalias{tikz}
- Works like |/pgf/minimum width|.
-\end{key}
-
-\begin{key}{/pgf/minimum size=\meta{dimension}}
-\keyalias{tikz}
- This style both |/pgf/minimum width| and |/pgf/minimum height| to \meta{dimension}.
-\end{key}
-
-\begin{key}{/pgf/inner xsep=\meta{dimension} (initially 0.3333em)}
-\keyalias{tikz}
- This key stores the \emph{recommended} horizontal inner separation between
- the label text and the background path. As before, this value is just a
- recommendation and a shape may choose to ignore this key.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (-2,0) grid (2,1);
-
- \pgfset{inner xsep=1cm}
- \pgfnode{rectangle}{center}{Hello World}{}{\pgfusepath{stroke}}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/inner ysep=\meta{dimension} (initially 0.3333em)}
-\keyalias{tikz}
- Works like |/pgf/inner xsep|.
-\end{key}
-
-\begin{key}{/pgf/inner sep=\meta{dimension}}
-\keyalias{tikz}
- This style sets both |/pgf/inner xsep| and |/pgf/inner ysep| to
- \meta{dimension}.
-\end{key}
-
-\begin{key}{/pgf/outer xsep=\meta{dimension} (initially .5\string\pgflinewidth)}
-\keyalias{tikz}
- This key stores the recommended horizontal separation between the
- background path and the ``outer anchors''. For example, if \meta{dimension}
- is |1cm| then the |east| anchor will be 1cm to the right of the right
- border of the background path. As before, this value is just a
- recommendation.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (-2,0) grid (2,1);
-
- \pgfset{outer xsep=.5cm}
- \pgfnode{rectangle}{center}{Hello World}{x}{\pgfusepath{stroke}}
-
- \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt}
- \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt}
- \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt}
- \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt}
- \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt}
- \pgfusepath{fill}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/outer ysep=\meta{dimension} (initially .5\string\pgflinewidth)}
-\keyalias{tikz}
- Works like |/pgf/outer xsep|.
-\end{key}
-
-\begin{key}{/pgf/outer sep=\meta{dimension}}
-\keyalias{tikz}
- This style sets both |/pgf/outer xsep| and |/pgf/outer ysep| to
- \meta{dimension}.
-\end{key}
-
-
-\subsubsection{Deferred Node Positioning}
-\label{section-shapes-deferred-node-positioning}
-
-Normally, when a node is created using a command like |\pgfnode|, the node is
-immediately inserted into the current picture. In particular, you have no
-chance to change the position of a created node after it has been created.
-Using |\pgfpositionnodelater| in concert with |\pgfpositionnodenow|, you can
-create a node whose position is determined only at some later time.
-
-\begin{command}{\pgfpositionnodelater\marg{macro name}}
- This command is not a replacement for |\pgfnode|. Rather, when this command
- is used in a scope, all subsequent node creations in this scope will be
- affected in the following way: When a node is created, it is not inserted
- into the current picture. Instead, it is stored in the box
- |\pgfpositionnodelaterbox|. Furthermore, the node is not relevant for the
- picture's bounding box, but a bounding box for the node is computed and
- stored in the macros |\pgfpositionnodelaterminx| to
- |\pgfpositionnodelatermaxy|. Then, the \meta{macro name} is called with the
- following macros set up:
-
- \begin{command}{\pgfpositionnodelaterbox}
- A box register number (|0| currently) that stores the node's paths and
- texts. You should move the contents of this box to a box of your choice
- inside \meta{macro name}.
- \end{command}
-
- \begin{command}{\pgfpositionnodelatername}
- The name of the just-created-node. This name will be the originally
- ``desired'' name of the box plus the fixed prefix
- |not yet positionedPGFINTERNAL|. The idea is to ensure that the
- original name is not inadvertently used before the node is actually
- positioned. When |\pgfpositionnodenow| is called, it will change the
- name to the
- original name.
- \end{command}
-
- \begin{command}{\pgfpositionnodelaterminx}
- The minimal $x$-position of a bounding box of the node. This bounding
- box refers to the node when it is positioned with the anchor at the
- origin. It is guaranteed, that this macro will contain a dimension in
- the format \meta{number}|pt|.
- \end{command}
- %
- \begin{command}{\pgfpositionnodelaterminy}
- \end{command}
- %
- \begin{command}{\pgfpositionnodelatermaxx}
- \end{command}
- %
- \begin{command}{\pgfpositionnodelatermaxy}
- \end{command}
-
- Once a late node has been created, you can add arbitrary code in the same
- picture. Then, at some later point, you call |\pgfpositionnodenow| to
- finally position the node at a given position. At this point, the above
- macros must have the exact same values they had when \meta{macro name} was
- called. Note that the above macros are local to a scope that ends right
- after the call to \meta{macro name}, so it is your job to copy the values
- to safety inside \meta{macro name}.
-
- The following two macros will also be set inside the call to \meta{macro
- name}, but they are only ``informative'' in the sense that you need
- \emph{not} restore these macros when |\pgfpositionnodenow| is called.
-
- \begin{command}{\pgfpositionnodelaterpath}
- This macro stores the path of the background of the node. See
- Section~\ref{section-soft-paths} for an overview of how these paths are
- encode.
- \end{command}
-
- By setting \meta{macro name} to |\relax| (which is the default), you can
- switch off the whole mechanism. When a picture is interrupted, this is done
- automatically.
-\end{command}
-
-\begin{command}{\pgfpositionnodenow\marg{coordinate}}
- This command is used to position a node that has previously been created
- using the command |\pgfpositionnodelater|. When |\pgfpositionnodenow| is
- called, the macros and boxes mentioned in the description of
- |\pgfpositionnodenow| must be set to the value they had when the
- \meta{macro name} was called. Provided this is the case, this command will
- insert the box into the current picture, shifted by \meta{coordinate}.
- Then, the late code (see below) is called. Subsequently, you can refer to
- the node with its original name as if it had just been created.
- %
-\begin{codeexample}[]
-\newbox\mybox
-
-\def\mysaver{
- \global\setbox\mybox=\box\pgfpositionnodelaterbox
- \global\let\myname=\pgfpositionnodelatername
- \global\let\myminx=\pgfpositionnodelaterminx
- \global\let\myminy=\pgfpositionnodelaterminy
- \global\let\mymaxx=\pgfpositionnodelatermaxx
- \global\let\mymaxy=\pgfpositionnodelatermaxy
-}
-
-\begin{tikzpicture}
- {
- \pgfpositionnodelater{\mysaver}
- \node [fill=blue!20,below,rotate=30] (hi) {Hello world};
- }
- \draw [help lines] (0,0) grid (3,2);
-
- \let\pgfpositionnodelatername=\myname
- \let\pgfpositionnodelaterminx=\myminx
- \let\pgfpositionnodelaterminy=\myminy
- \let\pgfpositionnodelatermaxx=\mymaxx
- \let\pgfpositionnodelatermaxy=\mymaxy
- \setbox\pgfpositionnodelaterbox=\box\mybox
- \pgfpositionnodenow{\pgfqpoint{2cm}{2cm}}
-
- \draw (hi) -- (0,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfnodepostsetupcode\marg{node name}\marg{code}}
- When you call this macro inside a scope for which the
- |\pgfpositionnodelater| has been called, the \meta{code} will be stored
- internally. Later, when the node named \meta{node name} is actually
- positioned using |\pgfpositionnodenow|, the \meta{code} will be executed.
- When this macro is called multiple times with the same \meta{node name},
- the \meta{code} accumulates. However, When |\pgfpositionnodenow| is called,
- the code stored for the node is cleared.
-
- The main purpose of this mechanism is to allow \tikzname\ to store
- so-called ``late options'' with a node that will be positioned only later.
-\end{command}
-
-
-\subsection{Using Anchors}
-
-Each shape defines a set of anchors. We saw already that the anchors are used
-when the shape is drawn: the shape is placed in such a way that the given
-anchor is at the origin (which in turn is typically translated somewhere else).
-
-One has to look up the set of anchors of each shape, there is no ``default''
-set of anchors, except for the |center| anchor, which should always be present.
-Also, most shapes will declare anchors like |north| or |east|, but this is not
-guaranteed.
-
-
-\subsubsection{Referencing Anchors of Nodes in the Same Picture}
-
-Once a node has been defined, you can refer to its anchors using the following
-commands:
-
-\begin{command}{\pgfpointanchor\marg{node}\marg{anchor}}
- This command is another ``point command'' like the commands described in
- Section~\ref{section-points}. It returns the coordinate of the given
- \meta{anchor} in the given \meta{node}. The command can be used in commands
- like |\pgfpathmoveto|.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgftransformrotate{30}
- \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}
-
- \pgfpathcircle{\pgfpointanchor{x}{north}}{2pt}
- \pgfpathcircle{\pgfpointanchor{x}{south}}{2pt}
- \pgfpathcircle{\pgfpointanchor{x}{east}}{2pt}
- \pgfpathcircle{\pgfpointanchor{x}{west}}{2pt}
- \pgfpathcircle{\pgfpointanchor{x}{north east}}{2pt}
- \pgfusepath{fill}
-\end{pgfpicture}
-\end{codeexample}
-
- In the above example, you may have noticed something curious: The rotation
- transformation is still in force when the anchors are invoked, but it does
- not seem to have an effect. You might expect that the rotation should apply
- to the already rotated points once more.
-
- However, |\pgfpointanchor| returns a point that takes the current
- transformation matrix into account: \emph{The inverse transformation to the
- current coordinate transformation is applied to an anchor point before
- returning it.}
-
- This behavior may seem a bit strange, but you will find it very natural in
- most cases. If you really want to apply a transformation to an anchor point
- (for example, to ``shift it away'' a little bit), you have to invoke
- |\pgfpointanchor| without any transformations in force. Here is an example:
- %
-\makeatletter
-\begin{codeexample}[pre={\makeatletter}]
-\begin{pgfpicture}
- \pgftransformrotate{30}
- \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}
-
- {
- \pgftransformreset
- \pgfpointanchor{x}{east}
- \xdef\mycoordinate{\noexpand\pgfpoint{\the\pgf@x}{\the\pgf@y}}
- }
-
- \pgfpathcircle{\mycoordinate}{2pt}
- \pgfusepath{fill}
-\end{pgfpicture}
-\end{codeexample}
-
- A special situation arises when the \meta{node} lies in a picture different
- from the current picture. In this case, if you have not told \pgfname\ that
- the picture should be ``remembered'', the \meta{node} will be treated as if
- it lay in the current picture. For example, if the \meta{node} was at
- position $(3,2)$ in the original picture, it is treated as if it lay at
- position $(3,2)$ in the current picture. However, if you have told
- \pgfname\ to remember the picture position of the node's picture and also
- of the current picture, then |\pgfpointanchor| will return a coordinate
- that corresponds to the position of the node's anchor on the page,
- transformed into the current coordinate system. For examples and more
- details see Section~\ref{section-cross-pictures-pgf}.
-\end{command}
-
-\begin{command}{\pgfpointshapeborder\marg{node}\marg{point}}
- This command returns the point on the border of the shape that lies on a
- straight line from the center of the node to \meta{point}. For complex
- shapes it is not guaranteed that this point will actually lie on the
- border, it may be on the border of a ``simplified'' version of the shape.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \begin{pgfscope}
- \pgftransformrotate{30}
- \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}
- \end{pgfscope}
- \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{2cm}{1cm}}}{2pt}
- \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt}
- \pgfpathcircle{\pgfpointshapeborder{x}{\pgfpoint{-1cm}{1cm}}}{2pt}
- \pgfpathcircle{\pgfpoint{-1cm}{1cm}}{2pt}
- \pgfusepath{fill}
-\end{pgfpicture}
-\end{codeexample}
- %
- \emph{Remark:} If the given \meta{point} is almost identical to the center
- of \meta{node}, the node center is returned and a warning message will be
- printed.
-\end{command}
-
-
-\subsubsection{Referencing Anchors of Nodes in Different Pictures}
-\label{section-cross-pictures-pgf}
-
-As a picture is typeset, \pgfname\ keeps track of the positions of all nodes
-inside the picture. What \pgfname\ does not remember is the position of the
-picture \emph{itself} on the page. Thus, if you define a node in one picture
-and then try to reference this node while another picture is typeset, \pgfname\
-will only know the position of the nodes that you try to typeset inside the
-original picture, but it will not know where this picture lies. What is missing
-is the relative positioning of the two pictures.
-
-To overcome this problem, you need to tell \pgfname\ that it should remember
-the position of pictures on a page. If these positions are remembered, then
-\pgfname\ can compute the offset between the pictures and make nodes in
-different pictures accessible.
-
-Determining the positions of pictures on the page is, alas, not-so-easy.
-Because of this, \pgfname\ does not do so automatically. Rather, you have to
-proceed as follows:
-%
-\begin{enumerate}
- \item You have to use a backend driver that supports position tracking.
- pdf\TeX\ is one such driver, |dvips| currently is not.
- \item You have to say |\pgfrememberpicturepositiononpagetrue| somewhere
- before or inside every picture
- %
- \begin{itemize}
- \item in which you wish to reference a node and
- \item from which you wish to reference a node in another picture.
- \end{itemize}
- %
- The second item is important since \pgfname\ does not only need to know
- the position of the picture in which the node you wish to reference
- lies, but it also needs to know where the current picture lies.
- \item You typically have to run \TeX\ twice (depending on the backend
- driver) since the position information typically gets written into an
- external file on the first run and is available only on the second run.
- \item You have to switch off automatic bounding bound computations. The
- reason is that the node in the other picture should not influence the
- size of the bounding box of the current picture. You should say
- |\pgfusepath{use as bounding box}| before using a coordinate in another
- picture.
-\end{enumerate}
-
-
-\subsection{Special Nodes}
-
-There are several special nodes that are always defined and which you should
-not attempt to redefine.
-
-\begin{predefinednode}{current bounding box}
- This node is of shape |rectangle|. Unlike normal nodes, its size changes
- constantly and always reflects the size of the bounding box of the current
- picture. This means that, for instance, that
- %
-\begin{codeexample}[code only]
-\pgfpointanchor{current bounding box}{south east}
-\end{codeexample}
- %
- returns the lower left corner of the bounding box of the current picture.
-\end{predefinednode}
-
-\begin{predefinednode}{current path bounding box}
- This node is also of shape |rectangle|. Its size is the size of the
- bounding box of the current path.
-\end{predefinednode}
-
-\begin{predefinednode}{current subpath start}
- This node is of shape |coordinate| and is at the beginning of the current
- subpath. This is the position of the last move-to operation.
-\end{predefinednode}
-
-\begin{predefinednode}{current page}
- This node is inside a virtual remembered picture. The size of this node is
- the size of the current page. This means that if you create a remembered
- picture and inside this picture you reference an anchor of this node, you
- reference an absolute position on the page. To demonstrate the effect, the
- following code puts some text in the lower left corner of the current page.
- Note that this works only if the backend driver supports it, otherwise the
- text is inserted right here.
- %
-{%
-\pgfrememberpicturepositiononpagetrue%
-\begin{pgfpicture}
- \pgfusepath{use as bounding box}
- \pgftransformshift{\pgfpointanchor{current page}{south west}}
- \pgftransformshift{\pgfpoint{1cm}{1cm}}
- \pgftext[left,base]{
- \textcolor{red}{
- Text absolutely positioned in
- the lower left corner.}
- }
-\end{pgfpicture}
-}%
-\begin{codeexample}[code only]
-\pgfrememberpicturepositiononpagetrue
-\begin{pgfpicture}
- \pgfusepath{use as bounding box}
- \pgftransformshift{\pgfpointanchor{current page}{south west}}
- \pgftransformshift{\pgfpoint{1cm}{1cm}}
- \pgftext[left,base]{
- \textcolor{red}{
- Text absolutely positioned in
- the lower left corner.}
- }
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{predefinednode}
-
-There is also an option that allows you to create new special nodes quite
-similar to the above:
-%
-\begin{key}{/pgf/local bounding box=\meta{node name}}
-\keyalias{tikz}
- This defines a new node \meta{node name} whose size is the bounding box
- around all objects in the current scope starting at the position where this
- option was given. After the end of the scope, the \meta{node name} is still
- available. You can use this option to keep track of the size of a certain
- area. Note that excessive use of this option (keeping track of dozens of
- bounding boxes at the same time) will slow things down.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{scopes}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- { [local bounding box=outer box]
- \draw (1,1) circle (.5) [local bounding box=inner box] (2,2) circle (.5);
- }
- \draw (outer box.south west) rectangle (outer box.north east);
- \draw[red] (inner box.south west) rectangle (inner box.north east);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Declaring New Shapes}
-
-There are only three predefined shapes, see
-Section~\ref{section-predefined-shapes}, so there must be some way of defining
-new shapes. Defining a shape is, unfortunately, a not-quite-trivial process.
-The reason is that shapes need to be both very flexible (their size will vary
-greatly according to circumstances) and they need to be constructed reasonably
-``fast''. \pgfname\ must be able to handle pictures with several hundreds of
-nodes and documents with thousands of nodes in total. It would not do if
-\pgfname\ had to compute and store, say, dozens of anchor positions for every
-node.
-
-
-\subsubsection{What Must Be Defined For a Shape?}
-
-In order to define a new shape, you must provide:
-%
-\begin{itemize}
- \item a \emph{shape name},
- \item code for computing the \emph{saved anchors} and \emph{saved
- dimensions},
- \item code for computing \emph{anchor} positions in terms of the saved
- anchors,
- \item optionally code for the \emph{background path} and \emph{foreground
- path},
- \item optionally code for \emph{things to be drawn before or behind} the
- background and foreground paths.
- \item optionally a list of node parts.
-\end{itemize}
-
-
-\subsubsection{Normal Anchors Versus Saved Anchors}
-
-Anchors are special places in a shape. For example, the |north east| anchor,
-which is a normal anchor, lies at the upper right corner of the |rectangle|
-shape, as does |\northeast|, which is a saved anchor. The difference is the
-following: \emph{saved anchors are computed and stored for each node, anchors
-are only computed as needed.} The user only has access to the normal anchors,
-but a normal anchor can just ``copy'' or ``pass through'' the location of a
-saved anchor.
-
-The idea behind all this is that a shape can declare a very large number of
-normal anchors, but when a node of this shape is created, these anchors are not
-actually computed. However, this causes a problem: When we wish to reference an
-anchor of a node at some later time, we must still be able to compute the
-position of the anchor. For this, we may need a lot of information: What was
-the transformation matrix that was in force when the node was created? What was
-the size of the text box? What were the values of the different separation
-dimensions? And so on.
-
-To solve this problem, \pgfname\ will always compute the locations of all
-\emph{saved anchors} and store these positions. Then, when an normal anchor
-position is requested later on, the anchor position can be given just from
-knowing where the locations of the saved anchors are.
-
-As an example, consider the |rectangle| shape. For this shape two anchors are
-saved: The |\northeast| corner and the |\southwest| corner. A normal anchor
-like |north west| can now easily be expressed in terms of these coordinates:
-Take the $x$-position of the |\southwest| point and the $y$-position of the
-|\northeast| point. The |rectangle| shape currently defines 13 normal anchors,
-but needs only two saved anchors. Adding new anchors like a |south south east|
-anchor would not increase the memory and computation requirements of pictures.
-
-All anchors (both saved and normal) are specified in a local \emph{shape
-coordinate space}. This is also true for the background and foreground paths.
-The |\pgfnode| macro will automatically apply appropriate transformations to
-the coordinates so that the shape is shifted to the right anchor or otherwise
-transformed.
-
-
-\subsubsection{Command for Declaring New Shapes}
-
-The following command declares a new shape:
-%
-\begin{command}{\pgfdeclareshape\marg{shape name}\marg{shape specification}}
- This command declares a new shape named \meta{shape name}. The shape name
- can later be used in commands like |\pgfnode|.
-
- The \meta{shape specification} is some \TeX\ code containing calls to
- special commands that are only defined inside the \meta{shape
- specification} (similarly to commands like |\draw| that are only available
- inside the |{tikzpicture}| environment).
-
- \example Here is the code of the |coordinate| shape:
- %
-\begin{codeexample}[code only]
-\pgfdeclareshape{coordinate}
-{
- \savedanchor\centerpoint{%
- \pgf@x=.5\wd\pgfnodeparttextbox%
- \pgf@y=.5\ht\pgfnodeparttextbox%
- \advance\pgf@y by -.5\dp\pgfnodeparttextbox%
- }
- \anchor{center}{\centerpoint}
- \anchorborder{\centerpoint}
-}
-\end{codeexample}
-
- The special commands are explained next. In the examples given for the
- special commands a new shape will be constructed, which we might call
- |simple rectangle|. It should behave like the normal rectangle shape, only
- without bothering about the fine details like inner and outer separations.
- The skeleton for the shape is the following.
- %
-\begin{codeexample}[code only]
-\pgfdeclareshape{simple rectangle}{
- ...
-}
-\end{codeexample}
-
- \begin{command}{\nodeparts\marg{list of node parts}}
- This command declares which parts make up nodes of this shape. A
- \emph{node part} is a (possibly empty) text label that is drawn when a
- node of the shape is created.
-
- By default, a shape has just one node part called |text|. However,
- there can be several node parts. For example, the |circle split| shape
- has two parts: the |text| part, which shows that the upper text, and a
- |lower| part, which shows the lower text. For the |circle split| shape
- the |\nodeparts| command was called with the argument |{text,lower}|.
-
- When a multipart node is created, the text labels are drawn in the
- sequences listed in the \meta{list of node parts}. For each node part,
- you must have declared one anchor and the \TeX-box of the part is
- placed at this anchor. For a node part called |XYZ| the \TeX-box
- |\pgfnodepartXYZbox| is placed at anchor |XYZ|.
- \end{command}
-
- \begin{command}{\savedanchor\marg{command}\marg{code}}
- This command declares a saved anchor. The argument \meta{command}
- should be a \TeX\ macro name like |\centerpoint|.
-
- The \meta{code} will be executed each time |\pgfnode| (or
- |\pgfmultipartnode|) is called to create a node of the shape
- \meta{shape name}. When the \meta{code} is executed, the \TeX-boxes of
- the node parts will contain the text labels of the node. Possibly,
- these box are void. For example, if there is just a |text| part, the
- node |\pgfnodeparttextbox| will be set up when the \meta{code} is
- executed.
-
- The \meta{code} can use the width, height, and depth of the box(es) to
- compute the location of the saved anchor. In addition, the \meta{code}
- can take into account the values of dimensions like |\pgfshapeminwidth|
- or |\pgfshapeinnerxsep|. Furthermore, the \meta{code} can take into
- consideration the values of any further shape-specific variables that
- are set at the moment when |\pgfnode| is called.
-
- The net effect of the \meta{code} should be to set the two \TeX\
- dimensions |\pgf@x| and |\pgf@y|. One way to achieve this is to say
- |\pgfpoint{|\meta{x value}|}{|\meta{y value}|}| at the end of the
- \meta{code}, but you can also just set these variables. The values that
- |\pgf@x| and |\pgf@y| have after the code has been executed, let us
- call them $x$ and $y$, will be recorded and stored together with the
- node that is created by the command |\pgfnode|.
-
- The macro \meta{command} is defined to be |\pgfpoint{|$x$|}{|$y$|}|.
- However, the \meta{command} is only locally defined while anchor
- positions are being computed. Thus, it is possible to use very simple
- names for \meta{command}, like |\center| or |\a|, without causing a
- name-clash. (To be precise, very simple \meta{command} names will clash
- with existing names, but only locally inside the computation of anchor
- positions; and we do not need the normal |\center| command during these
- computations.)
-
- For our |simple rectangle| shape, we will need only one saved anchor:
- The upper right corner. The lower left corner could either be the
- origin or the ``mirrored'' upper right corner, depending on whether we
- want the text label to have its lower left corner at the origin or
- whether the text label should be centered on the origin. Either will be
- fine, for the final shape this will make no difference since the shape
- will be shifted anyway. So, let us assume that the text label is
- centered on the origin (this will be specified later on using the
- |text| anchor). We get the following code for the upper right corner:
- %
-\begin{codeexample}[code only]
-\savedanchor{\upperrightcorner}{
- \pgf@y=.5\ht\pgfnodeparttextbox % height of the box, ignoring the depth
- \pgf@x=.5\wd\pgfnodeparttextbox % width of the box
-}
-\end{codeexample}
-
- If we wanted to take, say, the |\pgfshapeminwidth| into account, we
- could use the following code:
- %
-\begin{codeexample}[code only]
-\savedanchor{\upperrightcorner}{
- \pgf@y=.\ht\pgfnodeparttextbox % height of the box
- \pgf@x=.\wd\pgfnodeparttextbox % width of the box
- \setlength{\pgf@xa}{\pgfshapeminwidth}
- \ifdim\pgf@x<.5\pgf@xa
- \pgf@x=.5\pgf@xa
- \fi
-}
-\end{codeexample}
- %
- Note that we could not have written |.5\pgfshapeminwidth| since the
- minimum width is stored in a ``plain text macro'', not as a real
- dimension. So if |\pgfshapeminwidth| depth were 2cm, writing
- |.5\pgfshapeminwidth| would yield the same as |.52cm|.
-
- In the ``real'' |rectangle| shape the code is somewhat more complex,
- but you get the basic idea.
- \end{command}
- %
- \begin{command}{\saveddimen\marg{command}\marg{code}}
- This command is similar to |\savedanchor|, only instead of setting
- \meta{command} to |\pgfpoint{|$x$|}{|$y$|}|, the \meta{command} is set
- just to (the value of) $x$.
-
- In the |simple rectangle| shape we might use a saved dimension to store
- the depth of the shape box.
- %
-\begin{codeexample}[code only]
-\saveddimen{\depth}{
- \pgf@x=\dp\pgfnodeparttextbox
-}
-\end{codeexample}
- \end{command}
- %
- \begin{command}{\savedmacro\marg{command}\marg{code}}
- This command is similar to |\saveddimen|, only at some point in
- \meta{code}, \meta{command} should be defined appropriately, (this
- could be a value, or some text).
-
- In the |regular polygon| shape, a saved macro is used to store the
- number of sides of the polygon.
- %
-\begin{codeexample}[code only]
-\savedmacro{\sides}{\let\sides\pgfpolygonsides}
-\end{codeexample}
- \end{command}
- %
- \begin{command}{\anchor\marg{name}\marg{code}}
- This command declares an anchor named \meta{name}. Unlike for saved
- anchors, the \meta{code} will not be executed each time a node is
- declared. Rather, the \meta{code} is only executed when the anchor is
- specifically requested; either for anchoring the node during its
- creation or as a position in the shape referenced later on.
-
- The \meta{name} is a quite arbitrary string that is not ``passed down''
- to the system level. Thus, names like |south| or |1| or |::| would all
- be fine.
-
- A saved anchor is not automatically also a normal anchor. If you wish
- to give the users access to a saved anchor you must declare a normal
- anchor that just returns the position of the saved anchor.
-
- When the \meta{code} is executed, all saved anchor macros will be
- defined. Thus, you can reference them in your \meta{code}. The effect
- of the \meta{code} should be to set the values of |\pgf@x| and |\pgf@y|
- to the coordinates of the anchor.
-
- Let us consider some example for the |simple rectangle| shape. First,
- we would like to make the upper right corner publicly available, for
- example as |north east|:
- %
-\begin{codeexample}[code only]
-\anchor{north east}{\upperrightcorner}
-\end{codeexample}
-
- The |\upperrightcorner| macro will set |\pgf@x| and |\pgf@y| to the
- coordinates of the upper right corner. Thus, |\pgf@x| and |\pgf@y| will
- have exactly the right values at the end of the anchor's code.
-
- Next, let us define a |north west| anchor. For this anchor, we can
- negate the |\pgf@x| variable:
- %
-\begin{codeexample}[code only]
-\anchor{north west}{
- \upperrightcorner
- \pgf@x=-\pgf@x
-}
-\end{codeexample}
-
- Finally, it is a good idea to always define a |center| anchor, which
- will be the default location for a shape.
- %
-\begin{codeexample}[code only]
-\anchor{center}{\pgfpointorigin}
-\end{codeexample}
-
- You might wonder whether we should not take into consideration that the
- node is not placed at the origin, but has been shifted somewhere.
- However, the anchor positions are always specified in the shape's
- ``private'' coordinate system. The ``outer'' transformation that has
- been applied to the shape upon its creation is applied automatically to
- the coordinates returned by the anchor's \meta{code}.
-
- Our |simple rectangle| only has one text label (node part) called
- |text|. This is the default situation, so we do not need to do
- anything. For the |text| node part we must set up a |text| anchor. Upon
- creation of a node, this anchor will be made to coincide with the left
- endpoint of the baseline of the text label (within the private
- coordinate system of the shape). By default, the |text| anchor is at
- the origin, but you may change this. For example, we would say
- %
-\begin{codeexample}[code only]
-\anchor{text}{%
- \upperrightcorner%
- \pgf@x=-\pgf@x%
- \pgf@y=-\pgf@y%
-}
-\end{codeexample}
- to center the text label on the origin in the shape coordinate space.
- Note that we could \emph{not} have written the following:
- %
-\begin{codeexample}[code only]
-\anchor{text}{\pgfpoint{-.5\wd\pgfnodeparttextbox}{-.5\ht\pgfnodeparttextbox}}
-\end{codeexample}
- %
- Do you see why this is wrong? The problem is that the box
- |\pgfnodeparttextbox| will most likely not have the correct size when
- the anchor is computed. After all, the anchor position might be
- recomputed at a time when several other nodes have been created.
-
- If a shape has several node parts, we would have to define an anchor
- for each part.
- \end{command}
-
- \begin{command}{\deferredanchor\marg{name}\marg{code}}
- This command declares an anchor named \meta{name}. It works like
- |\anchor|. However, unlike for anchors declared by |\anchor|,
- \meta{name} will \emph{not} be expanded during the shape declaration
- (i.e.\ not during |\pgfdeclareshape|). Rather, the \meta{name} is
- expanded when the \emph{node} is actually used (with |\pgfnode| or more
- likely with |\node|). This may be useful if the anchor name is context
- dependent (depending, for example, on the value of a key).
- %
-\begin{codeexample}[code only]
-\makeatletter
-\def\foo{foo}
-\pgfdeclareshape{simple shape}{%
- \savedanchor{\center}{%
- \pgfpointorigin}
- \anchor{center}{\center}
- \savedanchor{\anchorfoo}{%
- \pgf@x=1cm
- \pgf@y=0cm}
- \deferredanchor{anchor \foo}{\anchorfoo}}
-
-\begin{tikzpicture}
- \node[simple shape] (Test1) at (0,0) {};
- \fill (Test1.anchor foo) circle (2pt) node[below] {anchor foo anchor};
- %
- \def\foo{bar}
- \node[simple shape] (Test2) at (2,2) {};
- \fill (Test2.anchor bar) circle (2pt) node[below] {anchor bar anchor};
-\end{tikzpicture}
-\end{codeexample}
- \end{command}
- %
- \begin{command}{\anchorborder\marg{code}}
- A \emph{border anchor} is an anchor point on the border of the shape.
- What exactly is considered as the ``border'' of the shape depends on
- the shape.
-
- When the user requests a point on the border of the shape using the
- |\pgfpointshapeborder| command, the \meta{code} will be executed to
- discern this point. When the execution of the \meta{code} starts, the
- dimensions |\pgf@x| and |\pgf@y| will have been set to a location $p$
- in the shape's coordinate system, and relative to the anchor |center|.
- Note that |\pgfpointshapeborder| will produce an error if the shape does
- not contain the |center| anchor.
-
- It is now the job of the \meta{code} to set up |\pgf@x| and |\pgf@y|
- such that they specify the point on the shape's border that lies on a
- straight line from the shape's center to the point $p$. Usually, this is
- a somewhat complicated computation, involving many case distinctions and
- some basic math. Note that the output coordinates must be returned in the
- shape's coordinate system, \emph{no longer} relative to the |center|
- anchor. While these different points of reference are only noticeable if
- the |center| anchor is not at the origin of the shape's coordinate system,
- it implies that ``doing nothing'' as a border anchor, i.e., returning the
- point that was fed to |\pgfpointshapeborder| requires adding the |center|
- anchor to the input coordinates.
-
- For our |simple rectangle| we must compute a point on the border of a
- rectangle whose one corner is the origin (ignoring the depth for
- simplicity) and whose other corner is |\upperrightcorner|. The
- following code might be used:
- %
-\begin{codeexample}[code only]
-\anchorborder{%
- % Call a function that computes a border point. Since this
- % function will modify dimensions like \pgf@x, we must move them to
- % other dimensions.
- \@tempdima=\pgf@x
- \@tempdimb=\pgf@y
- \pgfpointborderrectangle{\pgfpoint{\@tempdima}{\@tempdimb}}{\upperrightcorner}
-}
-\end{codeexample}
- \end{command}
- %
- \begin{command}{\backgroundpath\marg{code}}
- This command specifies the path that ``makes up'' the background of the
- shape. Note that the shape cannot prescribe what is going to happen
- with the path: It might be drawn, shaded, filled, or even thrown away.
- If you want to specify that something should ``always'' happen when
- this shape is drawn (for example, if the shape is a stop-sign, we
- \emph{always} want it to be filled with a red color), you can use
- commands like |\beforebackgroundpath|, explained below.
-
- When the \meta{code} is executed, all saved anchors will be in effect.
- The \meta{code} should contain path construction commands.
-
- For our |simple rectangle|, the following code might be used:
- %
-\begin{codeexample}[code only]
-\backgroundpath{
- \pgfpathrectanglecorners
- {\upperrightcorner}
- {\pgfpointscale{-1}{\upperrightcorner}}
-}
-\end{codeexample}
- %
- As the name suggests, the background path is used ``behind'' the text
- labels. Thus, this path is used first, then the text labels are drawn,
- possibly obscuring part of the path.
- \end{command}
- %
- \begin{command}{\foregroundpath\marg{code}}
- This command works like |\backgroundpath|, only it is invoked after the
- text labels have been drawn. This means that this path can possibly
- obscure (part of) the text labels.
- \end{command}
- %
- \begin{command}{\behindbackgroundpath\marg{code}}
- Unlike the previous two commands, \meta{code} should not only construct
- a path, it should also use this path in whatever way is appropriate.
- For example, the \meta{code} might fill some area with a uniform color.
-
- Whatever the \meta{code} does, it does it first. This means that any
- drawing done by \meta{code} will be even behind the background path.
-
- Note that the \meta{code} is protected with a |{pgfscope}|.
- \end{command}
- %
- \begin{command}{\beforebackgroundpath\marg{code}}
- This command works like |\behindbackgroundpath|, only the \meta{code}
- is executed after the background path has been used, but before the
- texts label are drawn.
- \end{command}
- %
- \begin{command}{\behindforegroundpath\marg{code}}
- The \meta{code} is executed after the text labels have been drawn, but
- before the foreground path is used.
- \end{command}
- %
- \begin{command}{\beforeforegroundpath\marg{code}}
- This \meta{code} is executed at the very end.
- \end{command}
- %
- \begin{command}{\inheritsavedanchors|[from=|\marg{another shape name}|]|}
- This command allows you to inherit the code for saved anchors from
- \meta{another shape name}. The idea is that if you wish to create a new
- shape that is just a small modification of a another shape, you can
- recycle the code used for \meta{another shape name}.
-
- The effect of this command is the same as if you had called
- |\savedanchor| and |\saveddimen| for each saved anchor or saved
- dimension declared in \meta{another shape name}. Thus, it is not
- possible to ``selectively'' inherit only some saved anchors, you always
- have to inherit all saved anchors from another shape. However, you can
- inherit the saved anchors of more than one shape by calling this
- command several times.
- \end{command}
- %
- \begin{command}{\inheritbehindbackgroundpath|[from=|\marg{another shape name}|]|}
- This command can be used to inherit the code used for the drawings
- behind the background path from \meta{another shape name}.
- \end{command}
- %
- \begin{command}{\inheritbackgroundpath|[from=|\marg{another shape name}|]|}
- Inherits the background path code from \meta{another shape name}.
- \end{command}
- %
- \begin{command}{\inheritbeforebackgroundpath|[from=|\marg{another shape name}|]|}
- Inherits the before background path code from \meta{another shape
- name}.
- \end{command}
- %
- \begin{command}{\inheritbehindforegroundpath|[from=|\marg{another shape name}|]|}
- Inherits the behind foreground path code from \meta{another shape
- name}.
- \end{command}
- %
- \begin{command}{\inheritforegroundpath|[from=|\marg{another shape name}|]|}
- Inherits the foreground path code from \meta{another shape name}.
- \end{command}
- %
- \begin{command}{\inheritbeforeforegroundpath|[from=|\marg{another shape name}|]|}
- Inherits the before foreground path code from \meta{another shape
- name}.
- \end{command}
- %
- \begin{command}{\inheritanchor|[from=|\marg{another shape name}|]|\marg{name}}
- Inherits the code of one specific anchor named \meta{name} from
- \meta{another shape name}. Thus, unlike saved anchors, which must be
- inherited collectively, normal anchors can and must be inherited
- individually.
- \end{command}
- %
- \begin{command}{\inheritanchorborder|[from=|\marg{another shape name}|]|}
- Inherits the border anchor code from \meta{another shape name}.
- \end{command}
-
- The following example shows how a shape can be defined that relies heavily
- on inheritance:
- %
-\makeatletter
-\begin{codeexample}[
- preamble={\usetikzlibrary{shapes.geometric}},
- pre={\makeatletter},
-]
-\pgfdeclareshape{document}{
- \inheritsavedanchors[from=rectangle] % this is nearly a rectangle
- \inheritanchorborder[from=rectangle]
- \inheritanchor[from=rectangle]{center}
- \inheritanchor[from=rectangle]{north}
- \inheritanchor[from=rectangle]{south}
- \inheritanchor[from=rectangle]{west}
- \inheritanchor[from=rectangle]{east}
- % ... and possibly more
- \backgroundpath{% this is new
- % store lower right in xa/ya and upper right in xb/yb
- \southwest \pgf@xa=\pgf@x \pgf@ya=\pgf@y
- \northeast \pgf@xb=\pgf@x \pgf@yb=\pgf@y
- % compute corner of ``flipped page''
- \pgf@xc=\pgf@xb \advance\pgf@xc by-5pt % this should be a parameter
- \pgf@yc=\pgf@yb \advance\pgf@yc by-5pt
- % construct main path
- \pgfpathmoveto{\pgfpoint{\pgf@xa}{\pgf@ya}}
- \pgfpathlineto{\pgfpoint{\pgf@xa}{\pgf@yb}}
- \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yb}}
- \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}}
- \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@ya}}
- \pgfpathclose
- % add little corner
- \pgfpathmoveto{\pgfpoint{\pgf@xc}{\pgf@yb}}
- \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}}
- \pgfpathlineto{\pgfpoint{\pgf@xb}{\pgf@yc}}
- \pgfpathlineto{\pgfpoint{\pgf@xc}{\pgf@yc}}
- }
-}\hskip-1.2cm
-\begin{tikzpicture}
- \node[shade,draw,shape=document,inner sep=2ex] (x) {Remark};
- \node[fill=yellow!80!black,draw,ellipse,double]
- at ([shift=(-80:3cm)]x) (y) {Use Case};
-
- \draw[dashed] (x) -- (y);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-paths.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-paths.tex
deleted file mode 100644
index 690de303d4..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-paths.tex
+++ /dev/null
@@ -1,876 +0,0 @@
-% Copyright 2018 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{Constructing Paths}
-
-\subsection{Overview}
-
-The ``basic entity of drawing'' in \pgfname\ is the \emph{path}. A path
-consists of several parts, each of which is either a closed or open curve. An
-open curve has a starting point and an end point and, in between, consists of
-several \emph{segments}, each of which is either a straight line or a Bézier
-curve. Here is an example of a path (in red) consisting of two parts, one open,
-one closed:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=2]
- \draw[thick,red]
- (0,0) coordinate (a)
- -- coordinate (ab) (1,.5) coordinate (b)
- .. coordinate (bc) controls +(up:1cm) and +(left:1cm) .. (3,1) coordinate (c)
- (0,1) -- (2,1) -- coordinate (x) (1,2) -- cycle;
-
- \draw (a) node[below] {start part 1}
- (ab) node[below right] {straight segment}
- (b) node[right] {end first segment}
- (c) node[right] {end part 1}
- (x) node[above right] {part 2 (closed)};
-\end{tikzpicture}
-\end{codeexample}
-
-A path, by itself, has no ``effect'', that is, it does not leave any marks on
-the page. It is just a set of points on the plane. However, you can \emph{use}
-a path in different ways. The most natural actions are \emph{stroking} (also
-known as \emph{drawing}) and \emph{filling}. Stroking can be imagined as
-picking up a pen of a certain diameter and ``moving it along the path''.
-Filling means that everything ``inside'' the path is filled with a uniform
-color. Naturally, the open parts of a path must first be closed before a path
-can be filled.
-
-In \pgfname, there are numerous commands for constructing paths, all of which
-start with |\pgfpath|. There are also commands for \emph{using} paths, though
-most operations can be performed by calling |\pgfusepath| with an appropriate
-parameter.
-
-As a side-effect, the path construction commands keep track of two bounding
-boxes. One is the bounding box for the current path, the other is a bounding
-box for all paths in the current picture. See Section~\ref{section-bb} for more
-details.
-
-Each path construction command extends the current path in some way. The
-``current path'' is a global entity that persists across \TeX\ groups. Thus,
-between calls to the path construction commands you can perform arbitrary
-computations and even open and close \TeX\ groups. The current path only gets
-``flushed'' when the |\pgfusepath| command is called (or when the soft-path
-subsystem is used directly, see Section~\ref{section-soft-paths}).
-
-
-\subsection{The Move-To Path Operation}
-
-The most basic operation is the move-to operation. It must be given at the
-beginning of paths, though some path construction command (like
-|\pgfpathrectangle|) generate move-tos implicitly. A move-to operation can also
-be used to start a new part of a path.
-
-\begin{command}{\pgfpathmoveto\marg{coordinate}}
- This command expects a \pgfname-coordinate like |\pgfpointorigin| as its
- parameter. When the current path is empty, this operation will start the
- path at the given \meta{coordinate}. If a path has already been partly
- constructed, this command will end the current part of the path and start a
- new one.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{2cm}{1cm}}
- \pgfpathlineto{\pgfpoint{3cm}{0.5cm}}
- \pgfpathlineto{\pgfpoint{3cm}{0cm}}
- \pgfsetfillcolor{yellow!80!black}
- \pgfusepath{fill,stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{2cm}{1cm}}
- \pgfpathmoveto{\pgfpoint{2cm}{1cm}} % New part
- \pgfpathlineto{\pgfpoint{3cm}{0.5cm}}
- \pgfpathlineto{\pgfpoint{3cm}{0cm}}
- \pgfsetfillcolor{yellow!80!black}
- \pgfusepath{fill,stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
- The command will apply the current coordinate transformation matrix to
- \meta{coordinate} before using it.
-
- It will update the bounding box of the current path and picture, if
- necessary.
-\end{command}
-
-
-\subsection{The Line-To Path Operation}
-
-\begin{command}{\pgfpathlineto\marg{coordinate}}
- This command extends the current path in a straight line to the given
- \meta{coordinate}. If this command is given at the beginning of path
- without any other path construction command given before (in particular
- without a move-to operation), the \TeX\ file may compile without an error
- message, but a viewer application may display an error message when trying
- to render the picture.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{2cm}{1cm}}
- \pgfsetfillcolor{yellow!80!black}
- \pgfusepath{fill,stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
- The command will apply the current coordinate transformation matrix to
- \meta{coordinate} before using it.
-
- It will update the bounding box of the current path and picture, if
- necessary.
-\end{command}
-
-
-\subsection{The Curve-To Path Operations}
-
-\begin{command}{\pgfpathcurveto\marg{support 1}\marg{support 2}\marg{coordinate}}
- This command extends the current path with a Bézier curve from the last
- point of the path to \meta{coordinate}. The \meta{support 1} and
- \meta{support 2} are the first and second support point of the Bézier
- curve. For more information on Bézier curves, please consult a standard
- textbook on computer graphics.
-
- Like the line-to command, this command may not be the first path
- construction command in a path.
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathcurveto
- {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{1cm}}{\pgfpoint{3cm}{0cm}}
- \pgfsetfillcolor{yellow!80!black}
- \pgfusepath{fill,stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
- The command will apply the current coordinate transformation matrix to
- \meta{coordinate} before using it.
-
- It will update the bounding box of the current path and picture, if
- necessary. However, the bounding box is simply made large enough such that
- it encompasses all of the support points and the \meta{coordinate}. This
- will guarantee that the curve is completely inside the bounding box, but
- the bounding box will typically be quite a bit too large. It is not clear
- (to me) how this can be avoided without resorting to ``some serious math''
- in order to calculate a precise bounding box.
-\end{command}
-
-\begin{command}{\pgfpathquadraticcurveto\marg{support}\marg{coordinate}}
- This command works like |\pgfpathcurveto|, only it uses a quadratic Bézier
- curve rather than a cubic one. This means that only one support point is
- needed.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathquadraticcurveto
- {\pgfpoint{1cm}{1cm}}{\pgfpoint{2cm}{0cm}}
- \pgfsetfillcolor{yellow!80!black}
- \pgfusepath{fill,stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
- Internally, the quadratic curve is converted into a cubic curve. The only
- noticeable effect of this is that the points used for computing the
- bounding box are the control points of the converted curve rather than
- \meta{support}. The main effect of this is that the bounding box will be a
- bit tighter than might be expected. In particular, \meta{support} will not
- always be part of the bounding box.
-\end{command}
-
-There exist two commands to draw only part of a cubic Bézier curve:
-
-\begin{command}{\pgfpathcurvebetweentime\marg{time $t_1$}\marg{time $t_2$}\marg{point p}\marg{point $s_1$}\marg{point $s_2$}\marg{point q}}
- This command draws the part of the curve described by $p$, $s_1$, $s_2$ and
- $q$ between the times $t_1$ and $t_2$. A time value of 0 indicates the
- point $p$ and a time value of 1 indicates point $q$. This command includes
- a moveto operation to the first point.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw [thin] (0,0) .. controls (0,2) and (3,0) .. (3,2);
- \pgfpathcurvebetweentime{0.25}{0.9}{\pgfpointxy{0}{0}}{\pgfpointxy{0}{2}}
- {\pgfpointxy{3}{0}}{\pgfpointxy{3}{2}}
- \pgfsetstrokecolor{red}
- \pgfsetstrokeopacity{0.5}
- \pgfsetlinewidth{2pt}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpathcurvebetweentimecontinue\marg{time $t_1$}\marg{time $t_2$}\marg{point p}\marg{point $s_1$}\marg{point $s_2$}\marg{point q}}
- This command works like |\pgfpathcurvebetweentime|, except that a moveto
- operation is \emph{not} made to the first point.
-\end{command}
-
-
-\subsection{The Close Path Operation}
-
-\begin{command}{\pgfpathclose}
- This command closes the current part of the path by appending a straight
- line to the start point of the current part. Note that there \emph{is} a
- difference between closing a path and using the line-to operation to add a
- straight line to the start of the current path. The difference is
- demonstrated by the upper corners of the triangles in the following
- example:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfsetlinewidth{5pt}
- \pgfpathmoveto{\pgfpoint{1cm}{1cm}}
- \pgfpathlineto{\pgfpoint{0cm}{-1cm}}
- \pgfpathlineto{\pgfpoint{1cm}{-1cm}}
- \pgfpathclose
- \pgfpathmoveto{\pgfpoint{2.5cm}{1cm}}
- \pgfpathlineto{\pgfpoint{1.5cm}{-1cm}}
- \pgfpathlineto{\pgfpoint{2.5cm}{-1cm}}
- \pgfpathlineto{\pgfpoint{2.5cm}{1cm}}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Arc, Ellipse and Circle Path Operations}
-
-The path construction commands that we have discussed up to now are sufficient
-to create all paths that can be created ``at all''. However, it is useful to
-have special commands to create certain shapes, like circles, that arise often
-in practice.
-
-In the following, the commands for adding (parts of) (transformed) circles to a
-path are described.
-
-\begin{command}{\pgfpatharc\marg{start angle}\marg{end angle}{\ttfamily\char`\{}\meta{radius}\opt{| and |\meta{y-radius}}{\ttfamily\char`\}}}
- This command appends a part of a circle (or an ellipse) to the current
- path. Imagine the curve between \meta{start angle} and \meta{end angle} on
- a circle of radius \meta{radius} (if $\meta{start angle} < \meta{end
- angle}$, the curve goes around the circle counterclockwise, otherwise
- clockwise). This curve is now moved such that the point where the curve
- starts is the previous last point of the path. Note that this command will
- \emph{not} start a new part of the path, which is important for example for
- filling purposes.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{0cm}{1cm}}
- \pgfpatharc{180}{90}{.5cm}
- \pgfpathlineto{\pgfpoint{3cm}{1.5cm}}
- \pgfpatharc{90}{-45}{.5cm}
- \pgfusepath{fill}
-\end{tikzpicture}
-\end{codeexample}
-
- Saying |\pgfpatharc{0}{360}{1cm}| ``nearly'' gives you a full circle. The
- ``nearly'' refers to the fact that the circle will not be closed. You can
- close it using |\pgfpathclose|.
-
- If the optional \meta{y-radius} is given, the \meta{radius} is the
- $x$-radius and the \meta{y-radius} the $y$-radius of the ellipse from which
- the curve is taken:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpatharc{180}{45}{2cm and 1cm}
- \pgfusepath{draw}
-\end{tikzpicture}
-\end{codeexample}
-
- The axes of the circle or ellipse from which the arc is ``taken'' always
- point up and right. However, the current coordinate transformation matrix
- will have an effect on the arc. This can be used to, say, rotate an arc:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgftransformrotate{30}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpatharc{180}{45}{2cm and 1cm}
- \pgfusepath{draw}
-\end{tikzpicture}
-\end{codeexample}
-
- The command will update the bounding box of the current path and picture,
- if necessary. Unless rotation or shearing transformations are applied, the
- bounding box will be tight.
-\end{command}
-
-\begin{command}{\pgfpatharcaxes\marg{start angle}\marg{end angle}\marg{first axis}\marg{second axis}}
- This command is similar to |\pgfpatharc|. The main difference is how the
- ellipse or circle is specified from which the arc is taken. The two
- parameters \meta{first axis} and \meta{second axis} are the $0^\circ$-axis
- and the $90^\circ$-axis of the ellipse from which the path is taken. Thus,
- |\pgfpatharc{0}{90}{1cm and 2cm}| has the same effect as
- %
-\begin{verbatim}
-\pgfpatharcaxes{0}{90}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{2cm}}
-\end{verbatim}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (2cm,5mm) (0,0) -- (0cm,1cm);
-
- \pgfpathmoveto{\pgfpoint{2cm}{5mm}}
- \pgfpatharcaxes{0}{90}{\pgfpoint{2cm}{5mm}}{\pgfpoint{0cm}{1cm}}
- \pgfusepath{draw}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpatharcto\marg{x-radius}\marg{y-radius}\marg{rotation} \marg{large arc flag}\marg{counterclockwise flag}\\\marg{target point}}
- This command (which directly corresponds to the arc-path command of
- \textsc{svg}) is used to add an arc to the path that starts at the current
- point and ends at \meta{target point}. This arc is part of an ellipse that
- is determined in the following way: Imagine an ellipse with radii
- \meta{x-radius} and \meta{y-radius} that is rotated around its center by
- \meta{rotation} degrees. When you move this ellipse around in the plane,
- there will be exactly two positions such that the two current point and the
- target point lie on the border of the ellipse (excluding pathological
- cases). The flags \meta{large arc flag} and \meta{clockwise flag} are then
- used to decide which of these ellipses should be picked and which arc on
- the picked ellipsis should be used.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \pgfpathmoveto{\pgfpoint{0mm}{20mm}}
- \pgfpatharcto{3cm}{1cm}{0}{0}{0}{\pgfpoint{3cm}{1cm}}
- \pgfusepath{draw}
-\end{tikzpicture}
-\end{codeexample}
- %
- Both flags are considered to be false exactly if they evaluate to |0|,
- otherwise they are true. If the \meta{large arc flag} is true, then the
- angle spanned by the arc will be greater than $180^\circ$, otherwise it
- will be less than $180^\circ$. The \meta{clockwise flag} is used to
- determine which of the two ellipses should be used: if the flag is true,
- then the arc goes from the current point to the target point in a
- counterclockwise direction, otherwise in a clockwise fashion.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \pgfsetlinewidth{2pt}
- % Flags 0 0: red
- \pgfsetstrokecolor{red}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpatharcto{20pt}{10pt}{0}{0}{0}{\pgfpoint{20pt}{10pt}}
- \pgfusepath{stroke}
- % Flags 0 1: blue
- \pgfsetstrokecolor{blue}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpatharcto{20pt}{10pt}{0}{0}{1}{\pgfpoint{20pt}{10pt}}
- \pgfusepath{stroke}
- % Flags 1 0: orange
- \pgfsetstrokecolor{orange}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpatharcto{20pt}{10pt}{0}{1}{0}{\pgfpoint{20pt}{10pt}}
- \pgfusepath{stroke}
- % Flags 1 1: black
- \pgfsetstrokecolor{black}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpatharcto{20pt}{10pt}{0}{1}{1}{\pgfpoint{20pt}{10pt}}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
- \emph{Warning:} The internal computations necessary for this command are
- numerically very unstable. In particular, the arc will not always really
- end at the \meta{target coordinate}, but may be off by up to several
- points. A more precise positioning is currently infeasible due to \TeX's
- numerical weaknesses. The only case it works quite nicely is when the
- resulting angle is a multiple of~$90^\circ$.
-\end{command}
-
-\begin{command}{\pgfpatharctoprecomputed\marg{center point}\marg{start angle}\marg{end angle}\marg{end point}\\\marg{x-radius}\marg{y-radius}\marg{ratio x-radius/y-radius}\marg{ratio y-radius/x-radius}}
- A specialized arc operation which is fast and numerically stable, provided
- a lot of information is given in advance.
-
- In contrast to |\pgfpatharc|, it explicitly interpolates start and end
- points.
-
- In contrast to |\pgfpatharcto|, this routine is numerically stable and
- quite fast since it relies on a lot of available information.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \def\cx{1.5cm}% center x
- \def\cy{1cm}% center y
- \def\startangle{0}%
- \def\endangle{270}%
- \def\a{1.5cm}% xradius
- \def\b{0.5cm}% yradius
- \pgfmathparse{\a/\b}\let\abratio=\pgfmathresult
- \pgfmathparse{\b/\a}\let\baratio=\pgfmathresult
- %
- % start point:
- \pgfpathmoveto{\pgfpoint{\cx+\a*cos(\startangle)}{\cy+\b*sin(\startangle)}}%
- \pgfpatharctoprecomputed
- {\pgfpoint{\cx}{\cy}}
- {\startangle}
- {\endangle}
- {\pgfpoint{\cx+\a*cos(\endangle)}{\cy+\b*sin(\endangle)}}% end point
- {\a}
- {\b}
- {\abratio}
- {\baratio}
- \pgfusepath{draw}
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{command}{\pgfpatharctomaxstepsize}
- The quality of arc approximation taken by |\pgfpatharctoprecomputed| by
- means of Bézier splines is controlled by a mesh width, which is
- initially
-
- |\def\pgfpatharctoprecomputed{45}|.
-
- The mesh width is provided in (full!) degrees. The smaller the mesh
- width, the more precise the arc approximation.
-
- Use an empty value to disable spline approximation (uses a single cubic
- polynomial for the complete arc).
-
- The value must be an integer!
- \end{command}
-\end{command}
-
-\begin{command}{\pgfpathellipse\marg{center}\marg{first axis}\marg{second axis}}
- The effect of this command is to append an ellipse to the current path (if
- the path is not empty, a new part is started). The ellipse's center will be
- \meta{center} and \meta{first axis} and \meta{second axis} are the axis
- \emph{vectors}. The same effect as this command can also be achieved using
- an appropriate sequence of move-to, arc, and close operations, but this
- command is easier and faster.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathellipse{\pgfpoint{1cm}{0cm}}
- {\pgfpoint{1.5cm}{0cm}}
- {\pgfpoint{0cm}{1cm}}
- \pgfusepath{draw}
- \color{red}
- \pgfpathellipse{\pgfpoint{1cm}{0cm}}
- {\pgfpoint{1cm}{1cm}}
- {\pgfpoint{-0.5cm}{0.5cm}}
- \pgfusepath{draw}
-\end{tikzpicture}
-\end{codeexample}
-
- The command will apply coordinate transformations to all coordinates of the
- ellipse. However, the coordinate transformations are applied only after the
- ellipse is ``finished conceptually''. Thus, a transformation of 1cm to the
- right will simply shift the ellipse one centimeter to the right; it will
- not add 1cm to the $x$-coordinates of the two axis vectors.
-
- The command will update the bounding box of the current path and picture,
- if necessary.
-\end{command}
-
-\begin{command}{\pgfpathcircle\marg{center}\marg{radius}}
- A shorthand for |\pgfpathellipse| applied to \meta{center} and the two axis
- vectors $(\meta{radius},0)$ and $(0,\meta{radius})$.
-\end{command}
-
-
-\subsection{Rectangle Path Operations}
-
-Another shape that arises frequently is the rectangle. Two commands can be used
-to add a rectangle to the current path. Both commands will start a new part of
-the path.
-
-\begin{command}{\pgfpathrectangle\marg{corner}\marg{diagonal vector}}
- Adds a rectangle to the path whose one corner is \meta{corner} and whose
- opposite corner is given by $\meta{corner} + \meta{diagonal vector}$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathrectangle{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}}
- \pgfpathrectangle{\pgfpoint{1.5cm}{0.25cm}}{\pgfpoint{1.5cm}{1cm}}
- \pgfpathrectangle{\pgfpoint{2cm}{0.5cm}}{\pgfpoint{1.5cm}{1cm}}
- \pgfusepath{draw}
-\end{tikzpicture}
-\end{codeexample}
- %
- The command will apply coordinate transformations and update the bounding
- boxes tightly.
-\end{command}
-
-\begin{command}{\pgfpathrectanglecorners\marg{corner}\marg{opposite corner}}
- Adds a rectangle to the path whose two opposing corners are \meta{corner}
- and \meta{opposite corner}.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathrectanglecorners{\pgfpoint{1cm}{0cm}}{\pgfpoint{1.5cm}{1cm}}
- \pgfusepath{draw}
-\end{tikzpicture}
-\end{codeexample}
- %
- The command will apply coordinate transformations and update the bounding
- boxes tightly.
-\end{command}
-
-
-\subsection{The Grid Path Operation}
-
-\begin{command}{\pgfpathgrid\oarg{options}\marg{first corner}\marg{second corner}}
- Appends a grid to the current path. That is, a (possibly large) number of
- parts are added to the path, each part consisting of a single horizontal or
- vertical straight line segment.
-
- Conceptually, the origin is part of the grid and the grid is clipped to the
- rectangle specified by the \meta{first corner} and the \meta{second
- corner}. However, no clipping occurs (this command just adds parts to the
- current path) and the points where the lines enter and leave the ``clipping
- area'' are computed and used to add simple lines to the current path.
-
- The following keys influence the grid:
- %
- \begin{key}{/pgf/stepx=\meta{dimension} (initially 1cm)}
- The horizontal stepping.
- \end{key}
- %
- \begin{key}{/pgf/stepy=\meta{dimension} (initially 1cm)}
- The vertical stepping.
- \end{key}
- %
- \begin{key}{/pgf/step=\meta{vector}}
- Sets the horizontal stepping to the $x$-coordinate of \meta{vector} and
- the vertical stepping to its $y$-coordinate.
- \end{key}
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfsetlinewidth{0.8pt}
- \pgfpathgrid[step={\pgfpoint{1cm}{1cm}}]
- {\pgfpoint{-3mm}{-3mm}}{\pgfpoint{33mm}{23mm}}
- \pgfusepath{stroke}
- \pgfsetlinewidth{0.4pt}
- \pgfpathgrid[stepx=1mm,stepy=1mm]
- {\pgfpoint{-1.5mm}{-1.5mm}}{\pgfpoint{31.5mm}{21.5mm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
- The command will apply coordinate transformations and update the bounding
- boxes. As for ellipses, the transformations are applied to the
- ``conceptually finished'' grid.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgftransformrotate{10}
- \pgfpathgrid[stepx=1mm,stepy=2mm]{\pgfpoint{0mm}{0mm}}{\pgfpoint{30mm}{30mm}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{The Parabola Path Operation}
-
-\begin{command}{\pgfpathparabola\marg{bend vector}\marg{end vector}}
- This command appends two half-parabolas to the current path. The first
- starts at the current point and ends at the current point plus \meta{bend
- vector}. At this point, it has its bend. The second half parabola starts at
- that bend point and ends at point that is given by the bend plus \meta{end
- vector}.
-
- If you set \meta{end vector} to the null vector, you append only a half
- parabola that goes from the current point to the bend; by setting
- \meta{bend vector} to the null vector, you append only a half parabola that
- goes through the current point and \meta{end vector} and has its bend at
- the current point.
-
- It is not possible to use this command to draw a part of a parabola that
- does not contain the bend.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- % Half-parabola going ``up and right''
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathparabola{\pgfpointorigin}{\pgfpoint{2cm}{4cm}}
- \color{red}
- \pgfusepath{stroke}
-
- % Half-parabola going ``down and right''
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathparabola{\pgfpoint{-2cm}{4cm}}{\pgfpointorigin}
- \color{blue}
- \pgfusepath{stroke}
-
- % Full parabola
- \pgfpathmoveto{\pgfpoint{-2cm}{2cm}}
- \pgfpathparabola{\pgfpoint{1cm}{-1cm}}{\pgfpoint{2cm}{4cm}}
- \color{orange}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
- The command will apply coordinate transformations and update the bounding
- boxes.
-\end{command}
-
-
-\subsection{Sine and Cosine Path Operations}
-
-Sine and cosine curves often need to be drawn and the following commands may
-help with this. However, they only allow you to append sine and cosine curves
-in intervals that are multiples of $\pi/2$.
-
-\begin{command}{\pgfpathsine\marg{vector}}
- This command appends a sine curve in the interval $[0,\pi/2]$ to the
- current path. The sine curve is squeezed or stretched such that the curve
- starts at the current point and ends at the current point plus
- \meta{vector}.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,1);
- \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
- \pgfpathsine{\pgfpoint{1cm}{1cm}}
- \pgfusepath{stroke}
-
- \color{red}
- \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
- \pgfpathsine{\pgfpoint{-2cm}{-2cm}}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
- The command will apply coordinate transformations and update the bounding
- boxes.
-\end{command}
-
-\begin{command}{\pgfpathcosine\marg{vector}}
- This command appends a cosine curve in the interval $[0,\pi/2]$ to the
- current path. The curve is squeezed or stretched such that the curve starts
- at the current point and ends at the current point plus \meta{vector}.
- Using several sine and cosine operations in sequence allows you to produce
- a complete sine or cosine curve
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpoint{0cm}{0cm}}
- \pgfpathsine{\pgfpoint{1cm}{1cm}}
- \pgfpathcosine{\pgfpoint{1cm}{-1cm}}
- \pgfpathsine{\pgfpoint{1cm}{-1cm}}
- \pgfpathcosine{\pgfpoint{1cm}{1cm}}
- \pgfsetfillcolor{yellow!80!black}
- \pgfusepath{fill,stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
- The command will apply coordinate transformations and update the bounding
- boxes.
-\end{command}
-
-
-\subsection{Plot Path Operations}
-
-There exist several commands for appending plots to a path. These commands are
-available through the module |plot|. They are documented in
-Section~\ref{section-plots}.
-
-
-\subsection{Rounded Corners}
-
-Normally, when you connect two straight line segments or when you connect two
-curves that end and start ``at different angles'', you get ``sharp corners''
-between the lines or curves. In some cases it is desirable to produce ``rounded
-corners'' instead. Thus, the lines or curves should be shortened a bit and then
-connected by arcs.
-
-\pgfname\ offers an easy way to achieve this effect, by calling the following
-two commands.
-
-\begin{command}{\pgfsetcornersarced\marg{point}}
- This command causes all subsequent corners to be replaced by little
- arcs. The effect of this command lasts till the end of the current
- \TeX\ scope.
-
- The \meta{point} dictates how large the corner arc will be. Consider a
- corner made by two lines $l$ and~$r$ and assume that the line $l$ comes
- first on the path. The $x$-dimension of the \meta{point} decides by how
- much the line~$l$ will be shortened, the $y$-dimension of \meta{point}
- decides by how much the line $r$ will be shortened. Then, the shortened
- lines are connected by an arc.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \pgfsetcornersarced{\pgfpoint{5mm}{5mm}}
- \pgfpathrectanglecorners{\pgfpointorigin}{\pgfpoint{3cm}{2cm}}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \pgfsetcornersarced{\pgfpoint{10mm}{5mm}}
- % 10mm entering,
- % 5mm leaving.
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{0cm}{2cm}}
- \pgfpathlineto{\pgfpoint{3cm}{2cm}}
- \pgfpathcurveto
- {\pgfpoint{3cm}{0cm}}
- {\pgfpoint{2cm}{0cm}}
- {\pgfpoint{1cm}{0cm}}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
-
- If the $x$- and $y$-coordinates of \meta{point} are the same and the corner
- is a right angle, you will get a perfect quarter circle (well, not quite
- perfect, but perfect up to six decimals). When the angle is not $90^\circ$,
- you only get a fair approximation.
-
- More or less ``all'' corners will be rounded, even the corner generated by
- a |\pgfpathclose| command. (The author is a bit proud of this feature.)
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfsetcornersarced{\pgfpoint{4pt}{4pt}}
- \pgfpathmoveto{\pgfpointpolar{0}{1cm}}
- \pgfpathlineto{\pgfpointpolar{72}{1cm}}
- \pgfpathlineto{\pgfpointpolar{144}{1cm}}
- \pgfpathlineto{\pgfpointpolar{216}{1cm}}
- \pgfpathlineto{\pgfpointpolar{288}{1cm}}
- \pgfpathclose
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
-
- To return to normal (unrounded) corners, use
- |\pgfsetcornersarced{\pgfpointorigin}|.
-
- Note that the rounding will produce strange and undesirable effects if the
- lines at the corners are too short. In this case the shortening may cause
- the lines to ``suddenly extend over the other end'' which is rarely
- desirable.
-\end{command}
-
-
-\subsection{Internal Tracking of Bounding Boxes for Paths and Pictures}
-\label{section-bb}
-
-\makeatletter
-
-The path construction commands keep track of two bounding boxes: One for the
-current path, which is reset whenever the path is used and thereby flushed, and
-a bounding box for the current |{pgfpicture}|.
-
-\begin{command}{\pgfresetboundingbox}
- Resets the picture's bounding box. The picture will simply forget any
- previous bounding box updates and start collecting from scratch.
-
- You can use this together with |\pgfusepath{use as bounding box}| to
- replace the bounding box by the one of a particular path (ignoring
- subsequent paths).
-\end{command}
-
-The bounding boxes are not accessible by ``normal'' macros. Rather, two sets of
-four dimension variables are used for this, all of which contain the
-letter~|@|.
-
-\begin{textoken}{\pgf@pathminx}
- The minimum $x$-coordinate ``mentioned'' in the current path. Initially,
- this is set to $16000$pt.
-\end{textoken}
-
-\begin{textoken}{\pgf@pathmaxx}
- The maximum $x$-coordinate ``mentioned'' in the current path. Initially,
- this is set to $-16000$pt.
-\end{textoken}
-
-\begin{textoken}{\pgf@pathminy}
- The minimum $y$-coordinate ``mentioned'' in the current path. Initially,
- this is set to $16000$pt.
-\end{textoken}
-
-\begin{textoken}{\pgf@pathmaxy}
- The maximum $y$-coordinate ``mentioned'' in the current path. Initially,
- this is set to $-16000$pt.
-\end{textoken}
-
-\begin{textoken}{\pgf@picminx}
- The minimum $x$-coordinate ``mentioned'' in the current picture. Initially,
- this is set to $16000$pt.
-\end{textoken}
-
-\begin{textoken}{\pgf@picmaxx}
- The maximum $x$-coordinate ``mentioned'' in the current picture. Initially,
- this is set to $-16000$pt.
-\end{textoken}
-
-\begin{textoken}{\pgf@picminy}
- The minimum $y$-coordinate ``mentioned'' in the current picture. Initially,
- this is set to $16000$pt.
-\end{textoken}
-
-\begin{textoken}{\pgf@picmaxy}
- The maximum $y$-coordinate ``mentioned'' in the current picture. Initially,
- this is set to $-16000$pt.
-\end{textoken}
-
-
-Each time a path construction command is called, the above variables are
-(globally) updated. To facilitate this, you can use the following command:
-
-\begin{command}{\pgf@protocolsizes\marg{x-dimension}\marg{y-dimension}}
- Updates all of the above dimensions in such a way that the point specified
- by the two arguments is inside both bounding boxes. For the picture's
- bounding box this updating occurs only if |\ifpgf@relevantforpicturesize|
- is true, see below.
-\end{command}
-
-For the bounding box of the picture it is not always desirable that every path
-construction command affects this bounding box. For example, if you have just
-used a clip command, you do not want anything outside the clipping area to
-affect the bounding box. For this reason, there exists a special ``\TeX\ if''
-that (locally) decides whether updating should be applied to the picture's
-bounding box. Clipping will set this if to false, as will certain other
-commands.
-
-\begin{command}{\pgf@relevantforpicturesizefalse}
- Suppresses updating of the picture's bounding box.
-\end{command}
-
-\begin{command}{\pgf@relevantforpicturesizetrue}
- Causes updating of the picture's bounding box.
-\end{command}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-patterns.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-patterns.tex
deleted file mode 100644
index f032c5a2ea..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-patterns.tex
+++ /dev/null
@@ -1,261 +0,0 @@
-% 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{Patterns}
-\label{section-patterns}
-
-\subsection{Overview}
-
-There are many ways of filling a path. First, you can fill it using a solid
-color and this is also the fastest method. Second, you can also fill it using a
-shading, which means that the color changes smoothly between two (or more)
-different colors. Third, you can fill it using a tiling pattern and it is
-explained in the following how this is done.
-
-A tiling pattern can be imagined as a rectangular tile (hence the name) on
-which a small picture is painted. There is not a single tile, but
-(conceptually) an infinite number of tiles, all showing the same picture, and
-these tiles are arranged horizontally and vertically to fill the plane. When
-you use a tiling pattern to fill a path, what happens is that the path clips
-out a ``window'' through which we see part of this infinite plane.
-
-Patterns come in two versions: \emph{inherently colored patterns} and
-\emph{form-only patterns}. (These are often called ``color patterns'' and
-``uncolored patterns'', but these names are misleading since uncolored patterns
-do have a color and the color changes. As I said, the name is misleading\dots)
-An inherently colored pattern is just a colored tile like, say, a red star with
-a black outline. A form-only pattern can be imagined as a tile that is a kind
-of rubber stamp. When this pattern is used, the stamp is used to print copies
-of the stamp picture onto the plane, but we can use a different stamp color
-each time we use a form-only pattern.
-
-\pgfname\ provides a special support for patterns. You can declare a pattern
-and then use it very much like a fill color. \pgfname\ directly maps patterns
-to the pattern facilities of the underlying graphic languages (PostScript,
-\textsc{pdf}, and \textsc{svg}). This means that filling a path using a pattern
-will be nearly as fast as if you used a uniform color.
-
-There are a number of pitfalls and restrictions when using patterns. First,
-once a pattern has been declared, you cannot change it anymore. In particular,
-it is not possible to enlarge it or change the line width. Such flexibility
-would require that the repeating of the pattern were not done by the graphic
-language, but on the \pgfname\ level. This would make patterns orders of
-magnitude slower to produce and to render. However, \pgfname{} does provide a
-more-or-less successful emulation of ``mutable'' patterns, although internally,
-a new (fixed) instance of a pattern is declared when the parameters of a
-pattern change.
-
-Second, the phase of patterns is not well-defined, that is, it is not clear
-where the origin of the ``first'' tile is. To be more precise, PostScript and
-\textsc{pdf} on the one hand and \textsc{svg} on the other hand define the
-origin differently. PostScript and \textsc{pdf} define a fixed origin that is
-independent of where the path lies. This has the highly desirable effect that
-if you use the same pattern to fill multiple paths, the outcome is the same as
-if you had filled a single path consisting of the union of all these paths. By
-comparison, \textsc{svg} uses the upper-left (?) corner of the path to be
-filled as the origin. However, the \textsc{svg} specification is a bit vague on
-this question.
-
-
-\subsection{Declaring a Pattern}
-
-Before a pattern can be used, it must be declared. The following command is
-used for this:
-
-\begin{command}{\pgfdeclarepatternformonly%
- \opt{\oarg{variables}}%
- \marg{name}%
- \marg{bottom left}%
- \marg{top right}%
- \marg{tile size}%
- \marg{code}%
-}
- This command declares a new form-only pattern. The \meta{name} is a name
- for later reference. The two parameters \meta{lower left} and \meta{upper
- right} must describe a bounding box that is large enough to encompass the
- complete tile.
-
- The size of a tile is given by \meta{tile size}, that is, a tile is a
- rectangle whose lower left corner is the origin and whose upper right
- corner is given by \meta{tile size}. This might make you wonder why the
- second and third parameters are needed. First, the bounding box might be
- smaller than the tile size if the tile is larger than the picture on the
- tile. Second, the bounding box might be bigger, in which case the picture
- will ``bleed'' over the tile.
-
- The \meta{code} should be \pgfname\ code than can be protocolled. It should
- not contain any color code.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
-\pgfdeclarepatternformonly{stars}
-{\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
-{\pgfpoint{1cm}{1cm}}
-{
- \pgftransformshift{\pgfpoint{.5cm}{.5cm}}
- \pgfpathmoveto{\pgfpointpolar{0}{4mm}}
- \pgfpathlineto{\pgfpointpolar{144}{4mm}}
- \pgfpathlineto{\pgfpointpolar{288}{4mm}}
- \pgfpathlineto{\pgfpointpolar{72}{4mm}}
- \pgfpathlineto{\pgfpointpolar{216}{4mm}}
- \pgfpathclose%
- \pgfusepath{fill}
-}
-\begin{tikzpicture}
- \filldraw[pattern=stars] (0,0) rectangle (1.5,2);
- \filldraw[pattern=stars,pattern color=red]
- (1.5,0) rectangle (3,2);
-\end{tikzpicture}
-\end{codeexample}
-
- The optional argument \meta{variables} consists of a comma separated list
- of macros, registers or keys, representing the parameters of the pattern
- that may vary. If a variable is a key, then the full path name must be used
- (specifically, it must start with |/|). As an example, a list might look
- like the following: |\mymacro,\mydimen,/pgf/my key|. Note that macros and
- keys should be ``simple''. They should only store values in themselves.
-
- The effect of \meta{variables}, is the following: Normally, when this
- argument is empty, once a pattern has been declared, it becomes ``frozen''.
- This means that it is not possible to enlarge the pattern or change the
- line width later on. By specifying \meta{variables}, no pattern is actually
- created. Instead, the arguments are stored away (so the macros, registers
- or keys do not have to be defined in advance).
-
- When the fill pattern is set, \pgfname{} checks if the pattern has already
- been created with the \meta{variables} set to their current values
- (\pgfname{} is usually ``smart enough'' to distinguish between macros,
- registers and keys). If so, this already-declared-pattern is used as the
- fill pattern. If not, a new instance of the pattern (which will have a
- unique internal name) is declared using the current values of
- \meta{variables}. These values are then saved and the fill pattern set
- accordingly.
-
- The following shows an example of a pattern which varies according to the
- values of the macro |\size|, the key |/tikz/radius|, and the \TeX{}
- dimension |\thickness|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
-\pgfdeclarepatternformonly[/tikz/radius,\thickness,\size]{rings}
-{\pgfpoint{-0.5*\size}{-0.5*\size}}
-{\pgfpoint{0.5*\size}{0.5*\size}}
-{\pgfpoint{\size}{\size}}
-{
- \pgfsetlinewidth{\thickness}
- \pgfpathcircle\pgfpointorigin{\pgfkeysvalueof{/tikz/radius}}
- \pgfusepath{stroke}
-}
-\newdimen\thickness
-\tikzset{
- radius/.initial=4pt,
- size/.store in=\size, size=20pt,
- thickness/.code={\thickness=#1},
- thickness=0.75pt
-}
-\begin{tikzpicture}[rings/.style={pattern=rings}]
- \filldraw [rings, radius=2pt, size=6pt] (0,0) rectangle +(1.5,2);
- \filldraw [rings, radius=2pt, size=8pt] (2,0) rectangle +(1.5,2);
- \filldraw [rings, radius=6pt, thickness=2pt] (0,2.5) rectangle +(1.5,2);
- \filldraw [rings, radius=8pt, thickness=4pt] (2,2.5) rectangle +(1.5,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfdeclarepatterninherentlycolored
- \opt{\oarg{variables}}
- \marg{name}
- \marg{lower left}
- \marg{upper right}
- \marg{tile size}
- \marg{code}%
-}
- This command works like |\pgfdeclarepatternuncolored|, only the pattern
- will have an inherent color. To set the color, you should use \pgfname's
- color commands, not the |\color| command, since this fill is not
- protocolled.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
-\pgfdeclarepatterninherentlycolored{green stars}
-{\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
-{\pgfpoint{1cm}{1cm}}
-{
- \pgfsetfillcolor{green!50!black}
- \pgftransformshift{\pgfpoint{.5cm}{.5cm}}
- \pgfpathmoveto{\pgfpointpolar{0}{4mm}}
- \pgfpathlineto{\pgfpointpolar{144}{4mm}}
- \pgfpathlineto{\pgfpointpolar{288}{4mm}}
- \pgfpathlineto{\pgfpointpolar{72}{4mm}}
- \pgfpathlineto{\pgfpointpolar{216}{4mm}}
- \pgfpathclose%
- \pgfusepath{stroke,fill}
-}
-\begin{tikzpicture}
- \filldraw[pattern=green stars] (0,0) rectangle (3,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Setting a Pattern}
-
-Once a pattern has been declared, it can be used.
-
-\begin{command}{\pgfsetfillpattern\marg{name}\marg{color}}
- This command specifies that paths that are filled should be filled with the
- ``color'' by the pattern \meta{name}. For an inherently colored pattern,
- the \meta{color} parameter is ignored. For form-only patterns, the
- \meta{color} parameter specifies the color to be used for the pattern.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{patterns}
-\pgfdeclarepatternformonly{stars}
-{\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
-{\pgfpoint{1cm}{1cm}}
-{
- \pgftransformshift{\pgfpoint{.5cm}{.5cm}}
- \pgfpathmoveto{\pgfpointpolar{0}{4mm}}
- \pgfpathlineto{\pgfpointpolar{144}{4mm}}
- \pgfpathlineto{\pgfpointpolar{288}{4mm}}
- \pgfpathlineto{\pgfpointpolar{72}{4mm}}
- \pgfpathlineto{\pgfpointpolar{216}{4mm}}
- \pgfpathclose%
- \pgfusepath{fill}
-}
-\pgfdeclarepatterninherentlycolored{green stars}
-{\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
-{\pgfpoint{1cm}{1cm}}
-{
- \pgfsetfillcolor{green!50!black}
- \pgftransformshift{\pgfpoint{.5cm}{.5cm}}
- \pgfpathmoveto{\pgfpointpolar{0}{4mm}}
- \pgfpathlineto{\pgfpointpolar{144}{4mm}}
- \pgfpathlineto{\pgfpointpolar{288}{4mm}}
- \pgfpathlineto{\pgfpointpolar{72}{4mm}}
- \pgfpathlineto{\pgfpointpolar{216}{4mm}}
- \pgfpathclose%
- \pgfusepath{stroke,fill}
-}}]
-\begin{tikzpicture}
- \pgfsetfillpattern{stars}{red}
- \filldraw (0,0) rectangle (1.5,2);
-
- \pgfsetfillpattern{green stars}{red}
- \filldraw (1.5,0) rectangle (3,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-plots.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-plots.tex
deleted file mode 100644
index d11922a09b..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-plots.tex
+++ /dev/null
@@ -1,587 +0,0 @@
-% Copyright 2018 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{Creating Plots}
-\label{section-plots}
-
-This section describes the |plot| module.
-
-\begin{pgfmodule}{plot}
- This module provides a set of commands that are intended to make it
- reasonably easy to plot functions using \pgfname. It is loaded
- automatically by |pgf|, but you can load it manually if you have only
- included |pgfcore|.
-\end{pgfmodule}
-
-
-\subsection{Overview}
-
-There are different reasons for using \pgfname\ for creating plots rather than
-some more powerful program such as \textsc{gnuplot} or \textsc{mathematica}, as
-discussed in Section~\ref{section-why-pgname-for-plots}. So, let us assume that
--- for whatever reason -- you wish to use \pgfname\ for generating a plot.
-
-\pgfname\ (conceptually) uses a two-stage process for generating plots. First,
-a \emph{plot stream} must be produced. This stream consists (more or less) of a
-large number of coordinates. Second a \emph{plot handler} is applied to the
-stream. A plot handler ``does something'' with the stream. The standard handler
-will issue line-to operations to the coordinates in the stream. However, a
-handler might also try to issue appropriate curve-to operations in order to
-smooth the curve. A handler may even do something else entirely, like writing
-each coordinate to another stream, thereby duplicating the original stream.
-
-Both for the creation of streams and the handling of streams different sets of
-commands exist. The commands for creating streams start with |\pgfplotstream|,
-the commands for setting the handler start with |\pgfplothandler|.
-
-
-\subsection{Generating Plot Streams}
-
-\subsubsection{Basic Building Blocks of Plot Streams}
-
-A \emph{plot stream} is a (long) sequence of the following commands:
-%
-\begin{enumerate}
- \item |\pgfplotstreamstart|,
- \item |\pgfplotstreampoint|,
- \item |\pgfplotstreampointoutlier|,
- \item |\pgfplotstreampointundefined|,
- \item |\pgfplotstreamnewdataset|,
- \item |\pgfplotstreamspecial|, and
- \item |\pgfplotstreamend|.
-\end{enumerate}
-%
-Between calls of these commands arbitrary other code may be called. Obviously,
-the stream should start with the first command and end with the last command.
-Here is an example of a plot stream:
-%
-\begin{codeexample}[code only]
-\pgfplotstreamstart
-\pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
-\newdimen\mydim
-\mydim=2cm
-\pgfplotstreampoint{\pgfpoint{\mydim}{2cm}}
-\advance \mydim by 3cm
-\pgfplotstreampoint{\pgfpoint{\mydim}{2cm}}
-\pgfplotstreamend
-\end{codeexample}
-
-Streams are \emph{global}, meaning that they are not influenced by \TeX\
-groups.
-
-\begin{command}{\pgfplotstreamstart}
- This command signals that a plot stream starts. The effect of this command
- is to call the internal command |\pgf@plotstreamstart|, which is set by the
- current plot handler to do whatever needs to be done at the beginning of
- the plot. It will also reset the meaning of the internal commands like
- |\pgf@plotstreampoint| to the initial setting for the plot handler (what
- this means will be explained in a moment).
-\end{command}
-
-\begin{command}{\pgfplotstreampoint\marg{point}}
- This command adds a \meta{point} to the current plot stream. The effect of
- this command is to call the internal command |\pgf@plotstreampoint|, which
- is also set by the current plot handler. This command should now ``handle''
- the point in some sensible way. For example, a line-to command might be
- issued for the point.
-
- When a plot handler is installed, it will setup the internal command
- |\pgf@plotstreampoint| in some way. It is permissible to change the meaning
- of this internal command during a stream. For instance, a handler might
- setup |\pgf@plotstreampoint| in some sensible way for the first point and
- then redefine it so that subsequent points are handled in some other way.
-
- As mentioned earlier, the |\pgfplotstreamstart| will always reset the
- definition of the internal command to the initial meaning it had when the
- handler was installed. This is true for the other commands mentioned in the
- following.
-\end{command}
-
-\begin{command}{\pgfplotstreampointoutlier\marg{point}}
- An \emph{outlier} is a point that is ``out of bounds'' in some way. For
- instance, it might have very large coordinates or the coordinates might
- just be outside some specified range. Nevertheless, an outlier is still a
- well-defined point. This command is issued, for instance, by
- \textsc{gnuplot} when a value is outside the specified range.
-
- You can configure how outliers are treated using the following key:
- %
- \begin{key}{/pgf/handle outlier points in plots=\meta{how} (initially jump)}
- \keyalias{tikz}
- You can set \meta{how} to one of the following values:
- %
- \begin{itemize}
- \item |plot| This will cause the outlier to be drawn normally, just
- as if |\pgfplotstreampoint| had been used rather than this
- command.
- \item |ignore| The outlier will be completely ignored, just as if
- the command had not been used at all.
- \item |jump| This causes the internal macro |\pgf@plotstreamjump|
- to be called. A ``jump'' in a stream is a position where a
- ``gap'' is introduced. For instance, a simple line-to plot
- handler will stop the current subpath at a jump position and
- begin with a move-to operation at the next normal point of the
- stream.
-
- The net effect of this setting is that at outlier points plots
- get interrupted and ``restarted'' when the points are no longer
- outliers. This is usually the behavior you will be looking for.
- \end{itemize}
- \end{key}
-\end{command}
-
-\begin{command}{\pgfplotstreampointundefined}
- This command indicated that the stream contains an ``undefined'' point like
- a point where some coordinate results for a division by zero. Such a point
- cannot be plotted, which is why it is not given as a parameter. However,
- such a point \emph{can} result in a jump in the plot, depending on the
- setting of the following key:
- %
- \begin{key}{/pgf/handle undefined points in plots=\meta{how} (initially jump)}
- \keyalias{tikz}
- You can set \meta{how} to one of the following values:
- %
- \begin{itemize}
- \item |ignore| The undefined point will be completely ignored, just
- as if the command had not been used at all.
- \item |jump| This causes the internal macro |\pgf@plotstreamjump|
- to be called.
- \end{itemize}
- \end{key}
-\end{command}
-
-\begin{command}{\pgfplotstreamnewdataset}
- This command indicated that in the stream a ``new data set'' starts. So,
- the stream does not end, but there is a logical break in the data. For
- example, when a table is read from a file, empty lines are interpreted as
- indicating new data sets. What happens when a new data set is encountered
- is governed by the following key:
- %
- \begin{key}{/pgf/handle new data sets in plots=\meta{how} (initially jump)}
- \keyalias{tikz}
- You can set \meta{how} to one of the following values:
- %
- \begin{itemize}
- \item |ignore| The command will be completely ignored, just as if
- the command had not been used at all.
- \item |jump| This causes the internal macro |\pgf@plotstreamjump|
- to be called.
- \end{itemize}
- \end{key}
-\end{command}
-
-\begin{command}{\pgfplotstreamspecial\marg{text}}
- This command causes |\pgf@plotstreamspecial| to be called with \meta{text}
- as its parameter. This allows handler-specific information to be passed to
- the handler. All normal handlers ignore this command.
-\end{command}
-
-\begin{command}{\pgfplotstreamend}
- This command signals that a plot stream ends. It calls
- |\pgf@plotstreamend|, which should now do any necessary ``cleanup''.
-\end{command}
-
-Note that plot streams are not buffered, that is, the different points are
-handled immediately. However, using the recording handler, it is possible to
-record a stream.
-
-
-\subsubsection{Commands That Generate Plot Streams}
-\label{section-plot-jumps}
-
-Plot streams can be created ``by hand'' as in the earlier example. However,
-most of the time the coordinates will be produced internally by some command.
-For example, the |\pgfplotxyfile| reads a file and converts it into a plot
-stream.
-
-\begin{command}{\pgfplotxyfile\marg{filename}}
- This command will try to open the file \meta{filename}. If this succeeds,
- it will convert the file contents into a plot stream as follows: A
- |\pgfplotstreamstart| is issued. Then, for each empty line a
- |\pgfplotstreamnewdataset| is produced. Other lines in the file should
- start with two numbers separated by a space, such as |0.1 1| or |100 -.3|.
- The numbers may be followed by some text, which will be ignore
- \emph{except} if it is exactly ``|u|'' or ``|o|''. For ``|u|'' the point
- is considered to be undefined and |\pgfplotstreampointundefined| is called.
- For ``|o|'' the point is considered to be an outlier and
- |\pgfplotstreampointoutlier| is called. Otherwise, each pair \meta{x} and
- \meta{y} of numbers is converted into one plot stream point in the
- $xy$-coordinate system. Thus, a line like
- %
-\begin{codeexample}[code only, tikz syntax=false]
-0 Nan u
-1 1 some text
-2 4
-3 9
-
-4 16 o
-5 25 oo
-\end{codeexample}
- %
- is turned into
- %
-\begin{codeexample}[code only]
-\pgfplotstreamstart
-\pgfplotstreampointundefined
-\pgfplotstreampoint{\pgfpointxy{1}{1}}
-\pgfplotstreampoint{\pgfpointxy{2}{4}}
-\pgfplotstreampoint{\pgfpointxy{3}{9}}
-\pgfplotstreamnewdataset
-\pgfplotstreampointoutlier{\pgfpointxy{4}{16}}
-\pgfplotstreampoint{\pgfpointxy{5}{25}}
-\pgfplotstreamend
-\end{codeexample}
- %
- (Note that the last line is not an outlier because |oo| is not the same as
- |o|).
-
- The two characters |%| and |#| are also allowed in a file and they are both
- treated as comment characters. Thus, a line starting with either of them is
- treated as empty.
-
- When the file has been read completely, |\pgfplotstreamend| is called.
-\end{command}
-
-\begin{command}{\pgfplotxyzfile\marg{filename}}
- This command works like |\pgfplotxyfile|, only \emph{three} numbers are
- expected on each non-empty line. They are converted into points in the
- $xyz$-coordinate system. Consider, the following file:
- %
-\begin{codeexample}[code only, tikz syntax=false]
-% Some comments
-# more comments
-2 -5 1 first entry
-2 -.2 2 o
-2 -5 2 third entry
-\end{codeexample}
- %
- It is turned into the following stream:
- %
-\begin{codeexample}[code only]
-\pgfplotstreamstart
-\pgfplotstreamnewdataset
-\pgfplotstreamnewdataset
-\pgfplotstreampoint{\pgfpointxyz{2}{-5}{1}}
-\pgfplotstreampointoutlier{\pgfpointxyz{2}{-.2}{2}}
-\pgfplotstreampoint{\pgfpointxyz{2}{-5}{2}}
-\pgfplotstreamend
-\end{codeexample}
- %
-\end{command}
-
-Currently, there is no command that can decide automatically whether the
-$xy$-coordinate system should be used or whether the $xyz$-system should be
-used. However, it would not be terribly difficult to write a ``smart file
-reader'' that parses coordinate files a bit more intelligently.
-
-\begin{command}{\pgfplotfunction\marg{variable}\marg{sample list}\marg{point}}
- This command will produce coordinates by iterating the \meta{variable} over
- all values in \meta{sample list}, which should be a list in the |\foreach|
- syntax. For each value of \meta{variable}, the \meta{point} is evaluated
- and the resulting coordinate is inserted into the plot stream.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[x=3.8cm/360]
- \pgfplothandlerlineto
- \pgfplotfunction{\x}{0,5,...,360}{\pgfpointxy{\x}{sin(\x)+sin(3*\x)}}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[y=3cm/360]
- \pgfplothandlerlineto
- \pgfplotfunction{\y}{0,5,...,360}{\pgfpointxyz{sin(2*\y)}{\y}{cos(2*\y)}}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
-
- Be warned that if the expressions that need to evaluated for each point are
- complex, then this command can be very slow.
-\end{command}
-
-\begin{command}{\pgfplotgnuplot\oarg{prefix}\marg{function}}
- This command will ``try'' to call the \textsc{gnuplot} program to generate
- the coordinates of the \meta{function}. In detail, the following happens:
-
- This command works with two files: \meta{prefix}|.gnuplot| and
- \meta{prefix}|.table|. If the optional argument \meta{prefix} is not
- given, it is set to |\jobname|.
-
- Let us start with the situation where none of these files exists. Then
- \pgfname\ will first generate the file \meta{prefix}|.gnuplot|. In this
- file it writes
- %
-\begin{codeexample}[code only, tikz syntax=false]
-set table "#1.table"; set format "%.5f"
-\end{codeexample}
- %
- where |#1| is replaced by \meta{prefix}. Then, in a second line, it writes
- the text \meta{function}.
-
- Next, \pgfname\ will try to invoke the program |gnuplot| with the argument
- \meta{prefix}|.gnuplot|. This call may or may not succeed, depending on
- whether the |\write18| mechanism (also known as shell escape) is switched
- on and whether the |gnuplot| program is available.
-
- Assuming that the call succeeded, the next step is to invoke
- |\pgfplotxyfile| on the file \meta{prefix}|.table|; which is exactly the
- file that has just been created by |gnuplot|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,-1) grid (4,1);
- \pgfplothandlerlineto
- \pgfplotgnuplot[plots/pgfplotgnuplot-example]{plot [x=0:3.5] x*sin(x)}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
-
- The more difficult situation arises when the |.gnuplot| file exists, which
- will be the case on the second run of \TeX\ on the \TeX\ file. In this case
- \pgfname\ will read this file and check whether it contains exactly what
- \pgfname\ ``would have written'' into this file. If this is not the case,
- the file contents is overwritten with what ``should be there'' and, as
- above, |gnuplot| is invoked to generate a new |.table| file. However, if
- the file contents is ``as expected'', the external |gnuplot| program is
- \emph{not} called. Instead, the \meta{prefix}|.table| file is immediately
- read.
-
- As explained in Section~\ref{section-tikz-gnuplot}, the net effect of the
- above mechanism is that |gnuplot| is called as seldom as possible and that
- when you pass along the |.gnuplot| and |.table| files with your |.tex| file
- to someone else, that person can \TeX\ the |.tex| file without having
- |gnuplot| installed and without having the |\write18| mechanism switched
- on.
-
- \begin{key}{/pgf/plot/gnuplot call=\meta{gnuplot invocation} (initially gnuplot)}
- This key can be used to change the way gnuplot is called.
-
- Some portable MiK\TeX{} distribution needs something like the
- following.
- %
-\begin{codeexample}[code only]
- \pgfkeys{/pgf/plot/gnuplot call="/Programs/gnuplot/binary/gnuplot"}
-\end{codeexample}
- \end{key}
-\end{command}
-
-
-\subsection{Plot Handlers}
-\label{section-plot-handlers}
-
-A \emph{plot handler} determines what ``should be done'' with a plot stream.
-You must set the plot handler before the stream starts. The following commands
-install the most basic plot handlers; more plot handlers are defined in the
-file |pgflibraryplothandlers|, which is documented in
-Section~\ref{section-library-plothandlers}.
-
-All plot handlers work by setting or redefining the following three macros:
-|\pgf@plotstreamstart|, |\pgf@plotstreampoint|, and |\pgf@plotstreamend|.
-
-\begin{command}{\pgfplothandlerlineto}
- This handler will issue a |\pgfpathlineto| command for each point of the
- plot, \emph{except} possibly for the first. What happens with the first
- point can be specified using the two commands described below.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfplothandlerlineto
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{1cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{3cm}{2cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{2cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetmovetofirstplotpoint}
- Specifies that the line-to plot handler (and also some other plot handlers)
- should issue a move-to command for the first point of the plot instead of a
- line-to. This will start a new part of the current path, which is not
- always, but often, desirable. This is the default.
-\end{command}
-
-\begin{command}{\pgfsetlinetofirstplotpoint}
- Specifies that plot handlers should issue a line-to command for the first
- point of the plot.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfsetlinetofirstplotpoint
- \pgfplothandlerlineto
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{1cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{3cm}{2cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{2cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfplothandlerpolygon}
- This handler works like the line-to plot handler, only the line is closed
- at the end using |\pgfpathclose|, resulting in a polygon.
-\end{command}
-
-\begin{command}{\pgfplothandlerdiscard}
- This handler will simply throw away the stream.
-\end{command}
-
-\begin{command}{\pgfplothandlerrecord\marg{macro}}
- When this handler is installed, each time a plot stream command is called,
- this command will be appended to \meta{macro}. Thus, at the end of the
- stream, \meta{macro} will contain all the commands that were issued on the
- stream. You can then install another handler and invoke \meta{macro} to
- ``replay'' the stream (possibly many times).
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfplothandlerrecord{\mystream}
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{1cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{3cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{2cm}}
- \pgfplotstreamend
- \pgfplothandlerlineto
- \mystream
- \pgfplothandlerclosedcurve
- \mystream
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Defining New Plot Handlers}
-
-You can define new plot handlers using the following command:
-
-\begin{command}{\pgfdeclareplothandler\marg{macro}\marg{arguments}\marg{configuration}}
- This command creates a new plot handler that can subsequently be called
- using the macro \meta{macro}. This macro take the arguments given in
- \meta{arguments}, which can be a list like |#1#2| if \meta{macro} should be
- invoked with two arguments. Here is a typical example:
- %
-\begin{codeexample}[code only]
-\pgfdeclareplothandler{\myhandler}{#1}{...}
-...
-\myhandler{foo}
-\pgfplotstreamstart
-...
-\pgfplotstreamend
-\end{codeexample}
-
- The \meta{configuration} is used to define the behavior of the handler. It
- is a list of key--value pairs, where the following keys are allowed:
- %
- \begin{itemize}
- \item |start=|\meta{code}. The \meta{code} will be executed whenever
- |\pgfplotstreamstart| is used while the handler \meta{macro} is
- selected. Inside the \meta{code}, you can use |#1|, |#2|, and so on
- to refer to the parameters that were given to \meta{macro}:
- %
-\begin{codeexample}[width=6cm]
-\pgfdeclareplothandler{\myhandler}{#1}{
- start = Hi #1.,
- end = Bye #1.,
-}
-\myhandler{foo}
-\pgfplotstreamstart
-\pgfplotstreamend
-\myhandler{bar}
-\pgfplotstreamstart
-\pgfplotstreamend
-\end{codeexample}
- %
- \item |end=|\meta{code} Works just like |start|.
- \item |point=|\meta{code}. The \meta{code} will be executed whenever
- |\pgfplotstreampoint| is used while the handler \meta{macro} is in
- force. Inside the \meta{code}, you can use |#1|, |#2|, and so on to
- refer to the arguments give to \meta{macro}, while you can use
- |##1| to refer to the argument given to |\pgfplotstreampoint|
- itself (this will be the coordinate).
- %
-\begin{codeexample}[]
-\pgfdeclareplothandler{\myhandler}{#1}{
- point=\pgfpathcircle{##1}{#1} % ##1 is the coordinate,
- % #1 the parameter for \myhandler
-}
-\begin{pgfpicture}
- \myhandler{1pt}
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0pt}{0pt}}
- \pgfplotstreampoint{\pgfpoint{3pt}{3pt}}
- \pgfplotstreampoint{\pgfpoint{6pt}{3pt}}
- \pgfplotstreampoint{\pgfpoint{9pt}{0pt}}
- \pgfplotstreamend
- \pgfusepath{stroke}
- \myhandler{3pt}
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0pt}{0pt}}
- \pgfplotstreampoint{\pgfpoint{9pt}{0pt}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
- The \meta{code} will also be called for
- |\pgfplotstreampointoutlier| when this command has been configured
- to |plot| the outliers.
- \item |jump=|\meta{code} The \meta{code} will be called whenever a jump
- has been requested indirectly via an outlier point, and undefined
- point, or a new data set (for each of which the command needs to be
- configured to |jump|). As always, inside the \meta{code} you can
- access |#1| and so on.
- \item |special=|\meta{code} Causes \meta{code} to be executed whenever
- |\pgfplotstreamspecial|\marg{something} is used. Inside the
- \meta{code}, you can access \meta{something} via |##1| and the
- parameters of \meta{macro} as |#1|, |#2|, and so on.
- \end{itemize}
-
- In addition to the above keys, there exist also ``code macro versions'' of
- them:
- %
- \begin{itemize}
- \item |point macro=|\meta{some macro}. Causes |\pgfplotstreampoint| to
- call \meta{some macro} directly (actually, |\pgf@plotstreampoint|
- is set to be equal to \meta{some macro}). Inside the \meta{some
- macro} you can use |#1| to access the coordinate passed to
- |\pgfplotstreampoint| and you can no longer access the parameters
- passed to the original call to \meta{macro} that installed the
- handler. So, \meta{some macro} must take exactly one argument,
- namely |#1|.
- \item |special macro=|\meta{some macro}. As |point macro|, only for
- specials.
- \item |start macro=|\meta{some macro}. Causes \meta{some macro} to be
- executed at the start. This macro, like the below ones, may not
- take any parameters and will not have access to the parameters
- passed to the original \meta{macro}.
- \item |end macro=|\meta{some macro}. As above.
- \item |jump macro=|\meta{some macro}. As above.
- \end{itemize}
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-points.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-points.tex
deleted file mode 100644
index 2f4b963dc4..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-points.tex
+++ /dev/null
@@ -1,683 +0,0 @@
-% 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{Specifying Coordinates}
-\label{section-points}
-
-\subsection{Overview}
-
-Most \pgfname\ commands expect you to provide the coordinates of a \emph{point}
-(also called \emph{coordinate}) inside your picture. Points are always
-``local'' to your picture, that is, they never refer to an absolute position on
-the page, but to a position inside the current |{pgfpicture}| environment. To
-specify a coordinate you can use commands that start with |\pgfpoint|.
-
-
-\subsection{Basic Coordinate Commands}
-
-The following commands are the most basic for specifying a coordinate.
-
-\begin{command}{\pgfpoint\marg{x coordinate}\marg{y coordinate}}
- Yields a point location. The coordinates are given as \TeX\ dimensions.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathcircle{\pgfpoint{1cm}{1cm}} {2pt}
- \pgfpathcircle{\pgfpoint{2cm}{5pt}} {2pt}
- \pgfpathcircle{\pgfpoint{0pt}{.5in}}{2pt}
- \pgfusepath{fill}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpointorigin}
- Yields the origin. Same as |\pgfpoint{0pt}{0pt}|.
-\end{command}
-
-\begin{command}{\pgfpointpolar\marg{degree}{\ttfamily\char`\{}\meta{radius}\opt{|/|\meta{y-radius}}{\ttfamily\char`\}}}
- Yields a point location given in polar coordinates. You can specify the
- angle only in degrees, radians are not supported, currently.
-
- If the optional \meta{y-radius} is given, the polar coordinate is actually
- a coordinate on an ellipse whose $x$-radius is given by \meta{radius} and
- whose $y$-radius is given by \meta{y-radius}.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \foreach \angle in {0,10,...,90}
- {\pgfpathcircle{\pgfpointpolar{\angle}{1cm}}{2pt}}
- \pgfusepath{fill}
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \foreach \angle in {0,10,...,90}
- {\pgfpathcircle{\pgfpointpolar{\angle}{1cm and 2cm}}{2pt}}
- \pgfusepath{fill}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Coordinates in the XY-Coordinate System}
-
-Coordinates can also be specified as multiples of an $x$-vector and a
-$y$-vector. Normally, the $x$-vector points one centimeter in the $x$-direction
-and the $y$-vector points one centimeter in the $y$-direction, but using the
-commands |\pgfsetxvec| and |\pgfsetyvec| they can be changed. Note that the
-$x$- and $y$-vector do not necessarily point ``horizontally'' and
-``vertically''.
-
-\begin{command}{\pgfpointxy\marg{$s_x$}\marg{$s_y$}}
- Yields a point that is situated at $s_x$ times the $x$-vector plus $s_y$
- times the $y$-vector.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathmoveto{\pgfpointxy{1}{0}}
- \pgfpathlineto{\pgfpointxy{2}{2}}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetxvec\marg{point}}
- Sets that current $x$-vector for usage in the $xyz$-coordinate system.
- \example
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \pgfpathmoveto{\pgfpointxy{1}{0}}
- \pgfpathlineto{\pgfpointxy{2}{2}}
- \pgfusepath{stroke}
-
- \color{red}
- \pgfsetxvec{\pgfpoint{0.75cm}{0cm}}
- \pgfpathmoveto{\pgfpointxy{1}{0}}
- \pgfpathlineto{\pgfpointxy{2}{2}}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetyvec\marg{point}}
- Works like |\pgfsetxvec|.
-\end{command}
-
-\begin{command}{\pgfpointpolarxy\marg{degree}{\ttfamily\char`\{}\meta{radius}\opt{|/|\meta{y-radius}}{\ttfamily\char`\}}}
- This command is similar to the |\pgfpointpolar| command, but the
- \meta{radius} is now a factor to be interpreted in the $xy$-coordinate
- system. This means that a degree of |0| is the same as the $x$-vector of
- the $xy$-coordinate system times \meta{radius} and a degree of |90| is the
- $y$-vector times \meta{radius}. As for |\pgfpointpolar|, a \meta{radius}
- can also be a pair separated by a slash. In this case, the $x$- and
- $y$-vectors are multiplied by different factors.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \begin{scope}[x={(1cm,-5mm)},y=1.5cm]
- \foreach \angle in {0,10,...,90}
- {\pgfpathcircle{\pgfpointpolarxy{\angle}{1}}{2pt}}
- \pgfusepath{fill}
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Three Dimensional Coordinates}
-
-It is also possible to specify a point as a multiple of three vectors, the
-$x$-, $y$-, and $z$-vector. This is useful for creating simple three
-dimensional graphics.
-
-\begin{command}{\pgfpointxyz\marg{$s_x$}\marg{$s_y$}\marg{$s_z$}}
- Yields a point that is situated at $s_x$ times the $x$-vector plus $s_y$
- times the $y$-vector plus $s_z$ times the $z$-vector.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfsetarrowsend{to}
-
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpointxyz{0}{0}{1}}
- \pgfusepath{stroke}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpointxyz{0}{1}{0}}
- \pgfusepath{stroke}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpointxyz{1}{0}{0}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetzvec\marg{point}}
- Works like |\pgfsetxvec|.
-\end{command}
-
-Inside the $xyz$-coordinate system, you can also specify points using spherical
-and cylindrical coordinates.
-
-\begin{command}{\pgfpointcylindrical\marg{degree}\marg{radius}\marg{height}}
- This command yields the same as
- %
-\begin{verbatim}
-\pgfpointadd{\pgfpointpolarxy{degree}{radius}}{\pgfpointxyz{0}{0}{height}}
-\end{verbatim}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw [->] (0,0) -- (1,0,0) node [right] {$x$};
- \draw [->] (0,0) -- (0,1,0) node [above] {$y$};
- \draw [->] (0,0) -- (0,0,1) node [below left] {$z$};
-
- \pgfpathcircle{\pgfpointcylindrical{80}{1}{.5}}{2pt}
- \pgfusepath{fill}
-
- \draw[red] (0,0) -- (0,0,.5) -- +(80:1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpointspherical\marg{longitude}\marg{latitude}\marg{radius}}
- This command yields a point ``on the surface of the earth'' specified by
- the \meta{longitude} and the \meta{latitude}. The radius of the earth is
- given by \meta{radius}. The equator lies in the $xy$-plane.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \pgfsetfillcolor{lightgray}
-
- \foreach \latitude in {-90,-75,...,30}
- {
- \foreach \longitude in {0,20,...,360}
- {
- \pgfpathmoveto{\pgfpointspherical{\longitude}{\latitude}{1}}
- \pgfpathlineto{\pgfpointspherical{\longitude+20}{\latitude}{1}}
- \pgfpathlineto{\pgfpointspherical{\longitude+20}{\latitude+15}{1}}
- \pgfpathlineto{\pgfpointspherical{\longitude}{\latitude+15}{1}}
- \pgfpathclose
- }
- \pgfusepath{fill,stroke}
- }
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Building Coordinates From Other Coordinates}
-
-Many commands allow you to construct a coordinate in terms of other
-coordinates.
-
-
-\subsubsection{Basic Manipulations of Coordinates}
-
-\begin{command}{\pgfpointadd\marg{$v_1$}\marg{$v_2$}}
- Returns the sum vector $\meta{$v_1$} + \meta{$v_2$}$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathcircle{\pgfpointadd{\pgfpoint{1cm}{0cm}}{\pgfpoint{1cm}{1cm}}}{2pt}
- \pgfusepath{fill}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpointscale\marg{factor}\marg{coordinate}}
- Returns the vector $\meta{factor}\meta{coordinate}$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathcircle{\pgfpointscale{1.5}{\pgfpoint{1cm}{0cm}}}{2pt}
- \pgfusepath{fill}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpointdiff\marg{start}\marg{end}}
- Returns the difference vector $\meta{end} - \meta{start}$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathcircle{\pgfpointdiff{\pgfpoint{1cm}{0cm}}{\pgfpoint{1cm}{1cm}}}{2pt}
- \pgfusepath{fill}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpointnormalised\marg{point}}
- This command returns a normalised version of \meta{point}, that is, a
- vector of length 1pt pointing in the direction of \meta{point}. If
- \meta{point} is the $0$-vector or extremely short, a vector of length 1pt
- pointing upwards is returned.
-
- This command is \emph{not} implemented by calculating the length of the
- vector, but rather by calculating the angle of the vector and then using
- (something equivalent to) the |\pgfpointpolar| command. This ensures that
- the point will really have length 1pt, but it is not guaranteed that the
- vector will \emph{precisely} point in the direction of \meta{point} due to
- the fact that the polar tables are accurate only up to one degree.
- Normally, this is not a problem.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathcircle{\pgfpoint{2cm}{1cm}}{2pt}
- \pgfpathcircle{\pgfpointscale{20}
- {\pgfpointnormalised{\pgfpoint{2cm}{1cm}}}}{2pt}
- \pgfusepath{fill}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Points Traveling along Lines and Curves}
-\label{section-pointsattime}
-
-The commands in this section allow you to specify points on a line or a curve.
-Imagine a point ``traveling'' along a curve from some point $p$ to another
-point $q$. At time $t=0$ the point is at $p$ and at time $t=1$ it is at $q$ and
-at time, say, $t=1/2$ it is ``somewhere in the middle''. The exact location at
-time $t=1/2$ will not necessarily be the ``halfway point'', that is, the point
-whose distance on the curve from $p$ and $q$ is equal. Rather, the exact
-location will depend on the ``speed'' at which the point is traveling, which in
-turn depends on the lengths of the support vectors in a complicated manner. If
-you are interested in the details, please see a good book on Bézier curves.
-
-\begin{command}{\pgfpointlineattime\marg{time $t$}\marg{point $p$}\marg{point $q$}}
- Yields a point that is the $t$th fraction between $p$ and~$q$, that is, $p
- + t(q-p)$. For $t=1/2$ this is the middle of $p$ and $q$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{2cm}{2cm}}
- \pgfusepath{stroke}
- \foreach \t in {0,0.25,...,1.25}
- {\pgftext[at=
- \pgfpointlineattime{\t}{\pgfpointorigin}{\pgfpoint{2cm}{2cm}}]{\t}}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpointlineatdistance\marg{distance}\marg{start point}\marg{end point}}
- Yields a point that is located \meta{distance} many units away from the
- start point in the direction of the end point. In other words, this is the
- point that results if we travel \meta{distance} steps from \meta{start
- point} towards \meta{end point}.
- %
- \example
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{3cm}{2cm}}
- \pgfusepath{stroke}
- \foreach \d in {0pt,20pt,40pt,70pt}
- {\pgftext[at=
- \pgfpointlineatdistance{\d}{\pgfpointorigin}{\pgfpoint{3cm}{2cm}}]{\d}}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpointarcaxesattime\marg{time $t$}\marg{center}\marg{0-degree axis}\marg{90-degree axis}\marg{start angle}\\\marg{end angle}}
- Yields a point on the arc between \meta{start angle} and \meta{end angle}
- on an ellipse whose center is at \meta{center} and whose two principal axes
- are \meta{0-degree axis} and \meta{90-degree axis}. For $t=0$ the point at
- the \meta{start angle} is returned and for $t=1$ the point at the \meta{end
- angle}.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathmoveto{\pgfpoint{2cm}{1cm}}
- \pgfpatharcaxes{0}{60}{\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}}
- \pgfusepath{stroke}
- \foreach \t in {0,0.25,0.5,0.75,1}
- {\pgftext[at=\pgfpointarcaxesattime{\t}{\pgfpoint{0cm}{1cm}}
- {\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}}{0}{60}]{\t}}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpointcurveattime\marg{time $t$}\marg{point $p$}\marg{point $s_1$}\marg{point $s_2$}\marg{point $q$}}
- Yields a point that is on the Bézier curve from $p$ to $q$ with the support
- points $s_1$ and $s_2$. The time $t$ is used to determine the location,
- where $t=0$ yields $p$ and $t=1$ yields $q$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathcurveto
- {\pgfpoint{0cm}{2cm}}{\pgfpoint{0cm}{2cm}}{\pgfpoint{3cm}{2cm}}
- \pgfusepath{stroke}
- \foreach \t in {0,0.25,0.5,0.75,1}
- {\pgftext[at=\pgfpointcurveattime{\t}{\pgfpointorigin}
- {\pgfpoint{0cm}{2cm}}
- {\pgfpoint{0cm}{2cm}}
- {\pgfpoint{3cm}{2cm}}]{\t}}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Points on Borders of Objects}
-
-The following commands are useful for specifying a point that lies on the
-border of special shapes. They are used, for example, by the shape mechanism to
-determine border points of shapes.
-
-\begin{command}{\pgfpointborderrectangle\marg{direction point}\marg{corner}}
- This command returns a point that lies on the intersection of a line
- starting at the origin and going towards the point \meta{direction point}
- and a rectangle whose center is in the origin and whose upper right corner
- is at \meta{corner}.
-
- The \meta{direction point} should have length ``about 1pt'', but it will be
- normalized automatically. Nevertheless, the ``nearer'' the length is to
- 1pt, the less rounding errors.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (2,1.5);
- \pgfpathrectanglecorners{\pgfpoint{-1cm}{-1.25cm}}{\pgfpoint{1cm}{1.25cm}}
- \pgfusepath{stroke}
-
- \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt}
- \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt}
- \pgfusepath{fill}
- \color{red}
- \pgfpathcircle{\pgfpointborderrectangle
- {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt}
- \pgfpathcircle{\pgfpointborderrectangle
- {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt}
- \pgfusepath{fill}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpointborderellipse\marg{direction point}\marg{corner}}
- This command works like the corresponding command for rectangles, only this
- time the \meta{corner} is the corner of the bounding rectangle of an
- ellipse.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (2,1.5);
- \pgfpathellipse{\pgfpointorigin}{\pgfpoint{1cm}{0cm}}{\pgfpoint{0cm}{1.25cm}}
- \pgfusepath{stroke}
-
- \pgfpathcircle{\pgfpoint{5pt}{5pt}}{2pt}
- \pgfpathcircle{\pgfpoint{-10pt}{5pt}}{2pt}
- \pgfusepath{fill}
- \color{red}
- \pgfpathcircle{\pgfpointborderellipse
- {\pgfpoint{5pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt}
- \pgfpathcircle{\pgfpointborderellipse
- {\pgfpoint{-10pt}{5pt}}{\pgfpoint{1cm}{1.25cm}}}{2pt}
- \pgfusepath{fill}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Points on the Intersection of Lines}
-
-\begin{command}{\pgfpointintersectionoflines\marg{$p$}\marg{$q$}\marg{$s$}\marg{$t$}}
- This command returns the intersection of a line going through $p$ and $q$
- and a line going through $s$ and $t$. If the lines do not intersection, an
- arithmetic overflow will occur.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (2,2);
- \draw (.5,0) -- (2,2);
- \draw (1,2) -- (2,0);
- \pgfpathcircle{%
- \pgfpointintersectionoflines
- {\pgfpointxy{.5}{0}}{\pgfpointxy{2}{2}}
- {\pgfpointxy{1}{2}}{\pgfpointxy{2}{0}}}
- {2pt}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Points on the Intersection of Two Circles}
-
-\begin{command}{\pgfpointintersectionofcircles\marg{$p_1$}\marg{$p_2$}\marg{$r_1$}\marg{$r_2$}\marg{solution}}
- This command returns the intersection of the two circles centered at $p_1$
- and $p_2$ with radii $r_1$ and $r_2$. If \meta{solution} is |1|, the first
- intersection is returned, otherwise the second one is returned.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (2,2);
- \draw (0.5,0) circle (1);
- \draw (1.5,1) circle (.8);
- \pgfpathcircle{%
- \pgfpointintersectionofcircles
- {\pgfpointxy{.5}{0}}{\pgfpointxy{1.5}{1}}
- {1cm}{0.8cm}{1}}
- {2pt}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Points on the Intersection of Two Paths}
-
-\begin{pgflibrary}{intersections}
- This library defines the below command and allows you to calculate the
- intersections of two arbitrary paths. However, due to the low accuracy of
- \TeX, the paths should not be ``too complicated''. In particular, you
- should not try to intersect paths consisting of lots of very small segments
- such as plots or decorated paths.
-\end{pgflibrary}
-
-\begin{command}{\pgfintersectionofpaths\marg{path 1}\marg{path 2}}
- This command finds the intersection points on the paths \meta{path 1} and
- \meta{path 2}. The number of intersection points (``solutions'') that are
- found will be stored, and each point can be accessed afterward. The code
- for \meta{path 1} and \meta{path 2} is executed within a \TeX{} group and
- so can contain transformations (which will be in addition to any existing
- transformations). The code should not use the path in any way, unless the
- path is saved first and restored afterward. \pgfname{} will regard
- solutions as ``a bit special'', in that the points returned will be
- ``absolute'' and unaffected by any further transformations.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
-\begin{pgfpicture}
-\pgfintersectionofpaths
-{
- \pgfpathellipse{\pgfpointxy{0}{0}}{\pgfpointxy{1}{0}}{\pgfpointxy{0}{2}}
- \pgfgetpath\temppath
- \pgfusepath{stroke}
- \pgfsetpath\temppath
-}
-{
- \pgftransformrotate{-30}
- \pgfpathrectangle{\pgfpointorigin}{\pgfpointxy{2}{2}}
- \pgfgetpath\temppath
- \pgfusepath{stroke}
- \pgfsetpath\temppath
-}
-\foreach \s in {1,...,\pgfintersectionsolutions}
- {\pgfpathcircle{\pgfpointintersectionsolution{\s}}{2pt}}
-\pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
-
- \begin{command}{\pgfintersectionsolutions}
- After using the |\pgfintersectionofpaths| command, this \TeX-macro will
- indicate the number of solutions found.
- \end{command}
-
- \begin{command}{\pgfpointintersectionsolution\marg{number}}
- After using the |\pgfintersectionofpaths| command, this command will
- return the point for solution \meta{number} or the origin if this
- solution was not found. By default, the intersections are simply
- returned in the order that the intersection algorithm finds them.
- Unfortunately, this is not necessarily a ``helpful'' ordering. However
- the following two commands can be used to order the solutions more
- helpfully.
- \end{command}
-
- \let\ifpgfintersectionsortbyfirstpath=\relax
- \begin{command}{\pgfintersectionsortbyfirstpath}
- Using this command will mean the solutions will be sorted along
- \meta{path 1}.
- \end{command}
-
- \let\ifpgfintersectionsortbysecondpath=\relax
- \begin{command}{\pgfintersectionsortbysecondpath}
- Using this command will mean the solutions will be sorted along
- \meta{path 2}.
- \end{command}
-\end{command}
-
-
-\subsection{Extracting Coordinates}
-
-There are two commands that can be used to ``extract'' the $x$- or
-$y$-coordinate of a coordinate.
-
-\begin{command}{\pgfextractx\marg{dimension}\marg{point}}
- Sets the \TeX-\meta{dimension} to the $x$-coordinate of the point.
- %
-\begin{codeexample}[code only]
-\newdimen\mydim
-\pgfextractx{\mydim}{\pgfpoint{2cm}{4pt}}
-%% \mydim is now 2cm
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfextracty\marg{dimension}\marg{point}}
- Like |\pgfextractx|, except for the $y$-coordinate.
-\end{command}
-
-\begin{command}{\pgfgetlastxy\marg{macro for $x$}\marg{macro for $y$}}
- Stores the most recently used $(x,y)$ coordinates into two macros.
- %
-\begin{codeexample}[]
-\pgfpoint{2cm}{4cm}
-\pgfgetlastxy{\macrox}{\macroy}
-Macro $x$ is `\macrox' and macro $y$ is `\macroy'.
-\end{codeexample}
- %
- Since $(x,y)$ coordinates are usually assigned globally, it is safe to use
- this command after path operations.
-\end{command}
-
-
-\subsection{Internals of How Point Commands Work}
-\label{section-internal-pointcmds}
-
-As a normal user of \pgfname\ you do not need to read this section. It is
-relevant only if you need to understand how the point commands work internally.
-
-When a command like |\pgfpoint{1cm}{2pt}| is called, all that happens is that
-the two \TeX-dimension variables |\pgf@x| and |\pgf@y| are set to |1cm| and
-|2pt|, respectively. These variables belong to the set of internal \pgfname\
-registers, see section~\ref{section-internal-registers} for details. A command
-like |\pgfpathmoveto| that takes a coordinate as parameter will just execute
-this parameter and then use the values of |\pgf@x| and |\pgf@y| as the
-coordinates to which it will move the pen on the current path.
-
-Since commands like |\pgfpointnormalised| modify other variables besides
-|\pgf@x| and |\pgf@y| during the computation of the final values of |\pgf@x|
-and |\pgf@y|, it is a good idea to enclose a call of a command like |\pgfpoint|
-in a \TeX-scope and then make the changes of |\pgf@x| and |\pgf@y| global as in
-the following example:
- %
-\begin{codeexample}[code only]
-...
-{ % open scope
- \pgfpointnormalised{\pgfpoint{1cm}{1cm}}
- \global\pgf@x=\pgf@x % make the change of \pgf@x persist past the scope
- \global\pgf@y=\pgf@y % make the change of \pgf@y persist past the scope
-}
-% \pgf@x and \pgf@y are now set correctly, all other variables are
-% unchanged
-\end{codeexample}
-
-\makeatletter
-Since this situation arises very often, the macro |\pgf@process| can
-be used to perform the above code:
- %
-\begin{command}{\pgf@process\marg{code}}
- Executes the \meta{code} in a scope and then makes |\pgf@x| and |\pgf@y|
- global.
-\end{command}
-
-Note that this macro is used often internally. For this reason, it is not a
-good idea to keep anything important in the variables |\pgf@x| and |\pgf@y|
-since they will be overwritten and changed frequently. Instead, intermediate
-values can be stored in the \TeX-dimensions |\pgf@xa|, |\pgf@xb|, |\pgf@xc| and
-their |y|-counterparts |\pgf@ya|, |\pgf@yb|, |\pgf@yc|. For example, here is the
-code of the command |\pgfpointadd|:
-%
-\begin{codeexample}[code only]
-\def\pgfpointadd#1#2{%
- \pgf@process{#1}%
- \pgf@xa=\pgf@x%
- \pgf@ya=\pgf@y%
- \pgf@process{#2}%
- \advance\pgf@x by\pgf@xa%
- \advance\pgf@y by\pgf@ya}
-\end{codeexample}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-quick.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-quick.tex
deleted file mode 100644
index 3813556b95..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-quick.tex
+++ /dev/null
@@ -1,189 +0,0 @@
-% 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{Quick Commands}
-
-This section explains the ``quick'' commands of \pgfname. These commands are
-executed more quickly than the normal commands of \pgfname, but offer less
-functionality. You should use these commands only if you either have a very
-large number of commands that need to be processed or if you expect your
-commands to be executed very often.
-
-
-\subsection{Quick Coordinate Commands}
-
-\begin{command}{\pgfqpoint\marg{x}\marg{y}}
- This command does the same as |\pgfpoint|, but \meta{x} and \meta{y} must
- be simple dimensions like |1pt| or |1cm|. Things like |2ex| or |2cm+1pt|
- are not allowed.
-\end{command}
-
-\begin{command}{\pgfqpointxy\marg{$s_x$}\marg{$s_y$}}
- This command does the same as |\pgfpointxy|, but \meta{$s_x$} and
- \meta{$s_y$} must be simple numbers without unit, like |1.234| or |5.0|.
- Mathematical expressions or units are not allowed.
-\end{command}
-
-\begin{command}{\pgfqpointxyz\marg{$s_x$}\marg{$s_y$}\marg{$s_z$}}
- As |\pgfqpointxy|, but for three-dimensional coordinates. Any argument
- needs to be a number without unit.
-\end{command}
-
-\begin{command}{\pgfqpointscale\marg{factor}\marg{coordinate}}
- As |\pgfpointscale|, but \marg{factor} must be a simple number without
- unit, as for the other ``quick'' commands.
-\end{command}
-
-
-\subsection{Quick Path Construction Commands}
-
-The difference between the quick and the normal path commands is that the quick
-path commands
-%
-\begin{itemize}
- \item do not keep track of the bounding boxes,
- \item do not allow you to arc corners,
- \item do not apply coordinate transformations.
-\end{itemize}
-
-However, they do use the soft-path subsystem (see
-Section~\ref{section-soft-paths} for details), which allows you to mix quick
-and normal path commands arbitrarily.
-
-All quick path construction commands start with |\pgfpathq|.
-
-\begin{command}{\pgfpathqmoveto\marg{x dimension}\marg{y dimension}}
- Either starts a path or starts a new part of a path at the coordinate
- $(\meta{x dimension},\meta{y dimension})$. The coordinate is \emph{not}
- transformed by the current coordinate transformation matrix. However, any
- low-level transformations apply.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgftransformxshift{1cm}
- \pgfpathqmoveto{0pt}{0pt} % not transformed
- \pgfpathqlineto{1cm}{1cm} % not transformed
- \pgfpathlineto{\pgfpoint{2cm}{0cm}}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpathqlineto\marg{x dimension}\marg{y dimension}}
- The quick version of the line-to operation.
-\end{command}
-
-\begin{command}{\pgfpathqcurveto\marg{$s^1_x$}\marg{$s^1_y$}\marg{$s^2_x$}\marg{$s^2_y$}\marg{$t_x$}\marg{$t_y$}}
- The quick version of the curve-to operation. The first support point is
- $(s^1_x,s^1_y)$, the second support point is $(s^2_x,s^2_y)$, and the
- target is $(t_x,t_y)$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathqmoveto{0pt}{0pt}
- \pgfpathqcurveto{1cm}{1cm}{2cm}{1cm}{3cm}{0cm}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpathqcircle\marg{radius}}
- Adds a radius around the origin of the given \meta{radius}. This command is
- orders of magnitude faster than |\pgfcircle{\pgfpointorigin}{|\meta{radius}|}|.
- %
-\begin{codeexample}[]
-\colorlet{examplefill}{yellow!80!black}
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (1,1);
- \pgfpathqcircle{10pt}
- \pgfsetfillcolor{examplefill}
- \pgfusepath{stroke,fill}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Quick Path Usage Commands}
-
-The quick path usage commands perform similar tasks as |\pgfusepath|, but they
-%
-\begin{itemize}
- \item do not add arrows,
- \item do not modify the path in any way, in particular,
- \item ends are not shortened,
- \item corners are not replaced by arcs.
-\end{itemize}
-
-Note that you \emph{have to} use the quick versions in the code of arrow tip
-definitions since, inside these definition, you obviously do not want arrows to
-be drawn.
-
-\begin{command}{\pgfusepathqstroke}
- Strokes the path without further ado. No arrows are drawn, no corners are
- arced.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathqcircle{5pt}
- \pgfusepathqstroke
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfusepathqfill}
- Fills the path without further ado.
-\end{command}
-
-\begin{command}{\pgfusepathqfillstroke}
- Fills and then strokes the path without further ado.
-\end{command}
-
-\begin{command}{\pgfusepathqclip}
- Clips all subsequent drawings against the current path. The path is not
- processed.
-\end{command}
-
-
-\subsection{Quick Text Box Commands}
-
-\begin{command}{\pgfqbox\marg{box number}}
- This command inserts a \TeX\ box into a |{pgfpicture}| by ``escaping'' to
- \TeX, inserting the box number \meta{box number} at the origin, and then
- returning to the typesetting the picture.
-\end{command}
-
-\begin{command}{\pgfqboxsynced\marg{box number}}
- This command works similarly to the |\pgfqbox| command. However, before
- inserting the text in \meta{box number}, the current coordinate
- transformation matrix is applied to the current canvas transformation
- matrix (is it ``synced'' with this matrix, hence the name).
-
- Thus, this command basically has the same effect as if you first called
- |\pgflowlevelsynccm| followed by |\pgfqbox|. However, this command will use
- |\hskip| and |\raise| commands for the ``translational part'' of the
- coordinate transformation matrix, instead of adding the translational part
- to the current canvas transformation matrix directly. Both methods have the
- same effect (box \meta{box number} is translated to where it should be),
- but the method used by |\pgfqboxsynced| ensures that hyperlinks are placed
- correctly. Note that scaling and rotation will not (cannot, even) apply to
- hyperlinks.
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-scopes.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-scopes.tex
deleted file mode 100644
index 51cce0ed8e..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-scopes.tex
+++ /dev/null
@@ -1,1027 +0,0 @@
-% Copyright 2019 by Till Tantau
-%
-% This file may be distributed and/or modified
-%
-% 1. under the LaTeX Project Public License and/or
-% 2. under the GNU Free Documentation License.
-%
-% See the file doc/generic/pgf/licenses/LICENSE for more details.
-
-
-\section[Hierarchical Structures: Package, Environments, Scopes, and Text]
- {Hierarchical Structures:\\
- Package, Environments, Scopes, and Text}
-
-\subsection{Overview}
-
-\pgfname\ uses two kinds of hierarchical structuring: First, the package itself
-is structured hierarchically, consisting of different packages that are built
-on top of each other. Second, \pgfname\ allows you to structure your graphics
-hierarchically using environments and scopes.
-
-
-\subsubsection{The Hierarchical Structure of the Package}
-
-The \pgfname\ system consists of several layers:
-%
-\begin{description}
- \item[System layer.]
- The lowest layer is called the \emph{system layer}, though it might
- also be called ``driver layer'' or perhaps ``backend layer''. Its job
- is to provide an abstraction of the details of which driver is used to
- transform the |.dvi| file. The system layer is implemented by the
- package |pgfsys|, which will load appropriate driver files as needed.
-
- The system layer is documented in Part~\ref{part-system}.
- \item[Basic layer.]
- The basic layer is loaded by the package |pgfcore| and subsequent use
- of the command |\usepgfmodule| to load additional modules of the basic
- layer.
-
- The basic layer is documented in the present part.
- \item[Frontend layer.]
- The frontend layer is not loaded by a single package. Rather, different
- packages, like \tikzname\ or \textsc{pgfpict2e}, are different
- frontends to the basic layer.
-
- The \tikzname\ frontend is documented in Part~\ref{part-tikz}.
-\end{description}
-
-Each layer will automatically load the necessary files of the layers below it.
-
-In addition to the packages of these layers, there are also some library
-packages. These packages provide additional definitions of things like new
-arrow tips or new plot handlers.
-
-The library packages are documented in Part~\ref{part-libraries}.
-
-
-\subsubsection{The Hierarchical Structure of Graphics}
-
-Graphics in \pgfname\ are typically structured hierarchically. Hierarchical
-structuring can be used to identify groups of graphical elements that are to be
-treated ``in the same way''. For example, you might group together a number of
-paths, all of which are to be drawn in red. Then, when you decide later on that
-you like them to be drawn in, say, blue, all you have to do is to change the
-color once.
-
-The general mechanism underlying hierarchical structuring is known as
-\emph{scoping} in computer science. The idea is that all changes to the general
-``state'' of the graphic that are done inside a scope are local to that scope.
-So, if you change the color inside a scope, this does not affect the color used
-outside the scope. Likewise, when you change the line width in a scope, the
-line width outside is not changed, and so on.
-
-There are different ways of starting and ending scopes of graphic parameters.
-Unfortunately, these scopes are sometimes ``in conflict'' with each other and
-it is sometimes not immediately clear which scopes apply. In essence, the
-following scoping mechanisms are available:
-%
-\begin{enumerate}
- \item The ``outermost'' scope supported by \pgfname\ is the |{pgfpicture}|
- environment. All changes to the graphic state done inside a
- |{pgfpicture}| are local to that picture.
-
- In general, it is \emph{not} possible to set graphic parameters
- globally outside any |{pgfpicture}| environments. Thus, you can
- \emph{not} say |\pgfsetlinewidth{1pt}| at the beginning of your
- document to have a default line width of one point. Rather, you have to
- (re)set all graphic parameters inside each |{pgfpicture}|. (If this is
- too bothersome, try defining some macro that does the job for you.)
- \item Inside a |{pgfpicture}| you can use a |{pgfscope}| environment to
- keep changes of the graphic state local to that environment.
-
- The effect of commands that change the graphic state are local to the
- current |{pgfscope}|, but not always to the current \TeX\ group. Thus,
- if you open a \TeX\ group (some text in curly braces) inside a
- |{pgfscope}|, and if you change, for example, the dash pattern, the
- effect of this changed dash pattern will persist till the end of the
- |{pgfscope}|.
-
- Unfortunately, this is not always the case. \emph{Some} graphic
- parameters only persist till the end of the current \TeX\ group. For
- example, when you use |\pgfsetarrows| to set the arrow tip inside a
- \TeX\ group, the effect lasts only till the end of the current \TeX\
- group.
- \item Some graphic parameters are not scoped by |{pgfscope}| but
- ``already'' by \TeX\ groups. For example, the effect of coordinate
- transformation commands is always local to the current \TeX\ group.
-
- Since every |{pgfscope}| automatically creates a \TeX\ group, all
- graphic parameters that are local to the current \TeX\ group are also
- local to the current |{pgfscope}|.
- \item Some graphic parameters can only be scoped using \TeX\ groups, since
- in some situations it is not possible to introduce a |{pgfscope}|. For
- example, a path always has to be completely constructed and used in the
- same |{pgfscope}|. However, we might wish to have different coordinate
- transformations apply to different points on the path. In this case, we
- can use \TeX\ groups to keep the effect local, but we could not use
- |{pgfscope}|.
- \item The |\pgftext| command can be used to create a scope in which \TeX\
- ``escapes back'' to normal \TeX\ mode. The text passed to the
- |\pgftext| is ``heavily guarded'' against having any effect on the
- scope in which it is used. For example, it is possible to use another
- |{pgfpicture}| environment inside the argument of |\pgftext|.
-\end{enumerate}
-
-Most of the complications can be avoided if you stick to the following
-rules:
-%
-\begin{itemize}
- \item Give graphic commands only inside |{pgfpicture}| environments.
- \item Use |{pgfscope}| to structure graphics.
- \item Do not use \TeX\ groups inside graphics, \emph{except} for keeping
- the effect of coordinate transformations local.
-\end{itemize}
-
-
-\subsection{The Hierarchical Structure of the Package}
-
-Before we come to the structuring commands provided by \pgfname\ to structure
-your graphics, let us first have a look at the structure of the package itself.
-
-
-\subsubsection{The Core Package}
-
-To use \pgfname, include the following package:
-
-\begin{package}{pgfcore}
- This package loads the complete core of the ``basic layer'' of \pgfname,
- but not any modules. That is, it will load all of the commands described in
- the current part of this manual, but it will not load frontends like
- \tikzname. It will also load the system layer. To load additional modules,
- use the |\usepgfmodule| command explained below.
-\end{package}
-
-The following package is just a convenience.
-
-\begin{package}{pgf}
- This package loads the |pgfcore| and the two modules |shapes| and |plot|.
-
- In \LaTeX, the package takes two options:
- %
- \begin{packageoption}{draft}
- When this option is set, all images will be replaced by empty
- rectangles. This can speedup compilation.
- \end{packageoption}
-
- \begin{packageoption}{version=\meta{version}}
- Indicates that the commands of version \meta{version} need to be
- defined. If you set \meta{version} to |0.65|, then a large bunch of
- ``compatibility commands'' are loaded. If you set \meta{version} to
- |0.96|, then these compatibility commands will not be loaded.
-
- If this option is not given at all, then the commands of all versions
- are defined.
- \end{packageoption}
-\end{package}
-
-
-\subsubsection{The Modules}
-
-\begin{command}{\usepgfmodule\marg{module names}}
- Once the core has been loaded, you can use this command to load further
- modules. The modules in the \meta{module names} list should be separated by
- commas. Instead of curly braces, you can also use square brackets, which is
- something Con\TeX t users will like. If you try to load a module a second
- time, nothing will happen.
-
- \example |\usepgfmodule{matrix,shapes}|
-
- What this command does is to load the file
- |pgfmodule|\meta{module}|.code.tex| for each \meta{module} in the list of
- \meta{module names}. Thus, to write your own module, all you need to do is
- to place a file of the appropriate name somewhere \TeX\ can find it.
- \LaTeX, plain \TeX, and Con\TeX t users can then use your library.
-\end{command}
-
-The following modules are available for use with |pgfcore|: \todosp{In the
-meantime there are some more modules. Also mention them here?}
-%
-\begin{itemize}
- \item The |plot| module provides commands for plotting functions. The
- commands are explained in Section~\ref{section-plots}.
- \item The |shapes| module provides commands for drawing shapes and nodes.
- These commands are explained in Section~\ref{section-shapes}.
- \item The |decorations| module provides commands for adding decorations to
- paths. These commands are explained in
- Section~\ref{section-base-decorations}.
- \item The |matrix| module provides the |\pgfmatrix| command. The commands
- are documented in Section~\ref{section-base-matrices}.
-\end{itemize}
-
-
-\subsubsection{The Library Packages}
-
-There is a special command for loading library packages. The difference between
-a library and module is the following: A library just defines additional
-objects using the basic layer, whereas a module adds completely new
-functionality. For instance, a |decorations| library defines additional
-decorations, while a decoration module defines the whole code for handling
-decorations.
-
-\begin{command}{\usepgflibrary\marg{list of libraries}}
- Use this command to load further libraries. The list of libraries should
- contain the names of libraries separated by commas. Instead of curly
- braces, you can also use square brackets. If you try to load a library a
- second time, nothing will happen.
-
- \example |\usepgflibrary{arrows}|
-
- This command causes the file |pgflibrary|\meta{library}|.code.tex| to be
- loaded for each \meta{library} in the \meta{list of libraries}. This means
- that in order to write your own library file, place a file of the
- appropriate name somewhere where \TeX\ can find it. \LaTeX, plain \TeX, and
- Con\TeX t users can then use your library.
-
- You should also consider adding a \tikzname\ library that simply includes
- your \pgfname\ library.
-\end{command}
-
-
-\subsection{The Hierarchical Structure of the Graphics}
-
-\subsubsection{The Main Environment}
-
-Most, but not all, commands of the \pgfname\ package must be given within a
-|{pgfpicture}| environment. The only commands that (must) be given outside are
-commands having to do with including images (like |\pgfuseimage|) and with
-inserting complete shadings (like |\pgfuseshading|). However, just to keep life
-entertaining, the |\pgfshadepath| command must be given \emph{inside} a
-|{pgfpicture}| environment.
-
-\begin{environment}{{pgfpicture}}
- This environment will insert a \TeX\ box containing the graphic drawn by
- the \meta{environment contents} at the current position.
-
-
- \medskip
- \textbf{The size of the bounding box.}
- The size of the box is determined in the following manner: While \pgfname\
- parses the \meta{environment contents}, it keeps track of a bounding box
- for the graphic. Essentially, this bounding box is the smallest box that
- contains all coordinates mentioned in the graphics. Some coordinates may be
- ``mentioned'' by \pgfname\ itself; for example, when you add circle to the
- current path, the support points of the curve making up the circle are also
- ``mentioned'' despite the fact that you will not ``see'' them in your code.
-
- Once the \meta{environment contents} have been parsed completely, a \TeX\
- box is created whose size is the size of the computed bounding box and this
- box is inserted at the current position.
- %
-\begin{codeexample}[]
-Hello \begin{pgfpicture}
- \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
- \pgfusepath{stroke}
-\end{pgfpicture} World!
-\end{codeexample}
-
- Sometimes, you may need more fine-grained control over the size of the
- bounding box. For example, the computed bounding box may be too large or
- you intensionally wish the box to be ``too small''. In these cases, you can
- use the command |\pgfusepath{use as bounding box}|, as described in
- Section~\ref{section-using-bb}.
-
-
- \medskip
- \textbf{The baseline of the bounding box.}
- When the box containing the graphic is inserted into the normal text, the
- baseline of the graphic is normally at the bottom of the graphic. For this
- reason, the following two sets of code lines have the same effect, despite
- the fact that the second graphic uses ``higher'' coordinates than the
- first:
- %
-\begin{codeexample}[]
-Rectangles \begin{pgfpicture}
- \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
- \pgfusepath{stroke}
-\end{pgfpicture} and \begin{pgfpicture}
- \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
- \pgfusepath{stroke}
-\end{pgfpicture}.
-\end{codeexample}
-
- You can change the baseline using the |\pgfsetbaseline| command, see below.
- %
-\begin{codeexample}[]
-Rectangles \begin{pgfpicture}
- \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{1ex}}
- \pgfusepath{stroke}
- \pgfsetbaseline{0pt}
-\end{pgfpicture} and \begin{pgfpicture}
- \pgfpathrectangle{\pgfpoint{0ex}{1ex}}{\pgfpoint{2ex}{1ex}}
- \pgfusepath{stroke}
- \pgfsetbaseline{0pt}
-\end{pgfpicture}.
-\end{codeexample}
-
-
- \medskip
- \textbf{Including text and images in a picture.}
- You cannot directly include text and images in a picture. Thus, you should
- \emph{not} simply write some text in a |{pgfpicture}| or use a command like
- |\includegraphics| or even |\pgfimage|. In all these cases, you need to
- place the text inside a |\pgftext| command. This will ``escape back'' to
- normal \TeX\ mode, see Section~\ref{section-text-command} for details.
-
-
- \medskip
- \textbf{Remembering a picture position for later reference.}
- After a picture has been typeset, its position on the page is normally
- forgotten by \pgfname\ and also by \TeX. This means that is not possible to
- reference a node in this picture later on. In particular, it is normally
- impossible to draw lines between nodes in different pictures automatically.
-
- In order to make \pgfname\ ``remember'' a picture, the \TeX-if
- |\ifpgfrememberpicturepositiononpage| should be set to |true|. It is only
- important that this \TeX-if is |true| at the end of the
- |{pgfpicture}|-en\-vi\-ron\-ment, so you can switch it on inside the
- environment. However, you can also just switch it on globally, then the
- positions of all pictures are remembered.
-
- There are several reasons why the remembering is not switched on by
- default. First, it does not work for all backend drivers (currently, it
- works only for pdf\TeX). Second, it requires two passes of \TeX\ over the
- file; on the first pass all positions will be wrong. Third, for every
- remembered picture a line is added to the |.aux|-file, which may result in
- a large number of extra lines.
-
- Despite all these ``problems'', for documents that are processed with
- pdf\TeX\ and in which there is only a small number of pictures (less than a
- hundred or so), you can switch on this option globally, it will not cause
- any significant slowing of \TeX.
-\end{environment}
-
-\begin{plainenvironment}{{pgfpicture}}
- The plain \TeX\ version of the environment. Note that in this version,
- also, a \TeX\ group is created around the environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{pgfpicture}}
- This is the Con\TeX t version of the environment.
-\end{contextenvironment}
-
-{\let\ifpgfrememberpicturepositiononpage=\relax
-\begin{command}{\ifpgfrememberpicturepositiononpage}
- Determines whether the position of pictures on the page should be recorded.
- The value of this \TeX-if at the end of a |{pgfpicture}| environment is
- important, not the value at the beginning.
-
- If this option is set to true of a picture, \pgfname\ will attempt to
- record the position of the picture on the page. (This attempt will fail
- with most drivers and when it works, it typically requires two runs of
- \TeX.) The position is not directly accessible. Rather, the nodes mechanism
- will use this position if you access a node from another picture. See
- Sections~\ref{section-cross-pictures-pgf}
- and~\ref{section-cross-picture-tikz} for more details.
-\end{command}
-}
-
-\makeatletter
-\begin{command}{\pgfsetbaseline\marg{dimension}}
- This command specifies a $y$-coordinate of the picture that should be used
- as the baseline of the whole picture. When a \pgfname\ picture has been
- typeset completely, \pgfname\ must decide at which height the baseline of
- the picture should lie. Normally, the baseline is set to the $y$-coordinate
- of the bottom of the picture, but it is often desirable to use a different
- height.
- %
-\begin{codeexample}[]
-Text
-\begin{pgfpicture}
- \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
-\end{pgfpicture},
-\begin{pgfpicture}
- \pgfsetbaseline{0pt}
- \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
-\end{pgfpicture},
-\begin{pgfpicture}
- \pgfsetbaseline{.5ex}
- \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
-\end{pgfpicture},
-\begin{pgfpicture}
- \pgfsetbaseline{-1ex}
- \pgfpathcircle{\pgfpointorigin}{1ex}\pgfusepath{stroke}
-\end{pgfpicture}.
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetbaselinepointnow\marg{point}}
- This command specifies the baseline indirectly, namely as the
- $y$-coordinate that the given \meta{point} has when the command is called.
-\end{command}
-
-\begin{command}{\pgfsetbaselinepointlater\marg{point}}
- This command also specifies the baseline indirectly, but the $y$-coordinate
- of the given \meta{point} is only computed at the end of the picture.
- %
-\begin{codeexample}[]
-Hello
-\begin{pgfpicture}
- \pgfsetbaselinepointlater{\pgfpointanchor{X}{base}}
- % Note: no shape X, yet
- \pgfnode{cross out}{center}{world.}{X}{\pgfusepath{stroke}}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Graphic Scope Environments}
-
-Inside a |{pgfpicture}| environment you can substructure your picture using the
-following environment:
-
-\begin{environment}{{pgfscope}}
- All changes to the graphic state done inside this environment are
- local to the environment. The graphic state includes the following:
- %
- \begin{itemize}
- \item The line width.
- \item The stroke and fill colors.
- \item The dash pattern.
- \item The line join and cap.
- \item The miter limit.
- \item The canvas transformation matrix.
- \item The clipping path.
- \end{itemize}
- %
- Other parameters may also influence how graphics are rendered, but they are
- \emph{not} part of the graphic state. For example, the arrow tip kind is
- not part of the graphic state and the effect of commands setting the arrow
- tip kind are local to the current \TeX\ group, not to the current
- |{pgfscope}|. However, since |{pgfscope}| starts and ends a \TeX\ group
- automatically, a |{pgfscope}| can be used to limit the effect of, say,
- commands that set the arrow tip kind.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \begin{pgfscope}
- {
- \pgfsetlinewidth{2pt}
- \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2ex}{2ex}}
- \pgfusepath{stroke}
- }
- \pgfpathrectangle{\pgfpoint{3ex}{0ex}}{\pgfpoint{2ex}{2ex}}
- \pgfusepath{stroke}
- \end{pgfscope}
- \pgfpathrectangle{\pgfpoint{6ex}{0ex}}{\pgfpoint{2ex}{2ex}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{pgfpicture}
- \begin{pgfscope}
- {
- \pgfsetarrows{->}
- \pgfpathmoveto{\pgfpointorigin}\pgfpathlineto{\pgfpoint{2ex}{2ex}}
- \pgfusepath{stroke}
- }
- \pgfpathmoveto{\pgfpoint{3ex}{0ex}}\pgfpathlineto{\pgfpoint{5ex}{2ex}}
- \pgfusepath{stroke}
- \end{pgfscope}
- \pgfpathmoveto{\pgfpoint{6ex}{0ex}}\pgfpathlineto{\pgfpoint{8ex}{2ex}}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
-
- At the start of the scope, the current path must be empty, that is, you
- cannot open a scope while constructing a path.
-
- It is usually a good idea \emph{not} to introduce \TeX\ groups inside a
- |{pgfscope}| environment.
-\end{environment}
-
-\begin{plainenvironment}{{pgfscope}}
- Plain \TeX\ version of the |{pgfscope}| environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{pgfscope}}
- This is the Con\TeX t version of the environment.
-\end{contextenvironment}
-
-The following scopes also encapsulate certain properties of the graphic state.
-However, they are typically not used directly by the user.
-
-\begin{environment}{{pgfinterruptpath}}
- This environment can be used to temporarily interrupt the construction of
- the current path. The effect will be that the path currently under
- construction will be ``stored away'' and restored at the end of the
- environment. Inside the environment you can construct a new path and do
- something with it.
-
- An example application of this environment is the arrow tip caching.
- Suppose you ask \pgfname\ to use a specific arrow tip kind. When the arrow
- tip needs to be rendered for the first time, \pgfname\ will ``cache'' the
- path that makes up the arrow tip. To do so, it interrupts the current path
- construction and then protocols the path of the arrow tip. The
- |{pgfinterruptpath}| environment is used to ensure that this does not
- interfere with the path to which the arrow tips should be attached.
-
- This command does \emph{not} install a |{pgfscope}|. In particular, it does
- not call any |\pgfsys@| commands at all, which would, indeed, be dangerous
- in the middle of a path construction.
-\end{environment}
-
-\begin{plainenvironment}{{pgfinterruptpath}}
- Plain \TeX\ version of the environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{pgfinterruptpath}}
- Con\TeX t version of the environment.
-\end{contextenvironment}
-
-\begin{environment}{{pgfinterruptpicture}}
- This environment can be used to temporarily interrupt a |{pgfpicture}|.
- However, the environment is intended only to be used at the beginning and
- end of a box that is (later) inserted into a |{pgfpicture}| using
- |\pgfqbox|. You cannot use this environment directly inside a
- |{pgfpicture}|.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfpathmoveto{\pgfpoint{0cm}{0cm}} % In the middle of path, now
- \newbox\mybox
- \setbox\mybox=\hbox{
- \begin{pgfinterruptpicture}
- Sub-\begin{pgfpicture} % a subpicture
- \pgfpathmoveto{\pgfpoint{1cm}{0cm}}
- \pgfpathlineto{\pgfpoint{1cm}{1cm}}
- \pgfusepath{stroke}
- \end{pgfpicture}-picture.
- \end{pgfinterruptpicture}
- }
- \pgfqbox{\mybox}%
- \pgfpathlineto{\pgfpoint{0cm}{1cm}}
- \pgfusepath{stroke}
-\end{pgfpicture}\hskip3.9cm
-\end{codeexample}
- %
-\end{environment}
-
-\begin{plainenvironment}{{pgfinterruptpicture}}
- Plain \TeX\ version of the environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{pgfinterruptpicture}}
- Con\TeX t version of the environment.
-\end{contextenvironment}
-
-\begin{environment}{{pgfinterruptboundingbox}}
- This environment temporarily interrupts the computation of the bounding box
- and sets up a new bounding box. At the beginning of the environment the old
- bounding box is saved and an empty bounding box is installed. After the
- environment the original bounding box is reinstalled as if nothing has
- happened.
-\end{environment}
-
-\begin{plainenvironment}{{pgfinterruptboundingbox}}
- Plain \TeX\ version of the environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{pgfinterruptboundingbox}}
- Con\TeX t version of the environment.
-\end{contextenvironment}
-
-
-\subsubsection{Inserting Text and Images}
-\label{section-text-command}
-
-Often, you may wish to add normal \TeX\ text at a certain point inside a
-|{pgfpicture}|. You cannot do so ``directly'', that is, you cannot simply write
-this text inside the |{pgfpicture}| environment. Rather, you must pass the text
-as an argument to the |\pgftext| command.
-
-You must \emph{also} use the |\pgftext| command to insert an image or a shading
-into a |{pgfpicture}|.
-
-\begin{command}{\pgftext\opt{\oarg{options}}\marg{text}}
- This command will typeset \meta{text} in normal \TeX\ mode and insert the
- resulting box into the |{pgfpicture}|. The bounding box of the graphic will
- be updated so that all of the text box is inside. By default, the text box
- is centered at the origin, but this can be changed either by giving
- appropriate \meta{options} or by applying an appropriate coordinate
- transformation beforehand.
-
- The \meta{text} may contain verbatim text. (In other words, the \meta{text}
- ``argument'' is not a normal argument, but is put in a box and some
- |\aftergroup| hackery is used to find the end of the box.)
-
- \pgfname's current (high-level) coordinate transformation is synchronized
- with the canvas transformation matrix temporarily when the text box is
- inserted. The effect is that if there is currently a high-level rotation
- of, say, 30 degrees, the \meta{text} will also be rotated by thirty
- degrees. If you do not want this effect, you have to (possibly temporarily)
- reset the high-level transformation matrix.
-
- The \meta{options} keys are used with the path |/pgf/text/|. The following
- keys are defined for this path:
- %
- \begin{key}{/pgf/text/left}
- The key causes the text box to be placed such that its left border is
- on the origin.
- %
-\begin{codeexample}[]
-\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
- \pgftext[left] {lovely}}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/text/right}
- The key causes the text box to be placed such that its right border is
- on the origin.
- %
-\begin{codeexample}[]
-\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
- \pgftext[right] {lovely}}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/text/top}
- This key causes the text box to be placed such that its top is on the
- origin. This option can be used together with the |left| or |right|
- option.
- %
-\begin{codeexample}[]
-\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
- \pgftext[top] {lovely}}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
- \pgftext[top,right] {lovely}}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/text/bottom}
- This key causes the text box to be placed such that its bottom is on
- the origin.
- %
-\begin{codeexample}[]
-\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
- \pgftext[bottom] {lovely}}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
- \pgftext[bottom,right] {lovely}}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/text/base}
- This key causes the text box to be placed such that its baseline is on
- the origin.
- %
-\begin{codeexample}[]
-\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
- \pgftext[base] {lovely}}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
- \pgftext[base,right] {lovely}}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/text/at=\meta{point}}
- Translates the origin (that is, the point where the text is shown) to
- \meta{point}.
- %
-\begin{codeexample}[]
-\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
- \pgftext[base,at={\pgfpoint{1cm}{0cm}}] {lovely}}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/text/x=\meta{dimension}}
- Translates the origin by \meta{dimension} along the $x$-axis.
- %
-\begin{codeexample}[]
-\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
- \pgftext[base,x=1cm,y=-0.5cm] {lovely}}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/text/y=\meta{dimension}}
- This key works like the |x| option.
- \end{key}
- %
- \begin{key}{/pgf/text/rotate=\meta{degree}}
- Rotates the coordinate system by \meta{degree}. This will also rotate
- the text box.
- %
-\begin{codeexample}[]
-\tikz{\draw[help lines] (-1,-.5) grid (1,.5);
- \pgftext[base,x=1cm,y=-0.5cm,rotate=30] {lovely}}
-\end{codeexample}
- \end{key}
-\end{command}
-
-
-\subsection{Object Identifiers}
-
-Graphical objects can have an \emph{identifier,} which allows you to reference
-the object later on. For instance, you could reference the object as the target
-of a hyperlink (although this capability is not necessarily implemented by
-drivers) or as the target of an animation; indeed, animations always need an
-object identifier to identify the to-be-animated object.
-
-Attaching an identifier to an object is a two-step process:
-%
-\begin{enumerate}
- \item You call |\pgfuseid{|\meta{id}|}| to choose an id, which is a normal
- string.
- \item Next, you call one of several commands like |\pgfidscope| or
- |\pgftext|, which create an object. This object will have then have the
- id.
-\end{enumerate}
-
-
-\subsubsection{Commands for Creating Graphic Objects}
-
-The following system level commands create an object with an id:
-%
-\begin{enumerate}
- \item |\pgfsys@begin@idscope|, which creates a graphic scope.
- \item |\pgfsys@viewboxmeet| or |\pgfsys@viewboxslice|, which create view
- boxes,
- \item |\pgfsys@fill|, |\pgfsys@stroke|, and all other path usage command,
- \item |\pgfsys@hbox| or |\pgfsys@hboxsynced|, which create text boxes, and
- \item |\pgfsys@animate...|, which create animations.
-\end{enumerate}
-
-These system layer commands are, in turn, called by the following basic layer
-commands (and, also, by the commands that call them, in turn):
-%
-\begin{itemize}
- \item |\pgfidscope|, which creates an id scope (see below).
- \item |\pgfviewboxscope|, which creates a view box.
- \item |\pgfusepath|, which creates a path.
- \item |\pgftext| and |\pgfnode| and |\pgfmultipartnode|, which create text
- boxes and nodes, and
- \item |\pgfanimateattribute|, which creates an animation.
-\end{itemize}
-
-\begin{environment}{{pgfidscope}}
- Creates a graphic scope that will have the id last used with |\pgfuseid|
- attached to, provided such an id was set and was not already used with
- another object. In the latter cases, no graphic scope is created. Thus, if
- you wish to ensure that a graphic scope is created, you must (additionally)
- call |\pgfscope| inside or outside the id scope.
-\end{environment}
-
-The Plain\TeX\ and Con\TeX t versions of the environment are:
-%
-\begin{plainenvironment}{{pgfidscope}}
-\end{plainenvironment}
-
-\begin{contextenvironment}{{pgfidscope}}
-\end{contextenvironment}
-
-
-\subsubsection{Settings and Querying Identifiers}
-
-In order to attach an identifier to an object, you first use the following
-command:
-
-\begin{command}{\pgfuseid\marg{name}}
- The \meta{name} is a string by which the object will be referenced (see
- |\pgfidrefnextuse|). The next time a graphic object is created in the
- current \TeX\ scope, the name will be attached to it (actually, it will get
- a system layer identifier attached to it that is automatically created
- using |\pgfsys@new@id|, the \meta{name} is bound to that identifier and it
- can be retrieved using |\pgfidrefnextuse|). This holds true only for the
- next object: If a second object is created, it will not get the name
- attached to it. This does not mean, however, that you cannot attach the
- same name to different objects; you just need to call |\pgfuseid| again
- before each object.
-
- Besides the \meta{name} (or, more precisely, besides the system layer
- identifier is refers to), the current \emph{identifier type} is also
- important: Actually, a graphic object is not referenced by a system layer
- identifier, but by the combination of the identifier and a type. You can
- use the following commands for modifying the type used for the creation of
- objects:
-
- \begin{command}{\pgfusetype\marg{type}}
- Sets the type used for the referencing of graphic objects for the
- current scope to \meta{type} or, if \meta{type} starts with a dot,
- appends \meta{type} to the current type.
-
- You use this command with compound graphic objects: Before each part of
- a graphic object, set the type to an appropriate value. Now, if the
- object is named using |\pgfuseid|, you can later on access all parts of
- the compound object using the combination of the \meta{name} used with
- |\pgfuseid| and the type of the part.
-
- As an example, this system is used to give you access to the different
- parts of a node: When use say |\pgfuseid{mynode}| and then create a
- node, you can use |mynode| with the empty type to reference the
- graphics scope that encompasses the whole node, but also |mynode|
- together with the type |background| to access the background path of
- the node.
-
- In detail, \pgfname\ uses this command to set the following types:
- %
- \begin{itemize}
- \item Inside the command |\pgfviewboxscope|, the type |.view| is
- used for the view object.
- \item Inside the command |\pgfmultipartnode|, the type
- |.behind background| is used for the scope of drawings behind
- the background. Similarly, |.before background| and
- |.behind foreground| and finally |.before foreground| are used
- with the respective parts of a node.
- \item Also inside a node, |.background| and |.foreground| are used
- as types of the background and foreground paths, respectively.
- \item Finally, inside a node, for each text part, the text part's
- name is used as a type (so |.text| is used for the main part).
- \end{itemize}
-
- In addition, \tikzname\ uses this command in the following
- situations:
- %
- \begin{itemize}
- \item The type |.path| is used with a named path (named using the
- |name| key). This is the graphic object you need to reference
- when you wish to morph a path.
- \item The type |.path picture| is used with the scope of the
- optional path picture.
- \item The type |.path fill| is used with the path used for filling.
- This is not the same as the normal path in case the path is
- filled and patterned, for instance.
- \item The type |.path shade| is used with the path used for shading
- a path.
- \end{itemize}
- \end{command}
-
- \begin{command}{\pgfpushtype}
- Pushes the current type on an internal global stack. The idea is to
- allow you to temporarily change the current type without having to open
- a \TeX\ scope.
- \end{command}
-
- \begin{command}{\pgfpoptype}
- Restores the most recent type from the internal global stack of types.
- \end{command}
-\end{command}
-
-\begin{command}{\pgfclearid}
- Clears the current id (and type) for the local scope.
-\end{command}
-
-\begin{command}{\pgfidrefnextuse\marg{macro}\marg{name}}
- This command assigns a system layer identifier (the identifier returned by
- |\pgfsys@new@id|) to the \meta{macro}, namely the one that will be used the
- \emph{next} time |\pgfuseid| is used. You use this command for ``forward
- referencing''.
-
- A typical use case is the following: A key like |whom| for animations uses
- this command to get the system identifier that will be used for a future
- object. Then, this identifier can be passed to system layer commands like
- |\pgfsys@animation@whom|.
-
- Note that the ``next'' use need not be on the same page (or there may not
- even be any use at all), in which case the reference will not refer to any
- object.
-\end{command}
-
-\begin{command}{\pgfidrefprevuse\marg{macro}\marg{name}}
- Works like |\pgfidrefnextuse|, only it references the most recent
- \emph{previous} use of the \meta{name}. As for |\pgfidrefnextuse|, the most
- recent use need not be on the same page.
-\end{command}
-
-\begin{command}{\pgfaliasid\marg{alias}\marg{name}}
- Creates an alias of a name inside the current \TeX\ scope. After calling
- this command, you can use \meta{alias} anywhere where you would normally
- use \meta{name}. Note that the binding between \meta{alias} and \meta{name}
- is not kept when |\pgfuseid| is used on the \meta{name} (or the
- \meta{alias}).
-\end{command}
-
-\begin{command}{\pgfgaliasid\marg{1}\marg{2}}
- Like |\pgfaliasid|, only the alias is set globally.
-\end{command}
-
-\begin{command}{\pgfifidreferenced\marg{name}\marg{then code}\marg{else code}}
- If \meta{name} has been referenced, \meta{then code} is executed, otherwise
- \meta{else code}.
-\end{command}
-
-
-\subsection{Resource Description Framework Annotations (RDFa)}
-\label{section-base-rdf}
-
-With certain output formats (in particular, with \textsc{svg}) you can insert
-annotations into the output file following the standard set by the
-\emph{resource description framework} (known as ``\textsc{rdf}'', please
-consult the literature on \textsc{rdf} and \textsc{rdf}a for an introduction to
-resource descriptions and ontologies and their purpose in general). To do so,
-you call one (or several) of the following commands before you call
-|\pgfidscope|. The attributes and values you specify using the commands will
-then be added to the resulting scope (if the driver supports this, which is
-only the case for \textsc{svg} at the moment). As an example, when you write
-%
-\begin{codeexample}[code only]
-\pgfrdfresource{/fruits/apple}
-\pgfidscope
-...
-\pgfendidscope
-\end{codeexample}
-
-in the resulting \textsc{svg} file you get
-%
-\begin{codeexample}[code only]
-<g resource="/fruits/apple">
- ...
-</g>
-\end{codeexample}
-
-Most of the following commands just set a single attribute for the next id
-scope. In some cases, however, repeated calling of these commands makes sense
-and causes the passed values to accumulate as in the following example:
-%
-\begin{codeexample}[code only]
-\pgfrdfresource{/fruits/apple}
-\pgfrdfproperty{http://foo.com/props/juicy}
-\pgfrdfproperty{http://foo.com/props/green}
-\pgfidscope
-...
-\pgfendidscope
-\end{codeexample}
-
-Now you get:
-%
-\begin{codeexample}[code only]
-<g resource="/fruits/apple"
- property="http://foo.com/props/juicy http://foo.com/props/green">
- ...
-</g>
-\end{codeexample}
-
-The following commands ``accumulate'': |\pgfrdfproperty|, |\pgfrdfrel|,
-|\pgfrdfrev| and also the command |\pgfrdftypeof|.
-
-\begin{command}{\pgfrdfabout\marg{text}}
- Adds the \textsc{rdf} attribute |about="|\meta{text}|"| to the next id
- scope (please see the \textsc{rdf}a specification for details on the
- semantics of |about| in the context of the resource description framework).
-\end{command}
-
-The following commands work the same way.
-
-\begin{command}{\pgfrdfcontent\marg{text}}
-\end{command}
-
-\begin{command}{\pgfrdfdatatype\marg{text}}
-\end{command}
-
-\begin{command}{\pgfrdfhref\marg{text}}
-\end{command}
-
-\begin{command}{\pgfrdfinlist}
-\end{command}
-
-\begin{command}{\pgfrdfprefix\marg{text}}
-\end{command}
-
-\begin{command}{\pgfrdfproperty\marg{text}}
-\end{command}
-
-\begin{command}{\pgfrdfrel\marg{text}}
-\end{command}
-
-\begin{command}{\pgfrdfresource\marg{text}}
-\end{command}
-
-\begin{command}{\pgfrdfrev\marg{text}}
-\end{command}
-
-\begin{command}{\pgfrdfsrc\marg{text}}
-\end{command}
-
-\begin{command}{\pgfrdftypeof\marg{text}}
-\end{command}
-
-\begin{command}{\pgfrdfvocab\marg{text}}
-\end{command}
-
-
-\subsection{Error Messages and Warnings}
-
-Sometimes, a command inside \pgfname\ may fail. In this case, two commands are
-useful to communicate with the author:
-
-\begin{command}{\pgferror\marg{message}}
- Stops the processing of the current document and prints out the
- \meta{message}. In \LaTeX, this will be done using |\PackageError|,
- otherwise |\errmessage| is used directly.
-\end{command}
-
-\begin{command}{\pgfwarning\marg{message}}
- Prints the \meta{message} on the output, but does not interrupt the
- processing. In \LaTeX, this will be done using |\PackageWarning|, otherwise
- a write to stream $17$ is used.
-\end{command}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-shadings.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-shadings.tex
deleted file mode 100644
index a091bc31b5..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-shadings.tex
+++ /dev/null
@@ -1,762 +0,0 @@
-% 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{Shadings}
-\label{section-shadings}
-
-\subsection{Overview}
-
-A shading is an area in which the color changes smoothly between different
-colors. Similarly to an image, a shading must first be declared before it can
-be used. Also similarly to an image, a shading is put into a \TeX-box. Hence,
-in order to include a shading in a |{pgfpicture}|, you have to use |\pgftext|
-around it.
-
-There are different kinds of shadings: horizontal, vertical, radial, and
-functional shadings. However, you can rotate and clip shadings like any other
-graphics object, which allows you to create more complicated shadings.
-Horizontal shadings could be created by rotating a vertical shading by 90
-degrees, but explicit commands for creating both horizontal and vertical
-shadings are included for convenience.
-
-Once you have declared a shading, you can insert it into the text using the
-command |\pgfuseshading|. This command cannot be used directly in a
-|{pgfpicture}|, you have to put a |\pgftext| around it. The second command for
-using shadings, |\pgfshadepath|, on the other hand, can only be used inside
-|{pgfpicture}| environments. It will ``fill'' the current path with the
-shading.
-
-A horizontal shading is a horizontal bar of a certain height whose color
-changes smoothly. You must at least specify the colors at the left and at the
-right end of the bar, but you can also add color specifications for points in
-between. For example, suppose you wish to create a bar that is red at the left
-end, green in the middle, and blue at the end, and you would like the bar to be
-4cm long. This could be specified as follows:
-%
-\begin{codeexample}[code only]
-rgb(0cm)=(1,0,0); rgb(2cm)=(0,1,0); rgb(4cm)=(0,0,1)
-\end{codeexample}
-%
-This line means that at 0cm (the left end) of the bar, the color should be red,
-which has red-green-blue (rgb) components (1,0,0). At 2cm, the bar should be
-green, and at 4cm it should be blue. Instead of |rgb|, you can currently also
-specify |cmyk| as color model, in which case four values are needed,
-|gray| as color model, in which case only one value is needed, or
-|color|, in which case you must provide the name of a color in parentheses. In
-a color specification the individual specifications must be separated using a
-semicolon, which may be followed by a whitespace (like a space or a newline).
-Individual specifications must be given in increasing order.
-
-\subsubsection{Color models}
-
-\noindent\emph{by David Purton}
-
-An attempt is made to produce shadings consistent with the currently selected
-|xcolor| package color model. The |rgb|, |cmyk|, and |gray| color models from
-the |xcolor| package are supported.
-
-\textbf{Note:} The color model chosen for a shading is based on the |xcolor|
-color model \emph{at the time the shading is created}. This is either when
-\cs{pgfdeclare*shading} is called with no optional argument or when
-\cs{pgfuseshading} is called if \cs{pgfdeclare*shading} was called with an
-optional argument.
-
-If the |xcolor| package |natural| color model is in use then the shading color
-model will be \textsc{rgb} by default. In practice this means that if you are
-using the |natural| color model of the |xcolor| package you can get mismatched
-colors if you, for example, create a shading from green (which is defined as
-\textsc{rgb}) to magenta (which is defined as \textsc{cmyk}). The shading will
-finish with \textsc{rgb} magenta which will look different to the
-\textsc{cmyk} magenta used in solid colors.
-
-You can avoid mismatched colors by loading the |xcolor| package first with an
-explicit color model (|rgb|, |cmyk|, or |gray|).
-
-\begin{codeexample}[code only]
-\begin{tikzpicture}
- \fill[green] (0,0) rectangle (1,1);
- \shade[left color=green, right color=magenta] (1.25,0) rectangle (3.75,1);
- \fill[magenta] (4,0) rectangle (5,1);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{center}
- \begin{minipage}{5cm}
- |xcolor| |natural| color model:\medskip
-
- \begin{tikzpicture}
- \fill[green] (0,0) rectangle (1,1);
- \shade[left color=green, right color=magenta] (1.25,0) rectangle (3.75,1);
- \fill[magenta] (4,0) rectangle (5,1);
- \end{tikzpicture}
- \end{minipage}\hspace{2cm}%
- \begin{minipage}{5cm}
- |xcolor| |cmyk| color model:\medskip
-
- \selectcolormodel{cmyk}
- \begin{tikzpicture}
- \fill[green] (0,0) rectangle (1,1);
- \shade[left color=green, right color=magenta] (1.25,0) rectangle (3.75,1);
- \fill[magenta] (4,0) rectangle (5,1);
- \end{tikzpicture}
- \end{minipage}\medskip
-
- \begin{minipage}{5cm}
- |xcolor| |rgb| color model:\medskip
-
- \selectcolormodel{rgb}
- \begin{tikzpicture}
- \fill[green] (0,0) rectangle (1,1);
- \shade[left color=green, right color=magenta] (1.25,0) rectangle (3.75,1);
- \fill[magenta] (4,0) rectangle (5,1);
- \end{tikzpicture}
- \end{minipage}\hspace{2cm}%
- \begin{minipage}{5cm}
- |xcolor| |gray| color model:\medskip
-
- \selectcolormodel{gray}
- \begin{tikzpicture}
- \fill[green] (0,0) rectangle (1,1);
- \shade[left color=green, right color=magenta] (1.25,0) rectangle (3.75,1);
- \fill[magenta] (4,0) rectangle (5,1);
- \end{tikzpicture}
- \end{minipage}
-\end{center}
-
-\subsection{Declaring Shadings}
-
-\subsubsection{Horizontal and Vertical Shadings}
-
-\begin{command}{\pgfdeclarehorizontalshading\oarg{color list}\marg{shading name}\marg{shading height}\marg{color specification}}
- Declares a horizontal shading named \meta{shading name} of the specified
- \meta{height} with the specified colors. The width of the bar is deduced
- automatically from the maximum dimension in the specification.
- %
-\begin{codeexample}[]
-\pgfdeclarehorizontalshading{myshadingA}
- {1cm}{rgb(0cm)=(1,0,0); color(2cm)=(green); color(4cm)=(blue)}
-\pgfuseshading{myshadingA}
-\end{codeexample}
-
- The effect of the \meta{color list}, which is a comma-separated list of
- colors, is the following: Normally, when this list is empty, once a shading
- has been declared, it becomes ``frozen''. This means that even if you
- change a color that was used in the declaration of the shading later on,
- the shading will not change. By specifying a \meta{color list} you can
- specify that the shading should be recalculated whenever one of the colors
- listed in the list changes (this includes effects like color mixins and
- |xcolor| color models). Thus, when you specify a \meta{color list},
- whenever the shading is used, \pgfname\ first converts the colors in the
- list to tuples in the current |xcolor| color model using the current
- values of the colors and taking any mixins and blends into account. If the
- resulting tuples have not yet been used,
- a new shading is internally created and used. Note that if the option
- \meta{color list} is used, then no shading is created until the first use
- of |\pgfuseshading|. In particular, the colors mentioned in the shading
- need not be defined when the declaration is given.
-
- When a shading is recalculated because of a change in the colors mentioned
- in \meta{color list}, the complete shading is recalculated. Thus even
- colors not mentioned in the list will be used with their current values,
- not with the values they had upon declaration.
- %
-\begin{codeexample}[]
-\pgfdeclarehorizontalshading[mycolor]{myshadingB}
- {1cm}{rgb(0cm)=(1,0,0); color(2cm)=(mycolor)}
-\colorlet{mycolor}{green}
-\pgfuseshading{myshadingB}
-\colorlet{mycolor}{blue}
-\pgfuseshading{myshadingB}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfdeclareverticalshading\oarg{color list}\marg{shading name}\marg{shading width}\marg{color specification}}
- Declares a vertical shading named \meta{shading name} of the specified
- \meta{width}. The height of the bar is deduced automatically. The effect of
- \meta{color list} is the same as for horizontal shadings.
- %
-\begin{codeexample}[]
-\pgfdeclareverticalshading{myshadingC}
- {4cm}{rgb(0cm)=(1,0,0); rgb(1.5cm)=(0,1,0); rgb(2cm)=(0,0,1)}
-\pgfuseshading{myshadingC}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Radial Shadings}
-
-\begin{command}{\pgfdeclareradialshading\oarg{color list}\marg{shading name}\marg{center point}\marg{color specification}}
- Declares a radial shading. A radial shading is a circle whose inner color
- changes as specified by the color specification. Assuming that the center
- of the shading is at the origin, the color of the center will be the color
- specified for 0cm and the color of the border of the circle will be the
- color for the maximum dimension given in the \meta{color specified}. This
- maximum will also be the radius of the circle. If the \meta{center point}
- is not at the origin, the whole shading inside the circle (whose size
- remains exactly the same) will be distorted such that the given center now
- has the color specified for 0cm. The effect of \meta{color list} is the
- same as for horizontal shadings.
- %
-\begin{codeexample}[]
-\pgfdeclareradialshading{sphere}{\pgfpoint{0.5cm}{0.5cm}}%
- {rgb(0cm)=(0.9,0,0);
- rgb(0.7cm)=(0.7,0,0);
- rgb(1cm)=(0.5,0,0);
- rgb(1.05cm)=(1,1,1)}
-\pgfuseshading{sphere}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{General (Functional) Shadings}
-
-\begin{command}{\pgfdeclarefunctionalshading\oarg{color list}\marg{shading
- name}\marg{lower left corner}\marg{upper right corner}\\
- \marg{init code}\marg{type 4 function}%
-}
- \emph{Warning: These shadings are the least portable of all and they put
- the heaviest burden of the renderer. They are slow and, possibly, will not
- print correctly!}
-
- This command creates a \emph{functional shading}. For such a shading, the
- color of each point is calculated by calling a function that takes the
- coordinates of the point as input and yields the color as an output. Note
- that the function is evaluated by the \emph{renderer}, not by \pgfname\ or
- \TeX\ or someone else at compile-time. This means that the evaluation of
- this function has to be done \emph{extremely quickly} and the function
- should be \emph{very simple}. For this reason, only a very restricted set
- of operations are possible in the function and functions should be kept
- small. Any errors in the function will only be noticed by the renderer.
-
- The syntax for specifying functions is the following: You use a simplified
- form of a subset of the PostScript language. This subset will be understood
- by the PDF-renderer (yes, PDF-renderers do have a basic understanding of
- PostScript) and also by PostScript renders. This subset is detailed in
- Section~3.9.4 of the PDF-specification (version~1.7). In essence, the
- specification states that these functions may contain ``expressions
- involving integers, real numbers, and boolean values only. There are no
- composite data structures such as strings or arrays, no procedures, and no
- variables or names.'' The allowed operators are (exactly) the following:
- \texttt{abs}, \texttt{add}, \texttt{atan}, \texttt{ceiling}, \texttt{cos},
- \texttt{cvi}, \texttt{cvr}, \texttt{div}, \texttt{exp}, \texttt{floor},
- \texttt{idiv}, \texttt{ln}, \texttt{log}, \texttt{mod}, \texttt{mul},
- \texttt{neg}, \texttt{round}, \texttt{sin}, \texttt{sqrt}, \texttt{sub},
- \texttt{truncate}, \texttt{and}, \texttt{bitshift}, \texttt{eq},
- \texttt{false}, \texttt{ge}, \texttt{gt}, \texttt{le}, \texttt{lt},
- \texttt{ne}, \texttt{not}, \texttt{or}, \texttt{true}, \texttt{xor},
- \texttt{if}, \texttt{ifelse}, \texttt{copy}, \texttt{dup}, \texttt{exch},
- \texttt{index}, \texttt{pop}.
-
- When the function is evaluated, the top two stack elements are the
- coordinates of the point for which the color should be computed. The
- coordinates are dimensionless and given in big points, so for the
- coordinate $(50bp, 72.27pt)$ the top two stack elements would be
- \texttt{50.0} and \texttt{72.0}. Otherwise, the (virtual) stack is empty
- (or should be treated as if it were empty). The function should then
- replace these two values by three values, representing the red, green, and
- blue color of the point for an \textsc{rgb} shading, four colors,
- representing the cyan, magenta, yellow, and black color of the point for a
- \textsc{cmyk} shading, or one value representing the gray color for a
- grayscale shading. The numbers should be real values, not integers
- since, Apple's PDF renderer is broken in this regard (use \texttt{cvr} at
- the end if necessary).
-
- Conceptually, the function will be evaluated once for each point of the
- rectangle \meta{lower left corner} to \meta{upper right corner}, which
- should be a \pgfname-point expression like |\pgfpoint{100bp}{100bp}|. A
- renderer may choose to evaluate the function at less points, but, in
- principle, the function will be evaluated for each pixel independently.
-
- Because of the rather difficult PostScript syntax, use this macro only
- \emph{if you know what you are doing} (or if you are adventurous, of
- course).
-
- As for other shadings, the optional \meta{color list} is used to determine
- whether a shading needs to be recalculated when a color has changed.
-
- The \meta{init code} is executed each time a shading is (re)calculated.
- Typically, it will contain code to extract coordinates from colors.
- %
-\begin{codeexample}[]
-\pgfdeclarefunctionalshading{twospots}
- {\pgfpointorigin}{\pgfpoint{4cm}{4cm}}{}{
- % Save coordinates for later
- 2 copy
- % Compute distance from (40bp,45bp), with x doubled
- 45 sub dup mul exch
- 40 sub dup mul 0.5 mul add sqrt
- % exponential decay
- dup mul neg 1.0005 exch exp 1.0 exch sub
- % Compute distance from (70bp,70bp) from stored coordinate, scaled
- 3 1 roll
- 70 sub dup mul .5 mul exch
- 70 sub dup mul add sqrt
- % Decay
- dup mul neg 1.002 exch exp 1.0 exch sub
- % red component
- 1.0 3 1 roll
-}
-\pgfuseshading{twospots}
-\end{codeexample}
-
- Inside the PostScript function \meta{type 4 function} you cannot use colors
- directly. Rather, you must push the color components on the stack. For
- this, it is useful to call one of |\pgfshadecolortorgb|,
- |\pgfshadecolortocmyk|, or |\pgfshadecolortogray| in the \meta{init code}:
-
- \begin{command}{\pgfshadecolortorgb\marg{color name}\marg{macro}}
- This command takes \meta{color name} as input, converts it to
- \textsc{rgb} and stores the color's
- red/green/blue components real numbers between 0.0 and 1.0 separated by
- spaces (which is exactly what you need if you want to push it on a
- stack) in \meta{macro}. This macro can then be used inside the
- \meta{type 4 function} argument for |\pgfdeclarefunctionalshading|.
- %
-\begin{codeexample}[]
-\pgfdeclarefunctionalshading[mycol]{sweep}{\pgfpoint{-1cm}{-1cm}}
-{\pgfpoint{1cm}{1cm}}{\pgfshadecolortorgb{mycol}{\myrgb}}{
- 2 copy % whirl
- % Calculate "safe" atan of position
- 2 copy abs exch abs add 0.0001 ge { atan } { pop } ifelse
- 3 1 roll
- dup mul exch
- dup mul add sqrt
- 30 mul
- add
- sin
- 1 add 2 div
- dup
- \myrgb % push mycol
- 5 4 roll % multiply all components by calculated value
- mul
- 3 1 roll
- 3 index
- mul
- 3 1 roll
- 4 3 roll
- mul
- 3 1 roll
-}
-\colorlet{mycol}{white}%
-\pgfuseshading{sweep}%
-\colorlet{mycol}{red}%
-\pgfuseshading{sweep}
-\end{codeexample}
-
- In addition, three macros suffixed with |red|, |green| and |blue| are
- defined, which store the individual components of \meta{color name}.
- These can also be used in the \meta{type 4 function} argument.
- %
-\begin{codeexample}[]
-\pgfshadecolortorgb{orange}{\mycol}
-|\mycol|=\mycol |\mycolred|=\mycolred |\mycolgreen|=\mycolgreen |\mycolblue|=\mycolblue
-\end{codeexample}
- \end{command}
-
-\begin{codeexample}[]
-\pgfdeclarefunctionalshading[col1,col2,col3,col4]{bilinear interpolation}
-{\pgfpointorigin}{\pgfpoint{100bp}{100bp}}
-{
-\pgfshadecolortorgb{col1}{\first}\pgfshadecolortorgb{col2}{\second}
-\pgfshadecolortorgb{col3}{\third}\pgfshadecolortorgb{col4}{\fourth}
-}{
- 100 div exch 100 div 2 copy % Calculate y/100 x/100.
- neg 1 add exch neg 1 add % Calculate 1-y/100 1-x/100.
- 3 1 roll 2 copy exch 5 2 roll 6 copy 6 copy % Set up stack.
- \firstred mul exch \secondred mul add mul % Process red component.
- 4 1 roll
- \thirdred mul exch \fourthred mul add mul
- add
- 13 1 roll
- \firstgreen mul exch \secondgreen mul add mul % Process green component.
- 4 1 roll
- \thirdgreen mul exch \fourthgreen mul add mul
- add
- 7 1 roll
- \firstblue mul exch \secondblue mul add mul % Process blue component.
- 4 1 roll
- \thirdblue mul exch \fourthblue mul add mul
- add
-}
-
-\colorlet{col1}{blue}
-\colorlet{col2}{yellow}
-\colorlet{col3}{red}
-\colorlet{col4}{green}
-\pgfuseshading{bilinear interpolation}
-\end{codeexample}
-
- \begin{command}{\pgfshadecolortocmyk\marg{color name}\marg{macro}}
- This command takes \meta{color name} as input, converts it to
- \textsc{cmyk} and stores the color's cyan/magenta/yellow/black
- components real numbers between 0.0 and 1.0 separated by spaces.
-
- In addition, four macros suffixed with |cyan|, |magenta|, |yellow| and
- |black| are defined, which store the individual components of
- \meta{color name}.
- %
- \end{command}
-
- \begin{command}{\pgfshadecolortogray\marg{color name}\marg{macro}}
- This command takes \meta{color name} as input converts it to grayscale
- and stores the color's value as a real number between 0.0 and 1.0.
-
- Although it's not needed, for consistency a second macro suffixed with
- |gray| is also defined.
- %
- \end{command}
- %
-\end{command}
-
-\paragraph{Color model independent functional shadings.}
-
-By nature, the PostScript code used in functional shadings must output one of
-\textsc{rgb}, \textsc{cmyk}, or grayscale data. Therefore,
-\cs{pgfdeclarefunctionalshading} is \emph{not} portable across color models.
-
-Take particular care that the same color model is in use at declaration time
-and use time for functional shadings declared with an optional argument as
-otherwise the PostScript data will not match the declared color space and
-you will end up with a malformed PDF.
-
-Having said this, it \emph{is} possible to create portable functional shadings
-by providing conditional code to append color transformations to the
-PostScript data. A variety of \cs{pgffuncshading*to*} (e.g.,
-\cs{pgffuncshadingrgbtocmyk}) macros along with \cs{ifpgfshadingmodel*} (e.g.,
-\cs{ifpgfshadingmodelcmyk}) conditionals are provided to assist with these
-transformations. Obviously, this will make the PostScript code less efficient
-than if you work in your intended color model.
-
-\pgfdeclarefunctionalshading[black]{portabletwospots}
- {\pgfpointorigin}{\pgfpoint{3.5cm}{3.5cm}}{}{
- 2 copy
- 45 sub dup mul exch
- 40 sub dup mul 0.5 mul add sqrt
- dup mul neg 1.0005 exch exp 1.0 exch sub
- 3 1 roll
- 70 sub dup mul .5 mul exch
- 70 sub dup mul add sqrt
- dup mul neg 1.002 exch exp 1.0 exch sub
- 1.0 3 1 roll
- \ifpgfshadingmodelcmyk
- \pgffuncshadingrgbtocmyk
- \fi
- \ifpgfshadingmodelgray
- \pgffuncshadingrgbtogray
- \fi
-}
-\begin{center}
- \begin{minipage}{3.5cm}
- |xcolor| |rgb| model:\medskip
-
- \selectcolormodel{rgb}
- \pgfuseshading{portabletwospots}
- \end{minipage}\hspace{2cm}
- \begin{minipage}{3.5cm}
- |xcolor| |cmyk| model:\medskip
-
- \selectcolormodel{cmyk}
- \pgfuseshading{portabletwospots}
- \end{minipage}\hspace{2cm}
- \begin{minipage}{3.5cm}
- |xcolor| |gray| model:\medskip
-
- \selectcolormodel{gray}
- \pgfuseshading{portabletwospots}
- \end{minipage}
-\end{center}
-
-\begin{codeexample}[code only]
-\pgfdeclarefunctionalshading[black]{portabletwospots}{\pgfpointorigin}{\pgfpoint{3.5cm}{3.5cm}}{}{
- 2 copy
- 45 sub dup mul exch
- 40 sub dup mul 0.5 mul add sqrt
- dup mul neg 1.0005 exch exp 1.0 exch sub
- 3 1 roll
- 70 sub dup mul .5 mul exch
- 70 sub dup mul add sqrt
- dup mul neg 1.002 exch exp 1.0 exch sub
- 1.0 3 1 roll
- \ifpgfshadingmodelcmyk
- \pgffuncshadingrgbtocmyk
- \fi
- \ifpgfshadingmodelgray
- \pgffuncshadingrgbtogray
- \fi
-}
-\end{codeexample}
-
-\begin{command}{\pgffuncshadingrgbtocmyk}
- Within the \meta{type 4 function} argument of
- \cs{pgfdeclarefunctionalshading}, this command can be used to convert the
- top 3 elements on the stack from \textsc{rgb} to \textsc{cmyk}. In
- combination with the \cs{ifpgfshadingmodelcmyk} conditional this macro can
- be used to make functional shading declarations more portable across color
- models.
-\end{command}
-
-\begin{command}{\pgffuncshadingrgbtogray}
- Within the \meta{type 4 function} argument of
- \cs{pgfdeclarefunctionalshading}, this command can be used to convert the
- top 3 elements on the stack from \textsc{rgb} to grayscale. In combination
- with the \cs{ifpgfshadingmodelgray} conditional this macro can be used to
- make functional shading declarations more portable across color models.
-\end{command}
-
-\begin{command}{\pgffuncshadingcmyktorgb}
- Within the \meta{type 4 function} argument of
- \cs{pgfdeclarefunctionalshading}, this command can be used to convert the
- top 4 elements on the stack from \textsc{cmyk} to \textsc{rgb}. In
- combination with the \cs{ifpgfshadingmodelrgb} conditional this macro can be
- used to make functional shading declarations more portable across color
- models.
-\end{command}
-
-\begin{command}{\pgffuncshadingcmyktogray}
- Within the \meta{type 4 function} argument of
- \cs{pgfdeclarefunctionalshading}, this command can be used to convert the
- top 4 elements on the stack from \textsc{cmyk} to grayscale. In combination
- with the \cs{ifpgfshadingmodelgray} conditional this macro can be used to
- make functional shading declarations more portable across color models.
-\end{command}
-
-\begin{command}{\pgffuncshadinggraytorgb}
- Within the \meta{type 4 function} argument of
- \cs{pgfdeclarefunctionalshading}, this command can be used to convert the
- top element on the stack from grayscale to \textsc{rgb}. In combination with
- the \cs{ifpgfshadingmodelrgb} conditional this macro can be used to make
- functional shading declarations more portable across color models.
-\end{command}
-
-\begin{command}{\pgffuncshadinggraytocmyk}
- Within the \meta{type 4 function} argument of
- \cs{pgfdeclarefunctionalshading}, this command can be used to convert the
- top element on the stack from grayscale to \textsc{cmyk}. In combination
- with the \cs{ifpgfshadingmodelcmyk} conditional this macro can be used to
- make functional shading declarations more portable across color models.
-\end{command}
-
-{\let\ifpgfshadingmodelrgb=\relax
- \let\ifpgfshadingmodelcmyk=\relax
- \let\ifpgfshadingmodelgray=\relax
- \begin{command}{\ifpgfshadingmodelrgb}
- Within the \meta{type 4 function} argument of
- \cs{pgfdeclarefunctionalshading}, this command can be used to test if the
- |xcolor| color model is |rgb| \emph{at the time the shading is created}.
- This can be used to ensure that the data output in the \meta{type 4
- function} correctly matches the active color model.
- \end{command}
-
- \begin{command}{\ifpgfshadingmodelcmyk}
- Within the \meta{type 4 function} argument of
- \cs{pgfdeclarefunctionalshading}, this command can be used to test if the
- |xcolor| color model is |cmyk| \emph{at the time the shading is created}.
- This can be used to ensure that the data output in the \meta{type 4
- function} correctly matches the active color model.
- \end{command}
-
- \begin{command}{\ifpgfshadingmodelgray}
- Within the \meta{type 4 function} argument of
- \cs{pgfdeclarefunctionalshading}, this command can be used to test if the
- |xcolor| color model is |gray| \emph{at the time the shading is created}.
- This can be used to ensure that the data output in the \meta{type 4
- function} correctly matches the active color model.
- \end{command}
-}
-
-\subsection{Using Shadings}
-\label{section-shading-a-path}
-
-\begin{command}{\pgfuseshading\marg{shading name}}
- Inserts a previously declared shading into the text. If you wish to use it
- in a |pgfpicture| environment, you should put a |\pgftext| around it.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfdeclareverticalshading{myshadingD}
- {20pt}{color(0pt)=(red); color(20pt)=(blue)}
- \pgftext[at=\pgfpoint{1cm}{0cm}] {\pgfuseshading{myshadingD}}
- \pgftext[at=\pgfpoint{2cm}{0.5cm}]{\pgfuseshading{myshadingD}}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfshadepath\marg{shading name}\marg{angle}}
- This command must be used inside a |{pgfpicture}| environment. The effect
- is a bit complex, so let us go over it step by step.
-
- First, \pgfname\ will set up a local scope.
-
- Second, it uses the current path to clip everything inside this scope.
- However, the current path is once more available after the scope, so it can
- be used, for example, to stroke it.
-
- Now, the \meta{shading name} should be a shading whose width and height are
- 100\,bp, that is, 100 big points. \pgfname\ has a look at the bounding box
- of the current path. This bounding box is computed automatically when a
- path is computed; however, it can sometimes be (quite a bit) too large,
- especially when complicated curves are involved.
-
- Inside the scope, the low-level transformation matrix is modified. The
- center of the shading is translated (moved) such that it lies on the center
- of the bounding box of the path. The low-level coordinate system is also
- scaled such that the shading ``covers'' the path (the details are a bit
- more complex, see below). Then, the coordinate system is rotated by
- \meta{angle}. Finally, if the macro |\pgfsetadditionalshadetransform| has
- been used, an additional transformation is applied.
-
- After everything has been set up, the shading is inserted. Due to the
- transformations and clippings, the effect will be that the shading seems
- to ``fill'' the path.
-
- If both the path and the shadings were always rectangles and if rotations
- were never involved, it would be easy to scale shadings such they always
- cover the path. However, when a vertical shading is rotated, it must
- obviously be ``magnified'' so that it still covers the path. Things get
- worse when the path is not a rectangle itself.
-
- For these reasons, things work slightly differently ``in reality''. The
- shading is scaled and translated such that the point
- $(50\mathrm{bp},50\mathrm{bp})$, which is the middle of the shading, is at
- the middle of the path and such that the point
- $(25\mathrm{bp},25\mathrm{bp})$ is at the lower left corner of the path and
- that $(75\mathrm{bp},75\mathrm{bp})$ is at upper right corner.
-
- In other words, only the center quarter of the shading will actually
- ``survive the clipping'' if the path is a rectangle. If the path is not a
- rectangle, but, say, a circle, even less is seen of the shading. Here is an
- example that demonstrates this effect:
- %
-\begin{codeexample}[]
-\pgfdeclareverticalshading{myshadingE}{100bp}
- {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)}
-\pgfuseshading{myshadingE}
-\hskip 1cm
-\begin{pgfpicture}
- \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
- \pgfshadepath{myshadingE}{0}
- \pgfusepath{stroke}
- \pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{1cm}{2cm}}
- \pgfshadepath{myshadingE}{0}
- \pgfusepath{stroke}
- \pgfpathrectangle{\pgfpoint{5cm}{0cm}}{\pgfpoint{2cm}{2cm}}
- \pgfshadepath{myshadingE}{45}
- \pgfusepath{stroke}
- \pgfpathcircle{\pgfpoint{9cm}{1cm}}{1cm}
- \pgfshadepath{myshadingE}{45}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
-
- As can be seen above in the last case, the ``hidden'' part of the shading
- actually \emph{can} become visible if the shading is rotated. The reason is
- that it is scaled as if no rotation took place, then the rotation is done.
-
- The following graphics show which part of the shading are actually shown:
- %
-\begin{codeexample}[]
-\pgfdeclareverticalshading{myshadingF}{100bp}
- {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)}
-\begin{tikzpicture}
- \draw (50bp,50bp) node {\pgfuseshading{myshadingF}};
- \draw[white,thick] (25bp,25bp) rectangle (75bp,75bp);
- \draw (50bp,0bp) node[below] {first two applications};
-
- \begin{scope}[xshift=5cm]
- \draw (50bp,50bp) node{\pgfuseshading{myshadingF}};
- \draw[rotate around={45:(50bp,50bp)},white,thick] (25bp,25bp) rectangle (75bp,75bp);
- \draw (50bp,0bp) node[below] {third application};
- \end{scope}
-
- \begin{scope}[xshift=10cm]
- \draw (50bp,50bp) node{\pgfuseshading{myshadingF}};
- \draw[white,thick] (50bp,50bp) circle (25bp);
- \draw (50bp,0bp) node[below] {fourth application};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
- An advantage of this approach is that when you rotate a radial shading, no
- distortion is introduced:
- %
-\begin{codeexample}[]
-\pgfdeclareradialshading{ballshading}{\pgfpoint{-10bp}{10bp}}
- {color(0bp)=(red!15!white); color(9bp)=(red!75!white);
- color(18bp)=(red!70!black); color(25bp)=(red!50!black); color(50bp)=(black)}
-\pgfuseshading{ballshading}
-\hskip 1cm
-\begin{pgfpicture}
- \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
- \pgfshadepath{ballshading}{0}
- \pgfusepath{}
- \pgfpathcircle{\pgfpoint{3cm}{0cm}}{1cm}
- \pgfshadepath{ballshading}{0}
- \pgfusepath{}
- \pgfpathcircle{\pgfpoint{6cm}{0cm}}{1cm}
- \pgfshadepath{ballshading}{45}
- \pgfusepath{}
-\end{pgfpicture}
-\end{codeexample}
-
- If you specify a rotation of $90^\circ$ and if the path is not a square,
- but an elongated rectangle, the ``desired'' effect results: The shading
- will exactly vary between the colors at the 25bp and 75bp boundaries. Here
- is an example:
- %
-\begin{codeexample}[]
-\pgfdeclareverticalshading{myshadingG}{100bp}
- {color(0bp)=(red); color(25bp)=(green); color(75bp)=(blue); color(100bp)=(black)}
-\begin{pgfpicture}
- \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
- \pgfshadepath{myshadingG}{0}
- \pgfusepath{stroke}
- \pgfpathrectangle{\pgfpoint{3cm}{0cm}}{\pgfpoint{2cm}{1cm}}
- \pgfshadepath{myshadingG}{90}
- \pgfusepath{stroke}
- \pgfpathrectangle{\pgfpoint{6cm}{0cm}}{\pgfpoint{2cm}{1cm}}
- \pgfshadepath{myshadingG}{45}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
-
- As a final example, let us define a ``rainbow spectrum'' shading for use
- with \tikzname.
- %
-\begin{codeexample}[]
-\pgfdeclareverticalshading{rainbow}{100bp}
- {color(0bp)=(red); color(25bp)=(red); color(35bp)=(yellow);
- color(45bp)=(green); color(55bp)=(cyan); color(65bp)=(blue);
- color(75bp)=(violet); color(100bp)=(violet)}
-\begin{tikzpicture}[shading=rainbow]
- \shade (0,0) rectangle node[white] {\textsc{pride}} (2,1);
- \shade[shading angle=90] (3,0) rectangle +(1,2);
-\end{tikzpicture}
-\end{codeexample}
-
- Note that rainbow shadings are \emph{way} too colorful in almost all
- applications.
-\end{command}
-
-\begin{command}{\pgfsetadditionalshadetransform\marg{transformation}}
- This command allows you to specify an additional transformation that should
- be applied to shadings when the |\pgfshadepath| command is used. The
- \meta{transformation} should be transformation code like
- |\pgftransformrotate{20}|.
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-transformations.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-transformations.tex
deleted file mode 100644
index afc5ed3d1d..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-transformations.tex
+++ /dev/null
@@ -1,1246 +0,0 @@
-% 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{Coordinate, Canvas, and Nonlinear Transformations}
-
-\subsection{Overview}
-
-\pgfname\ offers different ways of scaling, shifting, and rotating (these
-operations are generally known as \emph{transformations}) graphics: You can
-apply \emph{coordinate transformations} to all coordinates, you can apply
-\emph{canvas transformations} to the canvas on which you draw, and you can
-apply \emph{additional nonlinear transformations}. (The names ``coordinate''
-and ``canvas'' transformations are not standard, I introduce them only for the
-purposes of this manual.)
-
-The differences are the following:
-%
-\begin{itemize}
- \item As the name ``coordinate transformation'' suggests, coordinate
- transformations apply only to coordinates. For example, when you
- specify a coordinate like |\pgfpoint{1cm}{2cm}| and you wish to ``use''
- this coordinate -- for example as an argument to a |\pgfpathmoveto|
- command -- then the coordinate transformation matrix is applied to the
- coordinate, resulting in a new coordinate. Continuing the example, if
- the current coordinate transformation is ``scale by a factor of two'',
- the coordinate |\pgfpoint{1cm}{2cm}| actually designates the point
- $(2\mathrm{cm},4\mathrm{cm})$.
-
- Note that coordinate transformations apply \emph{only} to coordinates.
- They do not apply to, say, line width or shadings or text.
- \item The effect of a ``canvas transformation'' like ``scale by a factor of
- two'' can be imagined as follows: You first draw your picture on a
- ``rubber canvas'' normally. Then, once you are done, the whole canvas
- is transformed, in this case stretched by a factor of two. In the
- resulting image \emph{everything} will be larger: Text, lines,
- coordinates, and shadings.
- \item Nonlinear transformations are a special form of coordinate
- transformations that are, as the name suggests, not linear. The support
- for nonlinear transformations is quite different from the support for
- linear coordinate transformations, the main reason being speed: While
- linear coordinate transformations can be applied very quickly
- (\pgfname\ does so almost constantly), nonlinear transformations are
- much harder to apply and also to use. For this reason, nonlinear
- transformations are implemented in a special module
- |nonlineartransformations| that has to be loaded explicitly. By
- default, they are not available.
-\end{itemize}
-
-In many cases, it is preferable that you use coordinate transformations and not
-canvas transformations. When canvas transformations are used, \pgfname\ looses
-track of the coordinates of nodes and shapes. Also, canvas transformations
-often cause undesirable effects like changing text size. For these reasons,
-\pgfname\ makes it easy to setup the coordinate transformation, but a bit
-harder to change the canvas transformation. Because of the speed penalties
-caused by nonlinear transformations, they are even harder to set up.
-
-
-\subsection{Coordinate Transformations}
-\label{section-linear-coordinate-transformations}
-
-\subsubsection{How PGF Keeps Track of the Coordinate Transformation Matrix}
-\label{section-transform-cm}
-
-\pgfname\ has an internal coordinate transformation matrix. This matrix is
-applied to coordinates ``in certain situations''. This means that the matrix is
-not always applied to every coordinate ``no matter what''. Rather, \pgfname\
-tries to be reasonably smart at when and how this matrix should be applied. The
-most prominent examples are the path construction commands, which apply the
-coordinate transformation matrix to their inputs.
-
-The coordinate transformation matrix consists of four numbers $a$, $b$, $c$,
-and $d$, and two dimensions $s$ and $t$. When the coordinate transformation
-matrix is applied to a coordinate $(x,y)$, the new coordinate
-$(ax+cy+s,bx+dy+t)$ results. For more details on how transformation matrices
-work in general, please see, for example, the \textsc{pdf} or PostScript
-reference or a textbook on computer graphics.
-
-The coordinate transformation matrix is equal to the identity matrix at the
-beginning. More precisely, $a=1$, $b=0$, $c=0$, $d=1$, $s=0\mathrm{pt}$, and
-$t=0\mathrm{pt}$.
-
-The different coordinate transformation commands will modify the matrix by
-concatenating it with another transformation matrix. This way the effect of
-applying several transformation commands will \emph{accumulate}.
-
-The coordinate transformation matrix is local to the current \TeX\ group
-(unlike the canvas transformation matrix, which is local to the current
-|{pgfscope}|). Thus, the effect of adding a coordinate transformation to the
-coordinate transformation matrix will last only till the end of the current
-\TeX\ group.
-
-
-\subsubsection{Commands for Relative Coordinate Transformations}
-
-The following commands add a basic coordinate transformation to the current
-coordinate transformation matrix. For all commands, the transformation is
-applied \emph{in addition} to any previous coordinate transformations.
-
-\begin{command}{\pgftransformshift\marg{point}}
- Shifts coordinates by \meta{point}.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (2,1) -- (1,0);
- \pgftransformshift{\pgfpoint{1cm}{1cm}}
- \draw[red] (0,0) -- (2,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransformxshift\marg{dimensions}}
- Shifts coordinates by \meta{dimension} along the $x$-axis.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (2,1) -- (1,0);
- \pgftransformxshift{.5cm}
- \draw[red] (0,0) -- (2,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransformyshift\marg{dimensions}}
- Like |\pgftransformxshift|, only for the $y$-axis.
-\end{command}
-
-\begin{command}{\pgftransformscale\marg{factor}}
- Scales coordinates by \meta{factor}.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (2,1) -- (1,0);
- \pgftransformscale{.75}
- \draw[red] (0,0) -- (2,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransformxscale\marg{factor}}
- Scales coordinates by \meta{factor} in the $x$-direction.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (2,1) -- (1,0);
- \pgftransformxscale{.75}
- \draw[red] (0,0) -- (2,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransformyscale\marg{factor}}
- Like |\pgftransformxscale|, only for the $y$-axis.
-\end{command}
-
-\begin{command}{\pgftransformxslant\marg{factor}}
- Slants coordinates by \meta{factor} in the $x$-direction. Here, a factor of
- |1| means $45^\circ$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (2,1) -- (1,0);
- \pgftransformxslant{.5}
- \draw[red] (0,0) -- (2,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransformyslant\marg{factor}}
- Slants coordinates by \meta{factor} in the $y$-direction.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (2,1) -- (1,0);
- \pgftransformyslant{-1}
- \draw[red] (0,0) -- (2,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\begin{command}{\pgftransformrotate\marg{angles}}
- Rotates coordinates counterclockwise by \meta{angles} given in degrees.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (2,1) -- (1,0);
- \pgftransformrotate{30}
- \draw[red] (0,0) -- (2,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransformtriangle\marg{a}\marg{b}\marg{c}}
- This command transforms the coordinate system in such a way that the
- triangle given by the points \meta{a}, \meta{b} and \meta{c} lies at the
- coordinates $(0,0)$, $(1\mathrm{pt},0\mathrm{pt})$ and
- $(0\mathrm{pt},1\mathrm{pt})$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgftransformtriangle
- {\pgfpoint{1cm}{0cm}}
- {\pgfpoint{0cm}{2cm}}
- {\pgfpoint{3cm}{1cm}}
-
- \draw (0,0) -- (1pt,0pt) -- (0pt,1pt) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransformcm\marg{a}\marg{b}\marg{c}\marg{d}\marg{point}}
- Applies the transformation matrix given by $a$, $b$, $c$, and $d$ and the
- shift \meta{point} to coordinates (in addition to any previous
- transformations already in force).
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (2,1) -- (1,0);
- \pgftransformcm{1}{1}{0}{1}{\pgfpoint{.25cm}{.25cm}}
- \draw[red] (0,0) -- (2,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransformarrow\marg{start}\marg{end}}
- Shifts coordinates to the end of the line going from \meta{start} to
- \meta{end} with the correct rotation.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (3,1);
- \pgftransformarrow{\pgfpointorigin}{\pgfpoint{3cm}{1cm}}
- \pgftext{tip}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransformlineattime\marg{time}\marg{start}\marg{end}}
- Shifts coordinates by a specific point on a line at a specific time. The
- point by which the coordinate is shifted is calculated by calling
- |\pgfpointlineattime|, see Section~\ref{section-pointsattime}.
-
- In addition to shifting the coordinate, a rotation \emph{may} also be
- applied. Whether this is the case depends on whether the \TeX\ if
- |\ifpgfslopedattime| is set to true or not.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (2,1);
- \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
- \pgftext{Hi!}
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (2,1);
- \pgfslopedattimetrue
- \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
- \pgftext{Hi!}
-\end{tikzpicture}
-\end{codeexample}
- %
- If |\ifpgfslopedattime| is true, another \TeX\ |\if| is important:
- |\ifpgfallowupsidedowattime|. If this is false, \pgfname\ will ensure that
- the rotation is done in such a way that text is never ``upside down''.
-
- There is another \TeX\ |\if| that influences this command. If you set
- |\ifpgfresetnontranslationattime| to true, then, between shifting the
- coordinate and (possibly) rotating/sloping the coordinate, the command
- |\pgftransformresetnontranslations| is called. See the description of this
- command for details.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgftransformscale{1.5}
- \draw (0,0) -- (2,1);
- \pgfslopedattimetrue
- \pgfresetnontranslationattimefalse
- \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
- \pgftext{Hi!}
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgftransformscale{1.5}
- \draw (0,0) -- (2,1);
- \pgfslopedattimetrue
- \pgfresetnontranslationattimetrue
- \pgftransformlineattime{.25}{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
- \pgftext{Hi!}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransformcurveattime\marg{time}\marg{start}\marg{first support}\marg{second support}\marg{end}}
- Shifts coordinates by a specific point on a curve at a specific time, see
- Section~\ref{section-pointsattime} once more.
-
- As for the line-at-time transformation command, |\ifpgfslopedattime|
- decides whether an additional rotation should be applied. Again, the value
- of |\ifpgfallowupsidedowattime| is also considered.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) .. controls (0,2) and (1,2) .. (2,1);
- \pgftransformcurveattime{.25}{\pgfpointorigin}
- {\pgfpoint{0cm}{2cm}}{\pgfpoint{1cm}{2cm}}{\pgfpoint{2cm}{1cm}}
- \pgftext{Hi!}
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) .. controls (0,2) and (1,2) .. (2,1);
- \pgfslopedattimetrue
- \pgftransformcurveattime{.25}{\pgfpointorigin}
- {\pgfpoint{0cm}{2cm}}{\pgfpoint{1cm}{2cm}}{\pgfpoint{2cm}{1cm}}
- \pgftext{Hi!}
-\end{tikzpicture}
-\end{codeexample}
- %
- The value of |\ifpgfresetnontranslationsattime| is also taken into account.
-\end{command}
-
-\begin{command}{\pgftransformarcaxesattime\marg{time
- $t$}\marg{center}\marg{0-degree axis}\marg{90-degree
- axis}\marg{start angle}\marg{end angle}%
-}
- Shifts coordinates by a specific point on an arc at a specific time, see
- Section~\ref{section-pointsattime} once more.
-
- As for the previous commands, |\ifpgfslopedattime| decides whether an
- additional rotation should be applied and |\ifpgfallowupsidedowattime| is
- also considered.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfpathmoveto{\pgfpoint{2cm}{1cm}}
- \pgfpatharcaxes{0}{60}{\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}}
- \pgfusepath{stroke}
- \pgfslopedattimetrue
- \pgftransformarcaxesattime{.25}
- {\pgfpoint{0cm}{1cm}}
- {\pgfpoint{2cm}{0cm}}{\pgfpoint{0cm}{1cm}}
- {0}{60}
- \pgftext{Hi!}
-\end{tikzpicture}
-\end{codeexample}
- %
- The value of |\ifpgfresetnontranslationsattime| is also taken into account.
-\end{command}
-
-{
- \let\ifpgfslopedattime=\relax
- \begin{textoken}{\ifpgfslopedattime}
- Decides whether the ``at time'' transformation commands also rotate
- coordinates or not.
- \end{textoken}
-}
-{
- \let\ifpgfallowupsidedowattime=\relax
- \begin{textoken}{\ifpgfallowupsidedowattime}
- Decides whether the ``at time'' transformation commands should allow
- the rotation be done in such a way that ``upside-down text'' can
- result.
- \end{textoken}
-}
-{
- \let\ifpgfresetnontranslationsattime=\relax
- \begin{textoken}{\ifpgfresetnontranslationsattime}
- Decides whether the ``at time'' transformation commands should reset
- the non-translations between shifting and rotating.
- \end{textoken}
-}
-
-
-\subsubsection{Commands for Absolute Coordinate Transformations}
-
-The coordinate transformation commands introduced up to now are always applied
-in addition to any previous transformations. In contrast, the commands
-presented in the following can be used to change the transformation matrix ``in
-absolute terms''. Note that this is, in general, dangerous and will often
-produce unexpected effects. You should use these commands only if you really
-know what you are doing.
-
-\begin{command}{\pgftransformreset}
- Resets the coordinate transformation matrix to the identity matrix. Thus,
- once this command is given no transformations are applied till the end of
- the scope.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgftransformrotate{30}
- \draw (0,0) -- (2,1) -- (1,0);
- \pgftransformreset
- \draw[red] (0,0) -- (2,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransformresetnontranslations}
- This command sets the $a$, $b$, $c$, and $d$ part of the coordinate
- transformation matrix to $a=1$, $b=0$, $c=0$, and $d=1$. However, the
- current shifting of the matrix is not modified.
-
- The effect of this command is that any rotation/scaling/slanting is undone
- in the current \TeX\ group, but the origin is not ``moved back''.
-
- This command is mostly useful directly before a |\pgftext| command to
- ensure that the text is not scaled or rotated.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgftransformscale{2}
- \pgftransformrotate{30}
- \pgftransformxshift{1cm}
- {\color{red}\pgftext{rotated}}
- \pgftransformresetnontranslations
- \pgftext{shifted only}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgftransforminvert}
- Replaces the coordinate transformation matrix by a coordinate
- transformation matrix that ``exactly undoes the original transformation''.
- For example, if the original transformation was ``scale by 2 and then shift
- right by 1cm'' the new one is ``shift left by 1cm and then scale by
- $1/2$''.
-
- This command will produce an error if the determinant of the matrix is too
- small, that is, if the matrix is near-singular.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgftransformrotate{30}
- \draw (0,0) -- (2,1) -- (1,0);
- \pgftransforminvert
- \draw[red] (0,0) -- (2,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Saving and Restoring the Coordinate Transformation Matrix}
-
-There are two commands for saving and restoring coordinate transformation
-matrices.
-
-\begin{command}{\pgfgettransform\marg{macro}}
- This command will (locally) define \meta{macro} to a representation of the
- current coordinate transformation matrix. This matrix can later on be
- reinstalled using |\pgfsettransform|.
-\end{command}
-
-\begin{command}{\pgfsettransform\marg{macro}}
- Reinstalls a coordinate transformation matrix that was previously saved
- using |\pgfgettransform|.
-\end{command}
-
-\begin{command}{\pgfgettransformentries\marg{macro for a}\marg{macro
- for b}\marg{macro for c}\marg{macro for d}\marg{macro for shift
- x}\marg{macro for shift y}%
-}
- This command is similar to |\pgfgettransform| except that it stores the
- current coordinate transformation matrix in a set of six macros.
-
- The matrix can later on be reinstalled using |\pgfsettransformentries|.
- Furthermore, all these macros (or just a few of them) can be used as
- arguments for |\pgftransformcm|.
-\end{command}
-
-\begin{command}{\pgfsettransformentries\marg{a}\marg{b}\marg{c}\marg{d}\marg{shiftx}\marg{shifty}}
- Reinstalls a coordinate transformation matrix that was previously saved
- using the storage command |\pgfgettransformentries|. This command can also
- be used to replace any previously existing coordinate transformation matrix
- (it is thus equivalent to |\pgftransformreset| followed by
- |\pgftransformcm|).
-\end{command}
-
-
-\subsubsection{Applying Coordinate Transformation to Points}
-
-\begin{command}{\pgfpointtransformed\marg{point}}
- Applies current transformation matrix to \marg{point} $(x,y)$ and returns a
- transformed point $(ax+cy+s,bx+dy+t)$. Normally, this is done automatically
- by commands like |\pgfpathlineto| or |\pgfpathmoveto|, but sometimes you
- may wish to access a transformed point yourself.
-\end{command}
-
-
-\subsubsection{Computing Adjustments for Coordinate Transformations}
-\label{section-adjustment-transformations}
-
-\begin{command}{\pgftransformationadjustments}
- This command computes ``adjustments'' for the current transformation matrix
- so that even when you install a transformation matrix that scales
- everything by a certain factor, you can still draw something of ``an
- absolute size''. Suppose for instance that you install a transformation
- matrix that scales everything by a factor of 4 and you now wish to draw a
- horizontal line of length 1cm. Then, if you do not reset the transformation
- matrix, you can draw a line of logical length 2.5mm, which will then get
- scaled to a line of 1cm. Things get more difficult in case you scale things
- only, say, vertically. In this case, the adjustment necessary for
- horizontal lines is different from the one needed for vertical lines.
-
- This function computes two scaling factors, one for horizontal lines
- and one for vertical lines, and stores them in the following macros:
- %
- \begin{command}{\pgfhorizontaltransformationadjustment}
- When you scale the length of a horizontal line by this factor in the
- current transformation, you compensate for the scaling. Formally, it is
- $1/\|\mathit{transform}(1,0)\|_2$, where $\mathit{transform}$ applies
- the current transformations matrix to the given number.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (2,2);
- \begin{scope}[xscale=2,thick]
- \draw [red] (1,1) -- ++(1,0);
-
- \pgftransformationadjustments
- \draw [blue] (1,0) -- ++(\pgfhorizontaltransformationadjustment,0);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (2,2);
- \begin{scope}[xscale=2,thick,rotate=90]
- \draw [red] (1,1) -- ++(1,0);
-
- \pgftransformationadjustments
- \draw [blue] (1,0) -- ++(\pgfhorizontaltransformationadjustment,0);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
- \end{command}
- %
- \begin{command}{\pgfverticaltransformationadjustment}
- $1/\|\mathit{transform}(0,1)\|_2$.
- \end{command}
-
- Note that the ``right'' way to draw a line of absolute length 1cm in a
- transformed coordinate system is to first compute the start point and to
- then reset the transformation matrix. The transformation adjustments
- computed here are important only in situations where you cannot do this,
- for instance when an |outer xsep| must be set.
-\end{command}
-
-
-\subsection{Canvas Transformations}
-
-The canvas transformation matrix is not managed by \pgfname, but by the output
-format like \pdf\ or PostScript. All that \pgfname\ does is to call appropriate
-low-level |\pgfsys@| commands to change the canvas transformation matrix.
-
-Unlike coordinate transformations, canvas transformations apply to
-``everything'', including images, text, shadings, line thickness, and so on.
-The idea is that a canvas transformation really stretches and deforms the
-canvas after the graphic is finished.
-
-Unlike coordinate transformations, canvas transformations are local to the
-current |{pgfscope}|, not to the current \TeX\ group. This is due to the fact
-that they are managed by the backend driver, not by \TeX\ or \pgfname.
-
-Unlike the coordinate transformation matrix, it is not possible to ``reset''
-the canvas transformation matrix. The only way to change it is to concatenate
-it with another canvas transformation matrix or to end the current
-|{pgfscope}|.
-
-Unlike coordinate transformations, \pgfname\ does not ``keep track'' of canvas
-transformations. In particular, it will not be able to correctly save the
-coordinates of shapes or nodes when a canvas transformation is used.
-
-
-\subsubsection{Applying General Canvas Transformations}
-
-\pgfname\ does not offer many commands for modifying the canvas transformation
-matrix. Instead, different commands allow you to concatenate the canvas
-transformation matrix with a coordinate transformation matrix (and there are
-numerous commands for specifying a coordinate transformation, see the previous
-section).
-
-\begin{command}{\pgflowlevelsynccm}
- This command concatenates the canvas transformation matrix with the current
- coordinate transformation matrix. Afterward, the coordinate transformation
- matrix is reset.
-
- The effect of this command is to ``synchronize'' the coordinate
- transformation matrix and the canvas transformation matrix. All
- transformations that were previously applied by the coordinate
- transformations matrix are now applied by the canvas transformation matrix.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfsetlinewidth{1pt}
- \pgftransformscale{5}
- \draw (0,0) -- (0.4,.2);
- \pgftransformxshift{0.2cm}
- \pgflowlevelsynccm
- \draw[red] (0,0) -- (0.4,.2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgflowlevel\marg{transformation code}}
- This command concatenates the canvas transformation matrix with the
- coordinate transformation specified by \meta{transformation code}.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfsetlinewidth{1pt}
- \pgflowlevel{\pgftransformscale{5}}
- \draw (0,0) -- (0.4,.2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgflowlevelobj\marg{transformation code}\marg{code}}
- This command creates a local |{pgfscope}|. Inside this scope,
- |\pgflowlevel| is first called with the argument \meta{transformation
- code}, then the \meta{code} is inserted.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfsetlinewidth{1pt}
- \pgflowlevelobj{\pgftransformscale{5}} {\draw (0,0) -- (0.4,.2);}
- \pgflowlevelobj{\pgftransformxshift{-1cm}}{\draw (0,0) -- (0.4,.2);}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{environment}{{pgflowlevelscope}\marg{transformation code}}
- This environment first surrounds the \meta{environment contents} by a
- |{pgfscope}|. Then it calls |\pgflowlevel| with the argument
- \meta{transformation code}.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \pgfsetlinewidth{1pt}
- \begin{pgflowlevelscope}{\pgftransformscale{5}}
- \draw (0,0) -- (0.4,.2);
- \end{pgflowlevelscope}
- \begin{pgflowlevelscope}{\pgftransformxshift{-1cm}}
- \draw (0,0) -- (0.4,.2);
- \end{pgflowlevelscope}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{environment}
-
-\begin{plainenvironment}{{pgflowlevelscope}\marg{transformation code}}
- Plain \TeX\ version of the environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{pgflowlevelscope}\marg{transformation code}}
- Con\TeX t version of the environment.
-\end{contextenvironment}
-
-
-\subsubsection{Establishing View Boxes}
-\label{section-base-view}
-
-A \emph{view box} is like a ``window'' through which you see a graphic. To
-establish a view box, you specify a rectangle -- which is the window -- and
-another rectangle surrounding the to-be-viewed graphic. The graphic will then
-be rescaled and shifted in such a way that the to-be-viewed rectangle matches
-the view box's rectangle as well as possible. Note that establishing a view box
-does, indeed, cause a canvas transformation to be installed.
-
-View boxes are only seldom needed in normal graphics. Their main application is
-with animations since you can \emph{animate} the to-be-viewed rectangle. This
-makes it easy to create animations in which you zoom in, zoom out, and pan a
-graphic.
-
-\begin{environment}{{pgfviewboxscope}\marg{$ll_1$}\marg{$ur_1$}\marg{$ll_2$}\marg{$ur_2$}\marg{meet or slice}}
- Inside the viewbox scope, the source rectangle (with the two \pgfname\
- points $ll_1$ and $ur_1$ as corners) will be translated and scaled so that
- it becomes centered on the target rectangle (with the corners $ll_2$ and
- $ur_2$) and will, for |meet| as last parameter, be as large as possible so
- that it fits inside the target and, for |slice|, be as small as possible so
- that it encompasses the target.
- %
-\begin{codeexample}[]
-\tikz {
- \draw [red, very thick] (0,0) rectangle (20mm,20mm);
- \begin{pgfviewboxscope}
- {\pgfpoint{5mm}{5mm}}{\pgfpoint{25mm}{15mm}} % Source
- {\pgfpoint{0mm}{0mm}}{\pgfpoint{20mm}{20mm}} % Target
- {meet}
- \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
- \draw [thick] (1,1) circle [radius=8mm] node {Hi};
- \end{pgfviewboxscope} }
-\end{codeexample}
- %
-\begin{codeexample}[]
-\tikz {
- \draw [red, very thick] (0,0) rectangle (20mm,20mm);
- \begin{pgfviewboxscope}
- {\pgfpoint{5mm}{5mm}}{\pgfpoint{25mm}{15mm}} % Source
- {\pgfpoint{0mm}{0mm}}{\pgfpoint{20mm}{20mm}} % Target
- {slice}
- \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
- \draw [thick] (1,1) circle [radius=8mm] node {Hi};
- \end{pgfviewboxscope} }
-\end{codeexample}
- %
-\end{environment}
-
-\begin{plainenvironment}{{pgfviewboxscope}\marg{$ll_1$}\marg{$ur_1$}\marg{$ll_2$}\marg{$ur_2$}\marg{meet or slice}}
- Plain \TeX\ version of the environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{pgfviewboxscope}\marg{$ll_1$}\marg{$ur_1$}\marg{$ll_2$}\marg{$ur_2$}\marg{meet or slice}}
- Con\TeX t version of the environment.
-\end{contextenvironment}
-
-
-\subsection{Nonlinear Transformations}
-\label{section-nonlinear-transformations}
-
-In order to use nonlinear transformations, you first have to load the following
-\pgfname\ module:
-
-\begin{pgfmodule}{nonlineartransformations}
- Loads the necessary functionality for nonlinear transformations.
-\end{pgfmodule}
-
-
-\subsubsection{Introduction}
-
-The difference between the coordinate transformations introduced in
-Section~\ref{section-linear-coordinate-transformations} above to nonlinear
-transformations is, of course, that the transformations can be nonlinear. An
-example of a nonlinear transformation is the transformation underlying polar
-coordinates: A polar coordinate $(r,d)$ gets transformed to the canvas position
-$(d\cos r,d\sin r)$, which is clearly not a linear transformation.
-
-Nonlinear transformations work somewhat like the normal linear coordinate
-transformations in the sense that they apply to coordinate and thereby to the
-construction of paths, but not to things like text or line width or shadings.
-(Indeed, it is not possible to apply nonlinear transformations to, say, text.)
-
-This means that there is a fundamental difference between, on the one hand,
-calling a function like |\pgfpointpolar| or specifying a coordinate as |(45:2)|
-in \tikzname\ and, on the other hand, installing the nonlinear transformation
-``polar coordinates'' using the command |\pgftransformnonlinear|: In a
-coordinate like |(45:2)| the user explicitly says ``please evaluate this one
-coordinate in polar coordinate and then continue in the normal coordinate
-system with the result''. Otherwise nothing changes and a line between two
-points specified in this way is still a straight line.
-
-Things are quite different when we install a polar \emph{transformation} using
-|\pgftransformnonlinear|. Now, even a seemingly low-level Cartesian coordinate
-|\pgfqpoint{1pt}{1pt}| will get transformed. Even more drastically, what is
-specified as a straight line like
-%
-\begin{codeexample}[code only]
-\draw (0,1) -- (1,1);
-\end{codeexample}
-%
-can become curved since \emph{everything} gets transformed.
-
-
-\subsubsection{Installing Nonlinear Transformation}
-
-\begin{codeexample}[setup code,hidden]
-\makeatletter
-\def\polartransformation{
- % \pgf@x will contain the radius
- % \pgf@y will contain the distance
- \pgfmathsincos@{\pgf@sys@tonumber\pgf@x}%
- % pgfmathresultx is now the cosine of radius and
- % pgfmathresulty is the sine of radius
- \pgf@x=\pgfmathresultx\pgf@y%
- \pgf@y=\pgfmathresulty\pgf@y%
-}
-\makeatother
-\end{codeexample}
-
-\begin{command}{\pgftransformnonlinear\marg{transformation code}}
- This command adds the \meta{transformation code} to the list of non-linear
- transformations currently in force. Thus, similar to linear coordinate
- transformations, each additional call to this function adds another
- transformation to the current \TeX\ scope and the effect ends at the end of
- the current scope. In practice, however, you typically will not have more
- than one active nonlinear transformation.
-
- The job of the \meta{transformation code} is to map a point~$p$ given in
- the registers |\pgf@x| and |\pgf@y| to a new coordinate~$f(p)$, which
- should be returned in |\pgf@x| and |\pgf@y| as well. As an example, suppose
- we wish to install polar coordinates as the nonlinear transformation. For
- this, we need a bit of code:
- %
-\begin{codeexample}[code only]
-\def\polartransformation{%
- % \pgf@x will contain the radius
- % \pgf@y will contain the distance
- \pgfmathsincos@{\pgf@sys@tonumber\pgf@x}%
- % pgfmathresultx is now the cosine of radius and
- % pgfmathresulty is the sine of radius
- \pgf@x=\pgfmathresultx\pgf@y%
- \pgf@y=\pgfmathresulty\pgf@y%
-}
-\end{codeexample}
- %
- (In case you wonder why you cannot just call |\pgfpointpolar| at this
- point: You can, but this function internally uses |\pgf@x| and |\pgf@y| in
- complicated ways, so you would first have to safe them so some other
- registers. Also, the above is faster.)
-
- If we were to call this function again, we would get something funny like
- ``polar-polar coordinates'', so let's not do this. Let us instead have a
- look at the effect this call has: Once a nonlinear transformation is
- installed, all subsequent path constructions are affected by this
- transformation. In particular, a normal grid now becomes the typical
- ``polar grid''.
- %
-\begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- % Start nonlinear transformation
- \pgftransformnonlinear{\polartransformation}% see above
-
- % Draw something with this transformation in force
- \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Applying Nonlinear Transformations to Points}
-
-\begin{command}{\pgfpointtransformednonlinear\marg{point}}
- Works like |\pgfpointtransformed|, but also applies the current nonlinear
- transformation; that is, it first applies the current linear transformation
- and then the current nonlinear transformations. Note that, just like
- |\pgfpointtransformed|, you normally do not call this function directly
- since it is called internally by the path drawing commands.
-\end{command}
-
-
-\subsubsection{Applying Nonlinear Transformations to Paths}
-
-When a nonlinear transformation is installed, the normal path construction
-commands like |\pgfpathmoveto| get adjusted so that the ``honour'' the
-nonlinear transformations currently in force. For |\pgfpathmoveto| this is
-pretty simple: Instead of just applying the linear transformation matrix to the
-point to which the path should ``jump'' next, we also apply the nonlinear
-transformation. However, for a command like |\pgfpathlineto|, things are much
-more difficult: A straight line will no longer be a straight line!
-
-In order to make straight lines ``bend'', the following changes are in force
-while a nonlinear transformation is installed:
-%
-\begin{enumerate}
- \item Whenever a straight line between two points $p$ and $q$ should be
- added to the path, either through |\pgfpathlineto| or through
- |\pgfpathclose|, we replace this straight line by a ``degenerated
- curve'' from $p$ to $q$ whose control points are at one third and two
- third of the distance between $p$ and $q$ on the line between $p$ and
- $q$. In this way, while nonlinear transformations are in force, we only
- need to transform curves.
- \item Next, suppose we wish to transform a curve from $p$ to $q$ with
- supports $s$ and $t$. For this, we simply apply the nonlinear
- transformation $f$ to all four points and draw a line with the results.
- Note that this mapping is actually not quite satisfactory for long
- lines that are strongly curved:
- %
-\begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- {
- \pgftransformnonlinear{\polartransformation}
- % The curve with the controls computed by pgf: a nice quarter arc
- \draw [red] (0,20mm) -- (90pt,20mm);
- }
- % Here is the curve with controls just transformed:
- \draw (0:20mm) .. controls (30pt:20mm) and (60pt:20mm) .. (90pt:20mm);
-\end{tikzpicture}
-\end{codeexample}
- %
- As the example shows, the control points now lie on the arc; but in
- reality they should point along the tangents at the start and the end.
- This is exactly when \pgfname\ does through the computation described
- above.
- \item To overcome the effect of the control points being ``off'', it is
- necessary to split up longer curves into smaller parts, which are drawn
- individually to increase the accuracy. When such splitting occurs, can
- be configured using the following command:
- %
- \begin{command}{\pgfsettransformnonlinearflatness\marg{dimension} (initially 5pt)}
- Whenever in a to-be-drawn curve the $L^\infty$-distance (maximum of
- the distances in $x$- and $y$-directions) between the start of a
- curve and its first control point or between the first and second
- control points or between the second control point and the end is
- more than \meta{distance}, the curve gets split in the middle (more
- precisely, at time $t= 0.5$) and we draw the two parts individually
- (for them, splitting may occur again, if the curve is still too
- long).
- %
-\begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- \draw[red] (0:20mm) arc [start angle=0, end angle=90, radius=2cm];
- {
- \pgftransformnonlinear{\polartransformation}
- \pgfsettransformnonlinearflatness{2pt} % very precise
- \draw (0,20mm) -- (90pt,20mm);
- }
-\end{tikzpicture}
-\end{codeexample}
- \end{command}
-\end{enumerate}
-
-
-\subsubsection{Applying Nonlinear Transformations to Text}
-
-Earlier, it was pointed that nonlinear transformations do not apply to text.
-Nevertheless, when you use |\pgftext| or |\pgfnode|, \pgfname\ will do a sort
-of ``best effort'' to render the text in the nonlinear coordinate system: The
-point where the text should be shown can obviously be computed easily. When
-then temporarily reset the nonlinear transformation and, instead, setup a
-linear transformation that matches the nonlinear transformation at the point
-where the text should be. Then, the text is shown. This means that if the text
-is longer, it will not ``follow'' the nonlinear transformation, but near the
-origin of the text it will look ``correct''. As an example, let us add some
-text at the grid point of the above example:
-%
-\begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- \pgftransformnonlinear{\polartransformation}% see above
-
- % Draw something with this transformation in force
- \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm);
-
- \foreach \angle in {0,30,60,90}
- \foreach \dist in {1,2}
- {
- \pgftransformshift{\pgfpoint{\angle pt}{\dist cm}}
- \pgftext{\angle$^\circ$}
- }
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{Approximating Nonlinear Transformations Using Linear Transformations}
-
-At any given point, the current nonlinear transformation can be approximated
-using a linear transformation. The following two functions allow you to install
-such a local approximation:
-
-\begin{command}{\pgfapproximatenonlineartransformation}
- This command will do two things:
- %
- \begin{enumerate}
- \item It clears the nonlinear transformations for the rest of the
- current \TeX\ scope, so only linear transformations apply.
- \item However, before removing the nonlinear transformations, the
- linear transformation matrix is modified so that it mimics the
- effect the nonlinear transformation had at the origin. That is,
- after you call this command, drawing something near the origin will
- look almost the same as if you had not called it.
- \end{enumerate}
- %
-\begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- \pgftransformnonlinear{\polartransformation}% see above
- \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm);
-
- \begin{scope}[shift={(45pt,20mm)}]
- % Draw something near "origin":
- \draw [red] (-10pt,-10pt) -- (10pt,10pt);
- \draw [red] (10pt,-10pt) -- (-10pt,10pt);
-
- % Now draw the same, but in the "approximate" coordinate system:
- \pgfapproximatenonlineartransformation
- \draw [] (-10pt,-10pt) -- (10pt,10pt);
- \draw [] (10pt,-10pt) -- (-10pt,10pt);
- \pgftext{foo};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
- %
- This command is used by |\pgftext| and |\pgfnode| to transform text when a
- nonlinear transformation is in force.
-\end{command}
-
-\begin{command}{\pgfapproximatenonlineartranslation}
- This command works like the normal approximation command, but it will only
- approximate how the origin gets translated, it will not approximate the
- rotation, skewing, or scaling that is involved. This is useful for drawing
- text at the right position, but without ``mutilating'' the text.
- %
-\begin{codeexample}[preamble={\usepgfmodule{nonlineartransformations}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- \pgftransformnonlinear{\polartransformation}% see above
- \draw (0pt,0mm) grid [xstep=10pt, ystep=5mm] (90pt, 20mm);
-
- \begin{scope}[shift={(45pt,20mm)}]
- % Draw something near "origin":
- \draw [red] (-10pt,-10pt) -- (10pt,10pt);
- \draw [red] (10pt,-10pt) -- (-10pt,10pt);
-
- % Now draw the same, but in the "approximate" coordinate system:
- \pgfapproximatenonlineartranslation
- \draw [] (-10pt,-10pt) -- (10pt,10pt);
- \draw [] (10pt,-10pt) -- (-10pt,10pt);
- \pgftext{foo};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Nonlinear Transformation Libraries}
-\label{section-library-curvilinear}
-
-\begin{pgflibrary}{curvilinear}
- This library defines commands for computing nonlinear transformations
- ``along Bézier curves''.
-\end{pgflibrary}
-
-Up to now, our running example for a nonlinear transformation was polar
-transformation. However, is \pgfname\ nonlinear transformations are
-\emph{actually} mainly used for transforming arrow tips; and these need to be
-transformed ``along curves''. The |curvilinear| library defines a number of
-commands that offer the necessary computations for such transformations.
-
-\begin{command}{\pgfsetcurvilinearbeziercurve\marg{start}\marg{first support}\marg{second support}\marg{end}}
- Prior to using any other command from this library, you first call this
- function to ``install'' a Bézier curve to which the commands will refer.
- This curve will be local to the current \TeX\ scope and you can install
- only one curve at a time.
-
- The main job of this command is to store the passed points internally and
- to build a lookup table for distance-to-time conversions, see the next
- command.
- %
-\begin{codeexample}[code only]
-\pgfsetcurvilinearbeziercurve
- {\pgfpointorigin}
- {\pgfpoint{1cm}{1cm}}
- {\pgfpoint{2cm}{1cm}}
- {\pgfpoint{3cm}{0cm}}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfcurvilineardistancetotime\marg{distance}}
- This command does a ``distance-to-time-conversion'': It tries to compute a
- time $t$, returned in |\pgf@x|, that corresponds to travelling
- \meta{distance} along the curve that has last been installed using the
- command |\pgfsetcurvilinearbeziercurve|. The distance-to-time-conversion
- uses the precomputations done by that command. Note that several
- compromises had to be made between speed and accuracy:
- %
- \begin{itemize}
- \item The conversion will be best near the start of the curve.
- \item The more ``degenerate'' the curve, the worse the results.
- \end{itemize}
-\end{command}
-
-\begin{command}{\pgfpointcurvilinearbezierorthogonal\marg{distance}\marg{offset}}
- This command computes the following point: Consider the curve last
- installed using the command |\pgfsetcurvilinearbeziercurve|. We travel
- along this curve by \meta{distance}, arriving at a point $p$. Then, we turn
- by $90^\circ$ and travel by \meta{offset} units ``always from the curve'',
- arriving at a point $q$. This point $q$ will now be returned in |\pgf@x|
- and |\pgf@y|; furthermore, the transformed local coordinate system at point
- $q$ will also be returned |\pgf@xa| and the other registers, see
- |\pgftransformnonlinear| for details.
- %
-\makeatletter
-\begin{codeexample}[
- preamble={\usepgfmodule{nonlineartransformations}
-\usetikzlibrary{curvilinear}},
- pre=\makeatletter]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- {
- \pgfsetcurvilinearbeziercurve
- {\pgfpoint{0mm}{20mm}}
- {\pgfpoint{11mm}{20mm}}
- {\pgfpoint{20mm}{11mm}}
- {\pgfpoint{20mm}{0mm}}
- \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}%
- \draw (0,-30pt) grid [step=10pt] (80pt,30pt);
- }
- \draw[red, very thick]
- (0mm,20mm) .. controls (11mm,20mm) and (20mm,11mm) .. (20mm,0mm);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[
- preamble={\usepgfmodule{nonlineartransformations}
-\usetikzlibrary{curvilinear}},
- pre=\makeatletter]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- {
- \pgfsetcurvilinearbeziercurve
- {\pgfpoint{0mm}{20mm}}
- {\pgfpoint{10mm}{20mm}}
- {\pgfpoint{10mm}{10mm}}
- {\pgfpoint{20mm}{10mm}}
- \pgftransformnonlinear{\pgfpointcurvilinearbezierorthogonal\pgf@x\pgf@y}%
- \draw (0,-30pt) grid [step=10pt] (80pt,30pt);
- }
- \draw[red, very thick]
- (0mm,20mm) .. controls (10mm,20mm) and (10mm,10mm) .. (20mm,10mm);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfpointcurvilinearbezierpolar\marg{x}\marg{y}}
- This command is similar to the previous version, but the transformation is
- different: The idea is that a line form $(0,0)$ to $(x,0)$ gets transformed
- to the curve from the start of the curve to a point at distance $x$ along
- the curve. This is identical to what the ``orthogonal'' transformation
- above also does. The difference is that a line from $(0,0)$ to $(0,y)$ gets
- still transformed to an initial segment of the curve of a length of $y$,
- but now rotated by $90^\circ$. In general, the point $p = (x,y)$ gets
- transferred to a point that at distance $|p| = \sqrt{x^2+y^2}$ along the
- curve, but rotated by the angle of $p$ relative to the $x$-axis.
-
- All of these computations mainly have the following effect: Two straight
- lines from the start of the curve as in a |Straight Barb| arrow tip get
- transformed to an initial segment of the curve whose length is the length
- of the two lines, but this segment gets rotated by the angle of the two
- lines.
- %
-\makeatletter
-\begin{codeexample}[
- preamble={\usepgfmodule{nonlineartransformations}
-\usetikzlibrary{curvilinear}},
- pre=\makeatletter]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- {
- \pgfsetcurvilinearbeziercurve
- {\pgfpoint{0mm}{20mm}}
- {\pgfpoint{11mm}{20mm}}
- {\pgfpoint{20mm}{11mm}}
- {\pgfpoint{20mm}{0mm}}
- \pgftransformnonlinear{\pgfpointcurvilinearbezierpolar\pgf@x\pgf@y}%
- \draw (0,-30pt) grid [step=10pt] (80pt,30pt);
- % Add a "barb":
- \draw [blue, very thick] (20pt,10pt) -- (0,0) -- (20pt,-10pt);
- }
- \draw[red, very thick]
- (0mm,20mm) .. controls (11mm,20mm) and (20mm,11mm) .. (20mm,0mm);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[
- preamble={\usepgfmodule{nonlineartransformations}
-\usetikzlibrary{curvilinear}},
- pre=\makeatletter]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- {
- \pgfsetcurvilinearbeziercurve
- {\pgfpoint{0mm}{20mm}}
- {\pgfpoint{10mm}{20mm}}
- {\pgfpoint{10mm}{10mm}}
- {\pgfpoint{20mm}{10mm}}
- \pgftransformnonlinear{\pgfpointcurvilinearbezierpolar\pgf@x\pgf@y}%
- \draw (0,-30pt) grid [step=10pt] (80pt,30pt);
- % Add a "barb":
- \draw [blue, very thick] (20pt,10pt) -- (0,0) -- (20pt,-10pt);
- }
- \draw[red, very thick]
- (0mm,20mm) .. controls (10mm,20mm) and (10mm,10mm) .. (20mm,10mm);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
-
-% LocalWords: nonlineartransformations PGF cx dy pdf PostScript pgfscope xstep
-% LocalWords: Reinstalls shiftx backend pgflowlevelscope ystep ezier lookup xa
-% LocalWords: precomputations
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-transparency.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-base-transparency.tex
deleted file mode 100644
index de9c874ed0..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-base-transparency.tex
+++ /dev/null
@@ -1,391 +0,0 @@
-% 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{Transparency}
-\label{section-transparency}
-
-For an introduction to the notion of transparency, fadings, and transparency
-groups, please consult Section~\ref{section-tikz-transparency}.
-
-
-\subsection{Specifying a Uniform Opacity}
-
-Specifying a stroke and/or fill opacity is quite easy.
-
-\begin{command}{\pgfsetstrokeopacity\marg{value}}
- Sets the opacity of stroking operations. The \meta{value} should be a
- number between |0| and |1|, where |1| means ``fully opaque'' and |0| means
- ``fully transparent''. A value like |0.5| will cause paths to be stroked in
- a semitransparent way.
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfsetlinewidth{5mm}
- \color{red}
- \pgfpathcircle{\pgfpoint{0cm}{0cm}}{10mm} \pgfusepath{stroke}
- \color{black}
- \pgfsetstrokeopacity{0.5}
- \pgfpathcircle{\pgfpoint{1cm}{0cm}}{10mm} \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetfillopacity\marg{value}}
- Sets the opacity of filling operations. As for stroking, the \meta{value}
- should be a number between |0| and~|1|.
-
- The ``filling transparency'' will also be used for text and images.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \pgfsetfillopacity{0.5}
- \fill[red] (90:1cm) circle (11mm);
- \fill[green] (210:1cm) circle (11mm);
- \fill[blue] (-30:1cm) circle (11mm);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-Note the following effect: If you set up a certain opacity for stroking or
-filling and you stroke or fill the same area twice, the effect accumulates:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \pgfsetfillopacity{0.5}
- \fill[red] (0,0) circle (1);
- \fill[red] (1,0) circle (1);
-\end{tikzpicture}
-\end{codeexample}
-
-Often, this is exactly what you intend, but not always. You can use
-transparency groups, see the end of this section, to change this.
-
-
-\subsection{Specifying a Blend Mode}
-
-To set the blend mode, use the following command:
-
-\begin{command}{\pgfsetblendmode\marg{mode}}
- Sets the blend mode to one of the values described in
- Section~\ref{section-blend-modes}. As described there, blend modes are an
- advanced feature of \textsc{pdf} and not always rendered correctly.
- %
-\begin{codeexample}[]
-\tikz [transparency group] {
- \pgfsetblendmode{screen}
-
- \fill[red!90!black] ( 90:.6) circle (1);
- \fill[green!80!black] (210:.6) circle (1);
- \fill[blue!90!black] (330:.6) circle (1);
-}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Specifying a Fading}
-
-The method used by \pgfname\ for specifying fadings is quite general: You
-``paint'' the fading using any of the standard graphics commands. In more
-detail: You create a normal picture, which may even contain text, image, and
-shadings. Then, you create a fading based on this picture. For this, the
-\emph{luminosity} of each pixel of the picture is analyzed (the brighter the
-pixel, the higher the luminosity -- a black pixel has luminosity $0$, a white
-pixel has luminosity $1$, a gray pixel has some intermediate value as does a
-red pixel). Then, when the fading is used, the luminosity of the pixel
-determines the opacity of the fading at that position. Positions in the fading
-where the picture was black will be completely transparent, positions where the
-picture was white will be completely opaque. Positions that have not been
-painted at all in the picture are always completely transparent.
-
-\begin{command}{\pgfdeclarefading\marg{name}\marg{contents}}
- This command declares a fading named \meta{name} for later use. The
- ``picture'' on which the fading is based is given by the \meta{contents}.
- The \meta{contents} are normally typeset in a \TeX\ box. The resulting box
- is then used as the ``picture''. In particular, inside the \meta{contents}
- you must explicitly open a |{pgfpicture}| environment if you wish to use
- \pgfname\ commands.
-
- Let's start with an easy example. Our first fading picture is just some
- text:
- %
-\begin{codeexample}[]
-\pgfdeclarefading{fading1}{\textcolor{white}{Ti\emph{k}Z}}
-\begin{tikzpicture}
- \fill [black!20] (0,0) rectangle (2,2);
- \fill [black!30] (0,0) arc (180:0:1);
- \pgfsetfading{fading1}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
- \fill [red] (0,0) rectangle (2,2);
-\end{tikzpicture}
-\end{codeexample}
- %
- What's happening here? The ``fading picture'' is mostly transparent, except
- for the pixels that are part of the word Ti\emph{k}Z. Now, these pixels are
- \emph{white} and, thus, have a high luminosity. This in turn means that
- these pixels of the fading will be highly opaque. For this reason, only
- those pixels of the big red rectangle ``shine through'' that are at the
- positions of these opaque pixels.
-
- It is somewhat counter-intuitive that the white pixels in a fading picture
- are opaque in a fading. For this reason, the color |pgftransparent| is
- defined to be the same as |black|. This allows one to write
- |pgftransparent| for completely transparent parts of a fading picture and
- |pgftransparent!0| for the opaque parts and things like |pgftransparent!20|
- for parts that are 20\% transparent.
-
- Furthermore, the color |pgftransparent!0| (which is the same as white and
- which corresponds to completely opaque) is installed at the beginning of a
- fading picture. Thus, in the above example the |\color{white}| was not
- really necessary.
-
- Next, let us create a fading that gets more and more transparent as we go
- from left to right. For this, we put a shading inside the fading picture
- that has the color |pgftransparent!0| at the left-hand side and the color
- |pgftransparent!100| at the right-hand side.
- %
-\begin{codeexample}[]
-\pgfdeclarefading{fading2}
-{\tikz \shade[left color=pgftransparent!0,
- right color=pgftransparent!100] (0,0) rectangle (2,2);}
-\begin{tikzpicture}
- \fill [black!20] (0,0) rectangle (2,2);
- \fill [black!30] (0,0) arc (180:0:1);
- \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
- \fill [red] (0,0) rectangle (2,2);
-\end{tikzpicture}
-\end{codeexample}
-
- In our final example, we create a fading that is based on a radial shading.
- %
-\begin{codeexample}[]
-\pgfdeclareradialshading{myshading}{\pgfpointorigin}
-{
- color(0mm)=(pgftransparent!0);
- color(5mm)=(pgftransparent!0);
- color(8mm)=(pgftransparent!100);
- color(15mm)=(pgftransparent!100)
-}
-\pgfdeclarefading{fading3}{\pgfuseshading{myshading}}
-\begin{tikzpicture}
- \fill [black!20] (0,0) rectangle (2,2);
- \fill [black!30] (0,0) arc (180:0:1);
- \pgfsetfading{fading3}{\pgftransformshift{\pgfpoint{1cm}{1cm}}}
- \fill [red] (0,0) rectangle (2,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-After having declared a fading, we can use it. As for shadings, there are
-different commands for using fadings:
-
-\begin{command}{\pgfsetfading\marg{name}\marg{transformations}}
- This command sets the graphic state parameter ``fading'' to a previously
- defined fading \meta{name}. This graphic state works like other graphic
- states, that is, is persists till the end of the current scope or until a
- different transparency setting is chosen.
-
- When the fading is installed, it will be centered on the origin with its
- natural size. Anything outside the fading picture's original bounding box
- will be transparent and, thus, the fading effectively clips against this
- bounding box.
-
- The \meta{transformations} are applied to the fading before it is used.
- They contain normal \pgfname\ transformation commands like
- |\pgftransformshift|. You can also scale the fading using this command.
- Note, however, that the transformation needs to be inverted internally,
- which may result in inaccuracies and the following graphics may be slightly
- distorted if you use a strong \meta{transformation}.
- %
-\begin{codeexample}[]
-\pgfdeclarefading{fading2}
-{\tikz \shade[left color=pgftransparent!0,
- right color=pgftransparent!100] (0,0) rectangle (2,2);}
-\begin{tikzpicture}
- \fill [black!20] (0,0) rectangle (2,2);
- \fill [black!30] (0,0) arc (180:0:1);
- \pgfsetfading{fading2}{}
- \fill [red] (0,0) rectangle (2,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\pgfdeclarefading{fading2}
-{\tikz \shade[left color=pgftransparent!0,
- right color=pgftransparent!100] (0,0) rectangle (2,2);}}]
-\begin{tikzpicture}
- \fill [black!20] (0,0) rectangle (2,2);
- \fill [black!30] (0,0) arc (180:0:1);
- \pgfsetfading{fading2}{\pgftransformshift{\pgfpoint{1cm}{1cm}}
- \pgftransformrotate{20}}
- \fill [red] (0,0) rectangle (2,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetfadingforcurrentpath\marg{name}\marg{transformations}}
- This command works like |\pgfsetfading|, but the fading is scaled and
- transformed according to the following rules:
- %
- \begin{enumerate}
- \item If the current path is empty, the command has the same effect as
- |\pgfsetfading|.
- \item Otherwise it is assumed that the fading has a size of 100bp times
- 100bp.
- \item The fading is resized and shifted (using appropriate
- transformations) such that the position
- $(25\mathrm{bp},25\mathrm{bp})$ lies at the lower-left corner of
- the current path and the position $(75\mathrm{bp},75\mathrm{bp})$
- lies at the upper-right corner of the current path.
- \end{enumerate}
- %
- Note that these rules are the same as the ones used in |\pgfshadepath| for
- shadings. After these transformations, the \meta{transformations} are
- executed (typically a rotation).
- %
-\begin{codeexample}[]
-\pgfdeclarehorizontalshading{shading}{100bp}
-{ color(0pt)=(transparent!0); color(25bp)=(transparent!0);
- color(75bp)=(transparent!100); color(100bp)=(transparent!100)}
-
-\pgfdeclarefading{fading}{\pgfuseshading{shading}}
-
-\begin{tikzpicture}
- \fill [black!20] (0,0) rectangle (2,2);
- \fill [black!30] (0,0) arc (180:0:1);
-
- \pgfpathrectangle{\pgfpointorigin}{\pgfpoint{2cm}{1cm}}
- \pgfsetfadingforcurrentpath{fading}{}
- \pgfusepath{discard}
-
- \fill [red] (0,0) rectangle (2,1);
-
- \pgfpathrectangle{\pgfpoint{0cm}{1cm}}{\pgfpoint{2cm}{1cm}}
- \pgfsetfadingforcurrentpath{fading}{\pgftransformrotate{90}}
- \pgfusepath{discard}
-
- \fill [red] (0,1) rectangle (2,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetfadingforcurrentpathstroked\marg{name}\marg{transformations}}
- This command works like |\pgfsetfadingforcurrentpath|, only the current
- path is enlarged by the line width in both $x$- and $y$-direction. This is
- exactly the enlargement necessary to compensate for the fact that if the
- current path will be stroked, this much needs to be added around the path's
- bounding box to actually contain the path.
- %
-\begin{codeexample}[preamble={\pgfdeclarehorizontalshading{shading}{100bp}
-{ color(0pt)=(transparent!0); color(25bp)=(transparent!0);
- color(75bp)=(transparent!100); color(100bp)=(transparent!100)}
-%
-\pgfdeclarefading{fading}{\pgfuseshading{shading}}}]
-\begin{tikzpicture}
- \pgfsetlinewidth{2mm}
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{2cm}{0cm}}
- \pgfsetfadingforcurrentpathstroked{fading}{}
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Transparency Groups}
-
-Transparency groups are declared using the following commands.
-
-\begin{environment}{{pgftransparencygroup}\opt{\oarg{options}}}
- This environment should only be used inside a |{pgfpicture}|. It has the
- following effect:
- %
- \begin{enumerate}
- \item The \meta{environment contents} are stroked/filled ``ignoring any
- outside transparency''. This means, all previous transparency
- settings are ignored (you can still set transparency inside the
- group, but never mind). This means that if in the \meta{environment
- contents} you stroke a pixel three times in black, it is just
- black. Stroking it white afterwards yields a white pixel, and so
- on.
- \item When the group is finished, it is painted as a whole. The
- \emph{fill} transparency settings are now applied to the resulting
- picture. For instance, the pixel that has been painted three times
- in black and once in white is just white at the end, so this white
- color will be blended with whatever is ``behind'' the group on the
- page.
- \end{enumerate}
-
- The optional \meta{options} are keys that configure the transparency group
- further. Two keys are currently defined:
- %
- \begin{itemize}
- \item \declare{|knockout|\opt{|=|\meta{true or false}}} Configures
- whether the group is a knockout group (if no argument is given,
- |true| is assumed; initially the key is always false, even when the
- command is used in a nested manner.) See
- Section~\ref{section-transparency-groups} for details on knockout
- groups.
- \item \declare{|isolated|\opt{|=|\meta{true or false}}} Similar, but
- configures whether the group is an isolated group. Also see
- Section~\ref{section-transparency-groups} for details on isolated
- groups.
- \end{itemize}
-
- Note that, depending on the driver, \pgfname\ may have to guess the size of
- the contents of the transparency group (because such a group is put in an
- XForm in \textsc{pdf} and a bounding box must be supplied). \pgfname\ will
- use normally use the size of the picture's bounding box at the end of the
- transparency group plus a safety margin of 1cm. Under normal circumstances,
- this will work nicely since the picture's bounding box contains everything
- anyway. However, if you have switched off the picture size tracking or if
- you are using canvas transformations, you may have to make sure that the
- bounding box is big enough. The trick is to locally create a picture that
- is ``large enough'' and then insert this picture into the main picture
- while ignoring the size. The following example shows how this is done:
-
-% TODO: Nesting tikzpictures is NOT supported
-{\ifpgfmanualexternalize\tikzexternaldisable\fi
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (2,2);
-
- % Stuff outside the picture, but still in a transparency group.
- \node [left,overlay] at (0,1) {
- \begin{tikzpicture}
- \pgfsetfillopacity{0.5}
- \pgftransparencygroup
- \node at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
- {Smoking};
- \endpgftransparencygroup
- \end{tikzpicture}
- };
-\end{tikzpicture}
-\end{codeexample}
-}%
-
- \begin{plainenvironment}{{pgftransparencygroup}}
- Plain \TeX\ version of the |{pgftransparencygroup}| environment.
- \end{plainenvironment}
-
- \begin{contextenvironment}{{pgftransparencygroup}}
- This is the Con\TeX t version of the environment.
- \end{contextenvironment}
-\end{environment}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-drivers.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-drivers.tex
deleted file mode 100644
index 9ab6af46f1..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-drivers.tex
+++ /dev/null
@@ -1,468 +0,0 @@
-% 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{Supported Formats}
-\label{section-formats}
-
-\TeX\ was designed to be a flexible system. This is true both for the
-\emph{input} for \TeX\ as well as for the \emph{output}. The present section
-explains which input formats there are and how they are supported by \pgfname.
-It also explains which different output formats can be produced.
-
-
-\subsection{Supported Input Formats: \LaTeX, Plain \TeX, Con\TeX t}
-
-\TeX\ does not prescribe exactly how your input should be formatted. While it
-is \emph{customary} that, say, an opening brace starts a scope in \TeX, this is
-by no means necessary. Likewise, it is \emph{customary} that environments start
-with |\begin|, but \TeX\ could not really care less about the exact command
-name.
-
-Even though \TeX\ can be reconfigured, users can not. For this reason, certain
-\emph{input formats} specify a set of commands and conventions how input for
-\TeX\ should be formatted. There are currently three ``major'' formats: Donald
-Knuth's original |plain| \TeX\ format, Leslie Lamport's popular \LaTeX\ format,
-and Hans Hangen's Con\TeX t format.
-
-
-\subsubsection{Using the \LaTeX\ Format}
-
-Using \pgfname\ and \tikzname\ with the \LaTeX\ format is easy: You say
-|\usepackage{pgf}| or |\usepackage{tikz}|. Usually, that is all you need to do,
-all configuration will be done automatically and (hopefully) correctly.
-
-The style files used for the \LaTeX\ format reside in the subdirectory
-|latex/pgf/| of the \pgfname-system. Mainly, what these files do is to include
-files in the directory |generic/pgf|. For example, here is the content of the
-file |latex/pgf/frontends/tikz.sty|:
-%
-\begin{codeexample}[code only]
-% 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 Public License.
-%
-% See the file doc/generic/pgf/licenses/LICENSE for more details.
-
-
-\RequirePackage{pgf,pgffor}
-
-\input{tikz.code.tex}
-
-\endinput
-\end{codeexample}
-
-The files in the |generic/pgf| directory do the actual work.
-
-
-\subsubsection{Using the Plain \TeX\ Format}
-
-When using the plain \TeX\ format, you say |\input{pgf.tex}| or
-|\input{tikz.tex}|. Then, instead of |\begin{pgfpicture}| and
-|\end{pgfpicture}| you use |\pgfpicture| and |\endpgfpicture|.
-
-Unlike for the \LaTeX\ format, \pgfname\ is not as good at discerning the
-appropriate configuration for the plain \TeX\ format. In particular, it can
-only automatically determine the correct output format if you use |pdftex| or
-|tex| plus |dvips|. For all other output formats you need to set the macro
-|\pgfsysdriver| to the correct value. See the description of using output
-formats later on.
-
-Like the \LaTeX\ style files, the plain \TeX\ files like |tikz.tex| also just
-include the correct |tikz.code.tex| file.
-
-
-\subsubsection{Using the Con\TeX t Format}
-
-When using the Con\TeX t format, you say |\usemodule[pgf]| or
-|\usemodule[tikz]|. As for the plain \TeX\ format you also have to replace the
-start- and end-of-environment tags as follows: Instead of |\begin{pgfpicture}|
-and |\end{pgfpicture}| you use |\startpgfpicture| and |\stoppgfpicture|;
-similarly, instead of |\begin{tikzpicture}| and |\end{tikzpicture}| you use
-must now use |\starttikzpicture| and |\stoptikzpicture|; and so on for other
-environments.
-
-The Con\TeX t support is very similar to the plain \TeX\ support, so the same
-restrictions apply: You may have to set the output format directly and graphics
-inclusion may be a problem.
-
-In addition to |pgf| and |tikz| there also exist modules like |pgfcore| or
-|pgfmodulematrix|. To use them, you may need to include the module |pgfmod|
-first (the modules |pgf| and |tikz| both include |pgfmod| for you, so typically
-you can skip this). This special module is necessary since old versions of
-Con\TeX t~MkII before 2005 satanically restricted the length of module names to
-8 characters and \pgfname's long names are mapped to cryptic 6-letter-names for
-you by the module |pgfmod|. This restriction was never in place in
-Con\TeX t~MkIV and the |pgfmod| module can be safely ignored nowadays.
-
-
-\subsection{Supported Output Formats}
-\label{section-drivers}
-
-An output format is a format in which \TeX\ outputs the text it has typeset.
-Producing the output is (conceptually) a two-stage process:
-%
-\begin{enumerate}
- \item \TeX\ typesets your text and graphics. The result of this
- typesetting is mainly a long list of letter--coordinate pairs, plus
- (possibly) some ``special'' commands. This long list of pairs is
- written to something called a |.dvi|-file (informally known as
- ``device-independent file'').
- \item Some other program reads this |.dvi|-file and translates the
- letter--coordinate pairs into, say, PostScript commands for placing
- the given letter at the given coordinate.
-\end{enumerate}
-
-The classical example of this process is the combination of |latex| and
-|dvips|. The |latex| program (which is just the |tex| program called with the
-\LaTeX-macros preinstalled) produces a |.dvi|-file as its output. The |dvips|
-program takes this output and produces a |.ps|-file (a PostScript file).
-Possibly, this file is further converted using, say, |ps2pdf|, whose name is
-supposed to mean ``PostScript to PDF''. Another example of programs using this
-process is the combination of |tex| and |dvipdfm|. The |dvipdfm| program takes
-a |.dvi|-file as input and translates the letter--coordinate pairs therein into
-\pdf-commands, resulting in a |.pdf| file directly. Finally, the |tex4ht| is
-also a program that takes a |.dvi|-file and produces an output, this time it is
-a |.html| file. The programs |pdftex| and |pdflatex| are special: They directly
-produce a |.pdf|-file without the intermediate |.dvi|-stage. However, from the
-programmer's point of view they behave exactly as if there was an intermediate
-stage.
-
-Normally, \TeX\ only produces letter--coordinate pairs as its ``output''. This
-obviously makes it difficult to draw, say, a curve. For this, ``special''
-commands can be used. Unfortunately, these special commands are not the same
-for the different programs that process the |.dvi|-file. Indeed, every program
-that takes a |.dvi|-file as input has a totally different syntax for the
-special commands.
-
-One of the main jobs of \pgfname\ is to ``abstract away'' the difference in the
-syntax of the different programs. However, this means that support for each
-program has to be ``programmed'', which is a time-consuming and complicated
-process.
-
-
-\subsubsection{Selecting the Backend Driver}
-
-When \TeX\ typesets your document, it does not know which program you are going
-to use to transform the |.dvi|-file. If your |.dvi|-file does not contain any
-special commands, this would be fine; but these days almost all |.dvi|-files
-contain lots of special commands. It is thus necessary to tell \TeX\ which
-program you are going to use later on.
-
-Unfortunately, there is no ``standard'' way of telling this to \TeX. For the
-\LaTeX\ format a sophisticated mechanism exists inside the |graphics| package
-and \pgfname\ plugs into this mechanism. For other formats and when this
-plugging does not work as expected, it is necessary to tell \pgfname\ directly
-which program you are going to use. This is done by redefining the macro
-|\pgfsysdriver| to an appropriate value \emph{before} you load |pgf|. If you
-are going to use the |dvips| program, you set this macro to the value
-|pgfsys-dvips.def|; if you use |pdftex| or |pdflatex|, you set it to
-|pgfsys-pdftex.def|; and so on. In the following, details of the support of the
-different programs are discussed.
-
-
-\subsubsection{Producing PDF Output}
-
-\pgfname\ supports three programs that produce \pdf\ output (\pdf\ means
-``portable document format'' and was invented by the Adobe company): |dvipdfm|,
-|pdftex|, and |vtex|. The |pdflatex| program is the same as the |pdftex|
-program: it uses a different input format, but the output is exactly the same.
-
-\begin{filedescription}{pgfsys-pdftex.def}
- This is the driver file for use with pdf\TeX, that is, with the |pdftex| or
- |pdflatex| command. It includes |pgfsys-common-pdf.def|.
-
- This driver has a lot of functionality. (Almost) everything \pgfname\ ``can
- do at all'' is implemented in this driver.
-\end{filedescription}
-
-\begin{filedescription}{pgfsys-dvipdfm.def}
- This is a driver file for use with (|la|)|tex| followed by |dvipdfm|. It
- includes |pgfsys-common-pdf.def|.
-
- This driver supports most of \pgfname's features, but there are some
- restrictions:
- %
- \begin{enumerate}
- \item In \LaTeX\ mode it uses |graphicx| for the graphics inclusion
- and does not support masking.
- \item In plain \TeX\ mode it does not support image inclusion.
- \end{enumerate}
-\end{filedescription}
-
-\begin{filedescription}{pgfsys-xetex.def}
- This is a driver file for use with |xe|(|la|)|tex| followed by |xdvipdfmx|.
- This driver supports largely the same operations as the |dvipdfm| driver.
-\end{filedescription}
-
-\begin{filedescription}{pgfsys-vtex.def}
- This is the driver file for use with the commercial \textsc{vtex} program.
- Even though it produces \textsc{pdf} output, it includes
- |pgfsys-common-postscript.def|. Note that the \textsc{vtex} program can
- produce \emph{both} Postscript and \textsc{pdf} output, depending on the
- command line parameters. However, whether you produce Postscript or
- \textsc{pdf} output does not change anything with respect to the driver.
-
- This driver supports most of \pgfname's features, except for the following
- restrictions:
- %
- \begin{enumerate}
- \item In \LaTeX\ mode it uses |graphicx| for the graphics inclusion
- and does not support masking.
- \item In plain \TeX\ mode it does not support image inclusion.
- \item Shadings are approximated with discrete colors. This typically
- leads to aliasing patterns in PostScript and \textsc{pdf} viewing
- applications.
- \item Opacity, Transparency Groups, Fadings and Blend Modes are not
- supported.
- \item Remembering of pictures (inter-picture connections) is not
- supported.
- \end{enumerate}
-\end{filedescription}
-
-It is also possible to produce a |.pdf|-file by first producing a PostScript
-file (see below) and then using a PostScript-to-\pdf\ conversion program like
-|ps2pdf| or Acrobat Distiller.
-
-
-\subsubsection{Producing PostScript Output}
-
-\begin{filedescription}{pgfsys-dvips.def}
- This is a driver file for use with (|la|)|tex| followed by |dvips|. It
- includes |pgfsys-common-postscript.def|.
-
- This driver also supports most of \pgfname's features, except for the
- following restrictions:
- %
- \begin{enumerate}
- \item In \LaTeX\ mode it uses |graphicx| for the graphics inclusion.
- Image masking is supported if the PostScript output is further
- processed with |ps2pdf| to produce \textsc{pdf}.
- \item In plain \TeX\ mode it does not support image inclusion.
- \item Functional shadings are approximated with Type-0 functions
- (sampled functions), because Type-4 functions are not available in
- the latest (version 3) PostScript language definition. Due to
- their fixed resolution, Type-0 functional shadings are of lesser
- quality at higher zoom levels as compared to functional shadings
- from \textsc{pdf} producing drivers. Axial and radial shadings are
- fully supported. The same output quality (smooth shadings) is
- achieved as with drivers that produce \textsc{pdf} output.
- \item Although fully supported, opacity and fadings are \textsc{pdf}
- features that become visible only after further processing the
- PostScript output with |ps2pdf|. Note that newer Ghostscript
- versions are necessary for producing opacity in the \textsc{pdf}
- output. Also, beginning with version 9.52 of Ghostscript, command
- line option |-dALLOWPSTRANSPARENCY| must be added:
-\begin{codeexample}[code only]
-ps2pdf -dALLOWPSTRANSPARENCY example.ps
-\end{codeexample}
- \item For remembering of pictures (inter-picture connections) you
- need to use a recent version of |pdftex| running in DVI-mode.
- \end{enumerate}
-\end{filedescription}
-
-\begin{filedescription}{pgfsys-textures.def}
- This is a driver file for use with the \textsc{textures} program. It
- includes |pgfsys-common-postscript.def|.
-
- This driver shares the restrictions of the |vtex| driver, but adds limited
- opacity support (no transparency groups, fadings and blend modes, though).
-\end{filedescription}
-
-You can also use the |vtex| program together with |pgfsys-vtex.def| to produce
-Postscript output.
-
-
-\subsubsection{Producing SVG Output}
-
-\begin{filedescription}{pgfsys-dvisvgm.def}
- This driver converts \textsc{dvi} files to \textsc{svg} file, including
- text and fonts. When you select this driver, \pgfname\ will output the
- required raw \textsc{svg} code for the pictures it produces.
-
- Since the |graphics| package does not (yet?) support this driver directly,
- there is special rule for this driver in \LaTeX: If the option |dvisvgm| is
- given to the |tikz| package, this driver gets selected (normally, the
- driver selected by |graphics| would be used). For packages like |beamer|
- that load \pgfname\ themselves, this means that the option |dvisvgm| should
- be given to the document class.
- %
-\begin{codeexample}[code only]
-% example.tex
-\documentclass[dvisvgm]{minimal}
-
-\usepackage{tikz}
-
-\begin{document}
-Hello \tikz [baseline] \fill [fill=blue!80!black] (0,.75ex) circle[radius=.75ex];
-\end{document}
-\end{codeexample}
-
- And then run
- %
-\begin{codeexample}[code only]
-latex example
-dvisvgm example
-\end{codeexample}
- %
- or better
- %
-\begin{codeexample}[code only]
-lualatex --output-format=dvi example
-dvisvgm example
-\end{codeexample}
- %
- (This is ``better'' since it gives you access to the full power of Lua\TeX\
- inside your \TeX-file. In particular, \tikzname\ is able to run graph
- drawing algorithms in this case.)
-
- Unlike the |tex4ht| driver below, this driver has full support of text
- nodes.
-\end{filedescription}
-
-\begin{filedescription}{pgfsys-tex4ht.def}
- This is a driver file for use with the |tex4ht| program. It is selected
- automatically when the |tex4ht| style or command is loaded. It includes
- |pgfsys-common-svg.def|.
-
- The |tex4ht| program converts |.dvi|-files to |.html|-files. While the
- \textsc{html}-format cannot be used to draw graphics, the
- \textsc{svg}-format can. This driver will ask \pgfname\ to produce an
- \textsc{svg}-picture for each \pgfname\ graphic in your text.
-
- When using this driver you should be aware of the following restrictions:
- %
- \begin{enumerate}
- \item In \LaTeX\ mode it uses |graphicx| for the graphics inclusion.
- \item In plain \TeX\ mode it does not support image inclusion.
- \item Remembering of pictures (inter-picture connections) is not
- supported.
- \item Text inside |pgfpicture|s is not supported very well. The
- reason is that the \textsc{svg} specification currently does not
- support text very well and, although it is possible to ``escape
- back'' to \textsc{html}, \tikzname\ has then to guess what size
- the text rendered by the browser would have.
- \item Unlike for other output formats, the bounding box of a picture
- ``really crops'' the picture.
- \item Matrices do not work.
- \item Functional shadings are not supported.
- \end{enumerate}
-
- The driver basically works as follows: When a |{pgfpicture}| is started,
- appropriate |\special| commands are used to directed the output of |tex4ht|
- to a new file called |\jobname-xxx.svg|, where |xxx| is a number that is
- increased for each graphic. Then, till the end of the picture, each (system
- layer) graphic command creates a special that inserts appropriate
- \textsc{svg} literal text into the output file. The exact details are a bit
- complicated since the imaging model and the processing model of
- PostScript/\pdf\ and \textsc{svg} are not quite the same; but they are
- ``close enough'' for \pgfname's purposes.
-
- Because text is not supported very well in the \textsc{svg} standard, you
- may wish to use the following options to modify the way text is handled:
-
- \begin{key}{/pgf/tex4ht node/escape=\meta{boolean} (default |false|)}
- Selects the rendering method for a text node with the tex4ht driver.
-
- When this key is set to |false|, text is translated into \textsc{svg}
- text, which is somewhat limited: simple characters (letters, numerals,
- punctuation, $\sum$, $\int$, \ldots), subscripts and superscripts (but
- not subsubscripts) will display but everything else will be filtered
- out, ignored or will produce invalid \textsc{html} code (in the worst
- case). This means that two kind of texts render reasonably well:
- %
- \begin{enumerate}
- \item First, plain text without math mode, special characters or
- anything else special.
- \item Second, \emph{very} simple mathematical text that contains
- subscripts or superscripts. Even then, variables are not
- correctly set in italics and, in general, text simple does
- not look very nice.
- \end{enumerate}
- %
- If you use text that contains anything special, even something as
- simple as |$\alpha$|, this may corrupt the graphic.
- %
-\begin{codeexample}[code only]
-\tikz \node[draw,/pgf/tex4ht node/escape=false] {Example : $(a+b)^2=a^2+2ab+b^2$};
-\end{codeexample}
-
- When you write |node[/pgf/tex4ht node/escape=true] {|\meta{text}|}|,
- \pgfname\ escapes back to \textsc{html} to render the \meta{text}. This
- method produces valid \textsc{html} code in most cases and the support for
- complicated text nodes is much better since code that renders well outside
- a |{pgfpicture}|, should also render well inside a text node. Another
- advantage is that inside text nodes with fixed width, \textsc{html} will
- produce line breaks for long lines. On the other hand, you need a browser
- with good \textsc{svg} support to display the picture. Also, the text will
- display differently, depending on your browsers, the fonts you have on your
- system and your settings. Finally, \pgfname\ has to guess the size of the
- text rendered by the browser to scale it and prevent it from sticking from
- the node. When it fails, the text will be either cropped or too small.
- %
-\begin{codeexample}[code only]
-\tikz \node[draw,/pgf/tex4ht node/escape=true]
- {Example : $\int_0^\infty\frac{1}{1+t^2}dt=\frac{\pi}{2}$};
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/tex4ht node/css=\meta{filename} (default |\string\jobname|)}
- This option allows you to tell the browser what \textsc{css} file it
- should use to style the display of the node (only with
- |tex4ht node/escape=true|).
- \end{key}
-
- \begin{key}{/pgf/tex4ht node/class=\meta{class name} (default foreignobject)}
- This option allows you to give a class name to the node, allowing it to
- be styled by a \textsc{css} file (only with |tex4ht node/escape=true|).
- \end{key}
-
- \begin{key}{/pgf/tex4ht node/id=\meta{id name} (default |\string\jobname\ picture number-node number|)}
- This option allows you to give a unique id to the node, allowing
- it to be styled by a \textsc{css} file (only with
- |tex4ht node/escape=true|).
- \end{key}
-\end{filedescription}
-
-
-\subsubsection{Producing Perfectly Portable DVI Output}
-
-\begin{filedescription}{pgfsys-dvi.def}
- This is a driver file that can be used with any output driver, except for
- |tex4ht|.
-
- The driver will produce perfectly portable |.dvi| files by composing all
- pictures entirely of black rectangles, the basic and only graphic shape
- supported by the \TeX\ core. Even straight, but slanted lines are tricky to
- get right in this model (they need to be composed of lots of little
- squares).
-
- Naturally, \emph{very little} is possible with this driver. In fact, so
- little is possible that it is easier to list what is possible:
- %
- \begin{itemize}
- \item Text boxes can be placed in the normal way.
- \item Lines and curves can be drawn (stroked). If they are not
- horizontal or vertical, they are composed of hundreds of small
- rectangles.
- \item Lines of different width are supported.
- \item Transformations are supported.
- \end{itemize}
- %
- Note that, say, even filling is not supported! (Let alone color or anything
- fancy.)
-
- This driver has only one real application: It might be useful when you only
- need horizontal or vertical lines in a picture. Then, the results are quite
- satisfactory.
-\end{filedescription}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-axes.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-axes.tex
deleted file mode 100644
index 373402b5cd..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-axes.tex
+++ /dev/null
@@ -1,3822 +0,0 @@
-% 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{Axes}
-\label{section-dv-axes}
-
-\subsection{Overview}
-
-When a data point is visualized, the most obvious way of creating a visual
-representation of its many attributes is to vary \emph{where} the data point is
-shown. The data visualization system uses \emph{axes} to turn data point
-attributes into positions on a page. The simplest -- and most common -- use of
-axes is to vary the horizontal position of data points according to one
-attribute and to vary the vertical position according to another attribute. In
-contrast, in a polar plot one attribute dictates the distance of the data point
-from the origin and another attribute describes the angle. From the data
-visualization engine's point of view, in both cases two \emph{axes} are
-involved.
-
-In addition to specifying how the value of a certain attribute is converted
-into a displacement on the page, an axis is also typically (but not always)
-visualized (``drawn'') somewhere on the page. In this case, it is also
-customary to add a visual representation on this axis of which attribute values
-correspond to which positions on the page -- something commonly known as
-\emph{ticks}. Similar to ticks, \emph{grid lines} also indicate positions where
-a certain attribute has a certain value, but instead of just indicating a
-single position on an axis, a grid line goes through all points that share an
-attribute value.
-
-In the following, in Section~\ref{section-dv-axes-main} we first have a look at
-how axes can be defined and configured. As you will see, a lot of powerful
-configurations are available, but you will rarely define and configure an axis
-from scratch. Rather, it is more common to use a preconfigured axis instead.
-Section~\ref{section-dv-axis-systems} introduces \emph{axis systems}, which are
-predefined bundles of axes. You can define your own axis systems, but, again,
-in most cases it will suffice to just use one of the many preconfigured axis
-systems and use a few options to configure it so that it fits your need.
-Section~\ref{section-dv-ticks-and-grids} explains how ticks and grid lines can
-be configured. Again, several layers of options allow you to configure the way
-ticks look and where they are placed in great detail.
-
-This section documents the standard axis systems that are always available. For
-polar axis systems, a special library needs to be loaded, which is documented
-in Section~\ref{section-dv-polar}.
-
-
-\subsection{Basic Configuration of Axes}
-\label{section-dv-axes-main}
-
-Inside the data visualization system, an \emph{axis} is roughly a ``systematic,
-named way of mapping an attribute to a position on a page''. For instance, the
-classical ``$x$-axis'' is the ``systematic way of mapping the value of the |x|
-attribute of data points to a horizontal position on the page''. An axis is
-\emph{not} its visual representation (such as the horizontal line with the
-ticks drawn to represent the $x$-axis), but a visual representation can be
-created once an axis has been defined.
-
-The transformation of an attribute value (such as the value |1000000000| for
-the |x| attribute) to a specific displacement of the corresponding data point
-on the page involves two steps:
-%
-\begin{enumerate}
- \item First, the range of possible values such as $[-5.6\cdot
- 10^{12},7.8\cdot 10^{12}]$ must be mapped to a ``reasonable'' interval
- such as $[0\mathrm{cm},5\mathrm{cm}]$ or $[0^\circ,180^\circ]$.
- \tikzname's drawing routines will only be able to cope with values from
- such a ``reasonable'' interval.
- \item Second, the values from the reasonable interval must be mapped to a
- transformation.
-\end{enumerate}
-%
-The first step is always the same for all axes, while the second requires
-different strategies. For this reason, the command |new axis base| is used to
-create a ``basic'' axis that has a ``scaling mapper'', whose job it is to map
-the range of values of a specific attribute to a reasonable interval, but such
-a basic axis does not define an actual transformation object. For this second
-step, additional objects such as a |linear transformer| need to be created
-separately.
-
-
-\subsubsection{Usage}
-
-To create an axis, the key |new axis base| is used first. Since this key does
-not create a transformation object, users typically do not use this key
-directly. Rather, it is used internally by other keys that create ``real''
-axes. These keys are listed in Section~\ref{section-dv-reference-axis-types}.
-
-\begin{key}{/tikz/data visualization/new axis base=\meta{axis name}}
- This key defines a new axis for the current data visualization called
- \meta{name}. This has two effects:
- %
- \begin{enumerate}
- \item A so called \emph{scaling mapper} is created that will monitor a
- certain attribute, rescale it, and map it to another attribute.
- (This will be explained in detail in a moment.)
- \item The \meta{axis name} is made available as a key that can be used
- to configure the axis:
- %
- \begin{key}{/tikz/data visualization/\meta{axis name}=\meta{options}}
- This key becomes available once |new axis base=|meta{axis name}
- has been called. It will execute the \meta{options} with the
- path prefix |/tikz/data visualization/axis options|.
- %
-\begin{codeexample}[code only]
-[new axis base=my axis,
- my axis={attribute=some attribute}]
-\end{codeexample}
- \end{key}
- \item The \meta{axis name} becomes part of the current set of axes.
- This set can be accessed through the following key:
- %
- \begin{key}{/tikz/data visualization/all axes=\meta{options}}
- This key passes the \meta{options} to all axes inside the
- current scope, just as if you had written \meta{some axis
- name}|=|\meta{options} for each \meta{some axis name} in the
- current scope, including the just-created name \meta{axis
- name}.
- \end{key}
- \end{enumerate}
- %
- There are many \meta{options} that can be passed to a newly created axis.
- They are explained in the rest of this section.
-\end{key}
-
-Note the |new axis base| does \emph{not} cause attributes to be mapped to
-positions on a page. Rather, special keys like |new Cartesian axis| first use
-|new axis base| to create an axis and then create an internal object that
-performs a linear mapping of the attribute to positions along a vectors.
-
-
-\subsubsection{The Axis Attribute}
-\label{section-dv-axis-attribute}
-
-The first main job of an axis is to map the different values of some attribute
-to a reasonable interval. To achieve this, the following options are important
-(recall that these options are passed to the key whose name is the name of the
-axis):
-
-\begin{key}{/tikz/data visualization/axis options/attribute=\meta{attribute}}
- Specifies that the axis is used to transform the data points according the
- different values of the key |/data point/|\meta{attribute}. For instance,
- when we create a classical two-dimensional Cartesian coordinate system,
- then there are two axes called |x axis| and |y axis| that monitor the
- values of the attributes |/data point/x| and |/data point/y|, respectively:
- %
-\begin{codeexample}[code only]
- [new axis base=x axis,
- new axis base=y axis,
- x axis={attribute=x},
- y axis={attribute=y}]
-\end{codeexample}
- %
- In another example, we also create an |x axis| and a |y axis|. However,
- this time, we want to plot the values of the |/data point/time| attribute
- on the $x$-axis and, say, the value of the |height| attribute on the
- $y$-axis:
- %
-\begin{codeexample}[code only]
- [new axis base=x axis,
- new axis base=y axis,
- x axis={attribute=time},
- y axis={attribute=height}]
-\end{codeexample}
- %
- During the data visualization, the \meta{attribute} will be ``monitored''
- during the survey phase. This means that for each data point, the current
- value of |/data point/|\meta{attribute} is examined and the minimum value
- of all of these values as well as the maximum value is recorded internally.
- Note that this works even when very large numbers like |100000000000| are
- involved.
-
- Here is a real-life example. The |scientific axes| create two axes, called
- |x axis| and |y axis|, respectively.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [scientific axes,
- x axis={attribute=people, length=2.5cm, ticks=few},
- y axis={attribute=year},
- visualize as scatter]
- data {
- year, people
- 1900, 100
- 1910, 200
- 1950, 200
- 1960, 250
- 2000, 150
- };
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{The Axis Attribute Range Interval}
-
-Once an attribute has been specified for an axis, the data visualization engine
-will start monitoring this value. This means that before anything actual
-visualization is done, a ``survey phase'' is used to determine the range of
-values encountered for the attribute for all data points. This range of values
-results in what is called the \emph{attribute range interval}. Its minimum is
-the smallest value encountered in the data and its maximum is the largest
-value.
-
-Even though the attribute range interval is computed automatically and even
-though you typically do not need to worry about it, there are some situations
-where you may wish to set or enlarge the attribute range interval:
-%
-\begin{itemize}
- \item You may wish to start the interval with $0$, even though the range of
- values contains only positive values.
- \item You may wish to slightly enlarge the interval so that, say, the
- maximum is some ``nice'' value like |100| or |60|.
-\end{itemize}
-
-The following keys can be used to influence the size of the attribute range
-interval:
-%
-\begin{key}{/tikz/data visualization/axis options/include value=\meta{list of value}}
- This key ``fakes'' data points for which the attribute's values are in the
- comma-separated \meta{list of values}. For instance, when you write
- |include value=0|, then the attribute range interval is guaranteed to
- contain |0| -- even if the actual data points are all positive or all
- negative.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes, all axes={length=3cm},
- visualize as line]
- data [format=function] {
- var x : interval [5:10];
- func y = \value x * \value x;
- };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes, all axes={length=3cm},
- visualize as line,
- x axis={include value=20},
- y axis={include value=0}]
- data [format=function] {
- var x : interval [5:10];
- func y = \value x * \value x;
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/axis options/min value=\meta{value}}
- This key allows you to simply set the minimum value, regardless of which
- values are present in the actual data. This key should be used with care:
- If there are data points for which the attribute's value is less than
- \meta{value}, they will still be depicted, but typically outside the normal
- visualization area. Usually, saying |include value=|\meta{value} will
- achieve the same as saying |min value=|\meta{value}, but with less danger
- of creating ill-formed visualizations.
-\end{key}
-
-\begin{key}{/tikz/data visualization/axis options/max value=\meta{value}}
- Works like |min value|.
-\end{key}
-
-
-\subsubsection{Scaling: The General Mechanism}
-
-The above key allows us specify which attribute should be ``monitored''. The
-next key is used to specify what should happen with the observed values.
-
-\begin{key}{/tikz/data visualization/axis options/scaling=\meta{scaling spec}}
- The \meta{scaling spec} must have the following form:
- %
- \begin{quote}
- \meta{$s_1$}| at |\meta{$t_1$}| and |\meta{$s_2$}| at |\meta{$t_2$}
- \end{quote}
- %
- This means that monitored values in the interval $[s_1,s_2]$ should be
- mapped to values the ``reasonable'' interval $[t_1,t_2]$, instead. For
- instance, we might write
- %
-\begin{codeexample}[code only]
-[y axis = {scaling = 1900 at 0cm and 2000 at 5cm}]
-\end{codeexample}
- %
- in order to map dates between 1900 and 2000 to the dimension interval
- $[0\mathrm{cm},5\mathrm{cm}]$.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization
- [scientific axes,
- x axis={attribute=people, length=2.5cm, ticks=few},
- y axis={attribute=year, scaling=1900 at 0cm and 2000 at 5cm},
- visualize as scatter]
- data {
- year, people
- 1900, 100
- 1910, 200
- 1950, 200
- 1960, 250
- 2000, 150
- };
-\end{codeexample}
- %
- So much for the basic idea. Let us now have a detailed look at what
- happens.
-
-
- \medskip
- \textbf{Number format and the min and max keywords.}
- The source values $s_1$ and $s_2$ are typically just numbers like |3.14| or
- |10000000000|. However, as described in
- Section~\ref{section-dv-expressions}, you can also specify expressions like
- |(pi/2)|, provided that (currently) you put them in parentheses.
-
- Instead of a number, you may alternatively also use the two key words |min|
- and |max| for $s_1$ and/or $s_2$. In this case, |min| evaluates to the
- smallest value observed for the attribute in the data, symmetrically |max|
- evaluates to the largest values. For instance, in the above example with
- the |year| attribute ranging from |1900| to |2000|, the keyword |min| would
- stand for |1900| and |max| for |2000|. Similarly, for the |people|
- attribute |min| stands for |100| and |max| for |250|. Note that |min| and
- |max| can only be used for $s_1$ and $s_2$, not for $t_1$ and $t_2$.
-
- A typical use of the |min| and |max| keywords is to say
- %
-\begin{codeexample}[code only]
-scaling = min at 0cm and max at 5cm
-\end{codeexample}
- %
- to map the complete range of values into an interval of length of 5cm.
-
- The interval $[s_1,s_2]$ need not contain all values that the
- \meta{attribute} may attain. It is permissible that values are less than
- $s_1$ or more than $s_2$.
-
-
- \medskip
- \textbf{Linear transformation of the attribute.}
- As indicated earlier, the main job of an axis is to map values from a
- ``large'' interval $[s_1,s_2]$ to a more reasonable interval $[t_1,t_2]$.
- Suppose that for the current data point the value of the key
- |/data point/|\meta{attribute} is the number $v$. In the simplest case, the
- following happens: A new value $v'$ is computed so that $v' = t_1$ when
- $v=s_1$ and $v'=t_2$ when $v=s_2$ and $v'$ is some value in between $t_1$
- and $t_2$ then $v$ is some value in between $s_1$ and $s_2$. (Formally, in
- this basic case $v' = t_1 + (v-s_1)\frac{t_2-t_1}{s_2-s_1}$.)
-
- Once $v'$ has been computed, it is stored in the key
- |/data point/|\meta{attribute}|/scaled|. Thus, the ``reasonable'' value
- $v'$ does not replace the value of the attribute, but it is placed in a
- different key. This means that both the original value and the more
- ``scaled'' values are available when the data point is visualized.
-
- As an example, suppose you have written
- %
-\begin{codeexample}[code only]
-[x axis = {attribute = x, scaling=1000 at 20 and 2000 at 30}]
-\end{codeexample}
- %
- Now suppose that |/data point/x| equals |1200| for a data point. Then the
- key |/data point/x/scaled| will be set to |22| when the data point is being
- visualized.
-
-
- \medskip
- \textbf{Nonlinear transformations of the attribute.}
- By default, the transformation of $[s_1,s_2]$ to $[t_1,t_2]$ is the linear
- transformation described above. However, in some case you may be interested
- in a different kind of transformation: For example, in a logarithmic plot,
- values of an attribute may range between, say, |1| and |1000| and we want
- an axis of length |3cm|. So, we would write
- %
-\begin{codeexample}[code only]
-[x axis = {attribute = x, scaling=1 at 0cm and 1000 at 3cm}]
-\end{codeexample}
- %
- Indeed, |1| will now be mapped to position |0cm| and |1000| will be mapped
- to position |3cm|. Now, the value |10| will be mapped to approximately
- |0.03cm| because it is (almost) at one percent between |1| and |1000|.
- However, in a logarithmic plot we actually want |10| to be mapped to the
- position |1cm| rather than |0.03cm| and we want |100| to be mapped to the
- position |2cm|. Such a mapping a \emph{nonlinear} mapping between the
- intervals.
-
- In order to achieve such a nonlinear mapping, the |function| key can be
- used, whose syntax is described in a moment. The effect of this key is to
- specify a function $f \colon \mathbb{R} \to \mathbb{R}$ like, say, the
- logarithm function. When such a function is specified, the mapping of $v$
- to $v'$ is computed as follows:
- %
- \begin{align*}
- v' = t_1 + (f(s_2) - f(v))\frac{t_2 - t_1}{f(s_2)-f(s_1)}.
- \end{align*}
-
- The syntax of the |function| key is described next, but you typically will
- not call this key directly. Rather, you will use a key like |logarithmic|
- that installs appropriate code for the |function| key for you.
- %
- \begin{key}{/tikz/data visualization/axis options/function=\meta{code}}
- The \meta{code} should specify a function $f$ that is applied during
- the transformation of the interval $[s_1,s_2]$ to the interval
- $[t_1,t_2]$ in the following way: When the \meta{code} is called, the
- macro |\pgfvalue| will have been set to an internal representation of
- the to-be-transformed value~$v$. You can then call the commands of the
- math-micro-kernel of the data visualization system, see
- Section~\ref{section-dv-math-kernel}, to compute a new value. This new
- value must once more be stored in |\pgfvalue|.
-
- The most common use of this key is to say
- %
-\begin{codeexample}[code only]
-some axis={function=\pgfdvmathln{\pgfvalue}{\pgfvalue}}
-\end{codeexample}
- %
- This specifies that the function $f$ is the logarithm function.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization
- [scientific axes,
- x axis={ticks={major={at={1,10,100,1000}}},
- scaling=1 at 0cm and 1000 at 3cm,
- function=\pgfdvmathln{\pgfvalue}{\pgfvalue}},
- visualize as scatter]
- data [format=named] {
- x={1,100,...,1000}, y={1,2,3}
- };
-\end{codeexample}
- %
- Another possibility might be to use the square-root function, instead:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization
- [scientific axes,
- x axis={ticks=few,
- scaling=1 at 0cm and 1000 at 3cm,
- function=\pgfdvmathunaryop{\pgfvalue}{sqrt}{\pgfvalue}},
- visualize as scatter]
- data [format=named] {
- x={0,100,...,1000}, y={1,2,3}
- };
-\end{codeexample}
- \end{key}
-
-
- \medskip
- \textbf{Default scaling.}
- When no scaling is specified, it may seem natural to use $[0,1]$ both as
- the source and the target interval. However, this would not work when the
- logarithm function is used as transformations: In this case the logarithm
- of zero would be computed, leading to an error. Indeed, for a logarithmic
- axis it is far more natural to use $[1,10]$ as the source interval and
- $[0,1]$ as the target interval.
-
- For these reasons, the default value for the |scaling| that is used when no
- value is specified explicitly can be set using a special key:
- %
- \begin{key}{/tikz/data visualization/axis options/scaling/default=\meta{text}}
- The \meta{text} is used as |scaling| whenever no other scaling is
- specified. This key is mainly used when a transformation function is
- set using |function|; normally, you will not use this key directly.
- \end{key}
-\end{key}
-
-Most of the time, you will not use neither the |scaling| nor the |function| key
-directly, but rather you will use one of the following predefined styles
-documented in the following.
-
-
-\subsubsection{Scaling: Logarithmic Axes}
-
-\begin{key}{/tikz/data visualization/axis options/logarithmic}
- When this key is used with an axis, three things happen:
- %
- \begin{enumerate}
- \item The transformation |function| of the axis is setup to the
- logarithm.
- \item The strategy for automatically generating ticks and grid lines is
- set to the |exponential strategy|, see
- Section~\ref{section-dv-exponential-strategy} for details.
- \item The default scaling is setup sensibly.
- \end{enumerate}
- %
- All told, to turn an axis into a logarithmic axis, you just need to add
- this option to the axis.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization [scientific axes,
- x axis={logarithmic},
- y axis={logarithmic},
- visualize as line]
- data [format=function] {
- var x : interval [0.01:100];
- func y = \value x * \value x;
- };
-\end{codeexample}
- %
- Note that this will work with any axis, including, say, the degrees on a
- polar axis:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
-\tikz \datavisualization
- [new polar axes,
- angle axis={logarithmic, scaling=1 at 0 and 90 at 90},
- radius axis={scaling=0 at 0cm and 100 at 3cm},
- visualize as scatter]
- data [format=named] {
- angle={1,10,...,90}, radius={1,10,...,100}
- };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
-\tikz \datavisualization
- [new polar axes,
- angle axis={degrees},
- radius axis={logarithmic, scaling=1 at 0cm and 100 at 3cm},
- visualize as scatter]
- data [format=named] {
- angle={1,10,...,90}, radius={1,10,...,100}
- };
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Scaling: Setting the Length or Unit Length}
-
-\begin{key}{/tikz/data visualization/axis options/length=\meta{dimension}}
- Sets |scaling| to |min at 0cm and max at |\meta{dimension}. The effect is
- that the range of all values of the axis's attribute will be mapped to an
- interval of exact length \meta{dimension}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [scientific axes,
- x axis={length=3cm},
- y axis={length=2cm},
- all axes={ticks=few},
- visualize as line]
- data {
- x, y
- 10, 10
- 20, 20
- 15, 30
- 13, 20
- };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [scientific axes,
- x axis={length=3cm},
- y axis={length=4cm},
- all axes={ticks=few},
- visualize as line]
- data {
- x, y
- 10, 10
- 20, 20
- 15, 30
- 13, 20
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/axis options/unit length=\meta{dimension}\opt{| per |\meta{number}| units|}}
- Sets |scaling| to |0 at 0cm and 1 at |\meta{dimension}. In other words,
- this key allows you to specify how long a single unit should be. This key
- is particularly useful when you wish to ensure that the same scaling is
- used across multiple axes or pictures.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [scientific axes,
- all axes={ticks=few, unit length=1mm},
- visualize as line]
- data {
- x, y
- 10, 10
- 40, 20
- 15, 30
- 13, 20
- };
-\end{codeexample}
- %
- The optional |per |\meta{number}| units| allows you to apply more drastic
- scaling. Suppose that you want to plot a graph where one billion
- corresponds to one centimeter. Then the unit length would be need to be set
- to a hundredth of a nanometer -- much too small for \TeX\ to handle as a
- dimension. In this case, you can write
- |unit length=1cm per 1000000000 units|:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization
- [scientific axes,
- x axis={unit length=1mm per 1000000000 units, ticks=few},
- visualize as line]
- data {
- x, y
- 10000000000, 10
- 40000000000, 20
- 15000000000, 30
- 13000000000, 20
- };
-\end{codeexample}
- %
-\end{key}
-%
-\begin{key}{/tikz/data visualization/axis options/power unit length=\meta{dimension}}
- This key is used in conjunction with the |logarithmic| setting. It cases
- the |scaling| to be set to |1 at 0cm and 10 at |\meta{dimension}. This
- causes a ``power unit'', that is, one power of ten in a logarithmic plot,
- to get a length of \meta{dimension}. Again, this key is useful for ensuring
- that the same scaling is used across multiple axes or pictures.
- %
-\begin{codeexample}[width=8cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization
- [scientific axes,
- y axis={logarithmic, power unit length=1mm, grid},
- visualize as line]
- data {
- x, y
- 0, 0.0000000001
- 1, 1
- 2, 100000
- 3, 100000000000
- 4, 10000000000000000000000000000000
- 5, 500000000
- 6, 5000000000000000000
- };
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Axis Label}
-
-An axis can have a \emph{label}, which is a textual representation of the
-attribute according to which the axis varies the position of the page. You can
-set the attribute using the following key:
-
-\begin{key}{/tikz/data visualization/axis options/label=\opt{|\char`\{[|\meta{options}|]|}\meta{text}\opt{|\char`\}|}
- (default \normalfont axis's label in math mode)%
-}
- This key sets the label of an axis to \meta{text}. This text will typically
- be placed inside a |node| and the \meta{options} can be used to further
- configure the way this node is rendered. The \meta{options} will be
- executed with the path prefix |/tikz/data visualization/|, so you need to
- say |node style| to configure the styling of a node, see
- Section~\ref{section-dv-style}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [
- scientific axes,
- x axis = {label, length=2.5cm},
- y axis = {label={[node style={fill=blue!20}]{$x^2$}}},
- visualize as smooth line]
- data [format=function] {
- var x : interval [-3:5];
- func y = \value x * \value x;
- };
-\end{codeexample}
- %
-\end{key}
-
-Note that using the |label| key does not actually cause a node to be created,
-because it is somewhat unclear where the label should be placed. Instead, the
-|visualize label| key is used (typically internally by an axis system) to show
-the label at some sensible position. This key is documented in
-Section~\ref{section-dv-visualize-label}.
-
-
-\subsubsection{Reference: Axis Types}
-\label{section-dv-reference-axis-types}
-
-As explained earlier, when you use |new axis base| to create a new axis, a
-powerful scaling and attribute mapping mechanism is installed, but no mapping
-of values to positions on the page is performed. For this, a
-\emph{transformation object} must be installed. The following keys take care of
-this for you. Note, however, that even these keys do not cause a visual
-representation of the axis to be added to the visualization -- this is the job
-of an axis system, see Section~\ref{section-dv-axis-systems}.
-
-\begin{key}{/tikz/data visualization/new Cartesian axis=\meta{name}}
- This key creates a new ``Cartesian'' axis, named \meta{name}. For such an
- axis, the (scaled) values of the axis's attribute are transformed into a
- displacement on the page along a straight line. The following key is used
- to configure in which ``direction'' the axis points:
- %
- \begin{key}{/tikz/data visualization/axis options/unit vector=\meta{coordinate} (initially {(1pt,0pt)})}
- Recall that an axis takes the values of an attribute and rescales them
- so that they fit into a ``reasonable'' interval $[t_1,t_2]$. Suppose
- that $v'$ is the rescaled dimension in (\TeX) points. Then when the
- data point is visualized, the coordinate system will be shifted by $v'$
- times the \meta{coordinate}.
-
- As an example, suppose that you have said
- |scaling=0 and 10pt and 50 and 20pt|. Then when the underlying
- attribute has the value |25|, it will be mapped to a $v'$ of $15$
- (because |25| lies in the middle of |0| and |50| and |15pt| lies in the
- middle of |10pt| and |20pt|). This, in turn, causes the data point to
- be displaced by $15$ times the \meta{coordinate}.
-
- The bottom line is that the \meta{coordinate} should usually denote a
- point that is at distance |1pt| from the origin and that points into
- the direction of the axis.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \datavisualization
- [new Cartesian axis=x axis, x axis={attribute=x},
- new Cartesian axis=y axis, y axis={attribute=y},
- x axis={unit vector=(0:1pt)},
- y axis={unit vector=(60:1pt)},
- visualize as scatter]
- data {
- x, y
- 0, 0
- 1, 0
- 2, 0
- 1, 1
- 2, 1
- 1, 1.5
- 2, 1.5
- };
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{key}
-
-
-\subsection{Axis Systems}
-\label{section-dv-axis-systems}
-
-An \emph{axis system} is, as the name suggests, a whole family of axes that act
-in concert. For example, in the ``standard'' axis system there is a horizontal
-axis called the $x$-axis that monitors the |x| attribute (by default, you can
-change this easily) and a vertical axis called the $y$-axis. Furthermore, a
-certain number of ticks are added and labels are placed at sensible positions.
-
-
-\subsubsection{Usage}
-
-Using an axis system is usually pretty easy: You just specify a key like
-|scientific axes| and the necessary axes get initialized with sensible default
-values. You can then start to modify these default values, if necessary.
-
-First, you can (and should) set the attributes to which the difference axes
-refer. For instance, if the |time| attribute is plotted along the $x$-axis, you
-would write
-%
-\begin{codeexample}[code only]
-x axis = {attribute = time}
-\end{codeexample}
-
-Second, you may wish to modify the lengths of the axes. For this, you can use
-keys like |length| or further keys as described in the references later on.
-
-Third, you may often wish to modify how many ticks and grid lines are shown. By
-default, no grid lines are shown, but you can say the following in order to
-cause grid lines to be shown:
-%
-\begin{codeexample}[code only]
-all axes={grid}
-\end{codeexample}
-%
-Naturally, instead of |all axes| you can also specify a single axis, causing
-only grid lines to be shown for this axis. In order to change the number of
-ticks that are shown, you can say
-%
-\begin{codeexample}[code only]
-all axes={ticks=few}
-\end{codeexample}
-%
-or also |many| instead of |few| or even |none|. Far more fine-grained control
-over the tick placement and rendering is possible, see
-Section~\ref{section-dv-ticks-and-grids} for details.
-
-Fourth, consider adding units (like ``cm'' for centimeters or
-``$\mathrm{m}/\mathrm{s}^2$'' for acceleration) to your ticks:
-%
-\begin{codeexample}[code only]
-x axis={ticks={tick unit=cm}}, y axis={ticks={tick unit=m/s^2}}
-\end{codeexample}
-
-Finally, consider adding labels to your axes. For this, use the label option:
-%
-\begin{codeexample}[code only]
-x axes={time $t$ (ms)}, y axis={distance $d$ (mm)}
-\end{codeexample}
-
-Here is an example that employs most of the above features:
-%
-\begin{codeexample}[width=8.5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- scientific axes=clean,
- x axis={attribute=time, ticks={tick unit=ms},
- label={elapsed time}},
- y axis={attribute=v, ticks={tick unit=m/s},
- label={speed of disc}},
- all axes=grid,
- visualize as line]
-data {
- time, v
- 0, 0
- 1, 0.001
- 2, 0.002
- 3, 0.004
- 4, 0.0035
- 5, 0.0085
- 6, 0.0135
-};
-\end{codeexample}
-
-
-\subsubsection{Reference: Scientific Axis Systems}
-
-\begin{key}{/tikz/data visualization/scientific axes=\opt{\meta{options}}}
- This key installs a two-dimensional coordinate system based on the
- attributes |/data point/x| and |/data point/y|.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\begin{tikzpicture}
- \datavisualization [scientific axes,
- visualize as smooth line]
- data [format=function] {
- var x : interval [0:100];
- func y = sqrt(\value x);
- };
-\end{tikzpicture}
-\end{codeexample}
-
- This axis system is usually a good choice to depict ``arbitrary two
- dimensional data''. Because the axes are automatically scaled, you do not
- need to worry about how large or small the values will be. The name
- |scientific axes| is intended to indicate that this axis system is often
- used in scientific publications.
-
- You can use the \meta{options} to fine tune the axis system. The
- \meta{options} will be executed with the following path prefix:
- %
-\begin{codeexample}[code only]
-/tikz/data visualization/scientific axes
-\end{codeexample}
- %
- All keys with this prefix can thus be passed as \meta{options}.
-
- This axis system will always distort the relative magnitudes of the units
- on the two axis. If you wish the units on both axes to be equal, consider
- directly specifying the unit length ``by hand'':
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [visualize as smooth line,
- scientific axes,
- all axes={unit length=1cm per 10 units, ticks={few}}]
- data [format=function] {
- var x : interval [0:100];
- func y = sqrt(\value x);
- };
-\end{tikzpicture}
-\end{codeexample}
-
- The |scientific axes| have the following properties:
- %
- \begin{itemize}
- \item The |x|-values are surveyed and the $x$-axis is then scaled and
- shifted so that it has the length specified by the following key.
- %
- \begin{key}{/tikz/data visualization/scientific axes/width=\meta{dimension} (initially 5cm)}
- \end{key}
- %
- The minimum value is at the left end of the axis and at the canvas
- origin. The maximum value is at the right end of the axis. \item
- The |y|-values are surveyed and the $y$-axis is then scaled so that
- is has the length specified by the following key.
- %
- \begin{key}{/tikz/data visualization/scientific axes/height=\meta{dimension}}
- By default, the |height| is the golden ratio times the |width|.
- \end{key}
- %
- The minimum value is at the bottom of the axis and at the canvas
- origin. The maximum value is at the top of the axis.
- \item Lines (forming a frame) are depicted at the minimum and maximum
- values of the axes in 50\% black.
- \end{itemize}
-
- The following keys are executed by default as options: |outer ticks| and
- |standard labels|.
-
- You can use the following style to overrule the defaults:
-
- \begin{stylekey}{/tikz/data visualization/every scientific axes}
- \end{stylekey}
-\end{key}
-
-The keys described in the following can be used to fine-tune the way the
-scientific axis system is rendered.
-
-\begin{key}{/tikz/data visualization/scientific axes/outer ticks}
- This causes the ticks to be drawn `` on the outside'' of the frame so that
- they interfere as little as possible with the data. It is the default.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\begin{tikzpicture}
- \datavisualization [scientific axes=outer ticks,
- visualize as smooth line]
- data [format=function] {
- var x : interval [-12:12];
- func y = \value x*\value x*\value x;
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/scientific axes/inner ticks}
- This axis system works like |scientific axes|, only the ticks are on the
- ``inside'' of the frame.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\begin{tikzpicture}
- \datavisualization [scientific axes=inner ticks,
- visualize as smooth line]
- data [format=function] {
- var x : interval [-12:12];
- func y = \value x*\value x*\value x;
- };
-\end{tikzpicture}
-\end{codeexample}
-
- This axis system is also common in publications, but the ticks tend to
- interfere with marks if they are near to the border as can be seen in the
- following example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\begin{tikzpicture}
- \datavisualization [scientific axes={inner ticks, width=3.2cm},
- style sheet=cross marks,
- visualize as scatter/.list={a,b}]
- data [set=a] {
- x, y
- 0, 0
- 1, 1
- 0.5, 0.5
- 2, 1
- }
- data [set=b] {
- x, y
- 0.05, 0
- 1.5, 1
- 0.5, 0.75
- 2, 0.5
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/scientific axes/clean}
- The axes and the ticks are completely removed from the actual data, making
- this axis system especially useful for scatter plots, but also for most
- other scientific plots.
- %
-\begin{codeexample}[
- width=7.5cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization [
- scientific axes=clean,
- visualize as smooth line]
-data [format=function] {
- var x : interval [-12:12];
- func y = \value x*\value x*\value x;
-};
-\end{codeexample}
-
- The distance of the axes from the actual plot is given by the padding of
- the axes.
-\end{key}
-
-For all scientific axis systems, different label placement strategies can be
-specified. They are discussed in the following.
-
-\begin{key}{/tikz/data visualization/scientific axes/standard labels}
- As the name suggests, this is the standard placement strategy. The label of
- the $x$-axis is placed below the center of the $x$-axis, the label of the
- $y$-axis is rotated by $90^\circ$ and placed left of the center of the
- $y$-axis.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization
- [scientific axes={clean, standard labels},
- visualize as smooth line,
- x axis={label=degree $d$,
- ticks={tick unit={}^\circ}},
- y axis={label=$\sin d$}]
-data [format=function] {
- var x : interval [-10:10] samples 10;
- func y = sin(\value x);
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/scientific axes/upright labels}
- Works like |scientific axes standard labels|, only the label of the
- $y$-axis is not rotated.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization [
- scientific axes={clean, upright labels},
- visualize as smooth line,
- x axis={label=degree $d$,
- ticks={tick unit={}^\circ}},
- y axis={label=$\cos d$, include value=1,
- ticks={style={
- /pgf/number format/precision=4,
- /pgf/number format/fixed zerofill}}}]
-data [format=function] {
- var x : interval [-10:10] samples 10;
- func y = cos(\value x);
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/scientific axes/end labels}
- Places the labels at the end of the $x$- and the $y$-axis, similar to the
- axis labels of a school book axis system.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization [
- scientific axes={clean, end labels},
- visualize as smooth line,
- x axis={label=degree $d$,
- ticks={tick unit={}^\circ}},
- y axis={label=$\tan d$}]
-data [format=function] {
- var x : interval [-80:80];
- func y = tan(\value x);
-};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Reference: School Book Axis Systems}
-
-\begin{key}{/tikz/data visualization/school book axes=\meta{options}}
- This axis system is intended to ``look like'' the coordinate systems often
- used in school books: The axes are drawn in such a way that they intersect
- to origin. Furthermore, no automatic scaling is done to ensure that the
- lengths of units are the same in all directions.
-
- This axis system must be used with care -- it is nearly always necessary to
- specify the desired unit length by hand using the option |unit length|. If
- the magnitudes of the units on the two axes differ, different unit lengths
- typically need to be specified for the different axes.
-
- Finally, if the data is ``far removed'' from the origin, this axis system
- will also ``look bad''.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [school book axes, visualize as smooth line]
- data [format=function] {
- var x : interval [-1.3:1.3];
- func y = \value x*\value x*\value x;
- };
-\end{tikzpicture}
-\end{codeexample}
-
- The stepping of the ticks is one unit by default. Using keys like
- |ticks=some| may help to give better steppings.
-
- The \meta{options} are executed with the key itself as path prefix. Thus,
- the following subkeys are permissible options:
- %
- \begin{key}{/tikz/data visualization/school book axes/unit=\meta{value}}
- Sets the scaling so that 1\,cm corresponds to \meta{value} units. At
- the same time, the stepping of the ticks will also be set to
- \meta{value}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [school book axes={unit=10},
- visualize as smooth line,
- clean ticks,
- x axis={label=$x$},
- y axis={label=$f(x)$}]
- data [format=function] {
- var x : interval [-20:20];
- func y = \value x*\value x/10;
- };
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/data visualization/school book axes/standard labels}
- This key makes the label of the $x$-axis appear at the right end of
- this axis and it makes the label of the $y$-axis appear at the top of
- the $y$-axis.
-
- Currently, this is the only supported placement strategy for the school
- book axis system.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [school book axes={standard labels},
- visualize as smooth line,
- clean ticks,
- x axis={label=$x$},
- y axis={label=$f(x)$}]
- data [format=function] {
- var x : interval [-1:1];
- func y = \value x*\value x + 1;
- };
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{key}
-
-
-\subsubsection{Advanced Reference: Underlying Cartesian Axis Systems}
-
-The axis systems described in the following are typically not used directly by
-the user. The systems setup \emph{directions} for several axes in some sensible
-way, but they do not actually draw anything on these axes. For instance, the
-|xy Cartesian| creates two axes called |x axis| and |y axis| and makes the
-$x$-axis point right and the $y$-axis point up. In contrast, an axis system
-like |scientific axes| uses the axis system |xy Cartesian| internally and then
-proceeds to setup a lot of keys so that the axis lines are drawn, ticks and
-grid lines are drawn, and labels are placed at the correct positions.
-
-\begin{key}{/tikz/data visualization/xy Cartesian}
- This axis system creates two axes called |x axis| and |y axis| that point
- right and up, respectively. By default, one unit is mapped to one cm.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [xy Cartesian, visualize as smooth line]
- data [format=function] {
- var x : interval [-1.25:1.25];
- func y = \value x*\value x*\value x;
- };
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{key}{/tikz/data visualization/xy axes=\meta{options}}
- This key applies the \meta{options} both to the |x axis| and the
- |y axis|.
- \end{key}
-\end{key}
-
-\begin{key}{/tikz/data visualization/xyz Cartesian cabinet}
- This axis system works like |xy Cartesian|, only it \emph{additionally}
- creates an axis called |z axis| that points left and down. For this axis,
- one unit corresponds to $\frac{1}{2}\sin 45^\circ\mathrm{cm}$. This is also
- known as a cabinet projection.
-
- \begin{key}{/tikz/data visualization/xyz axes=\meta{options}}
- This key applies the \meta{options} both to the |x axis| and the
- |y axis|.
- \end{key}
-\end{key}
-
-\begin{key}{/tikz/data visualization/uv Cartesian}
- This axis system works like |xy Cartesian|, but it introduces two axes
- called |u axis| and |v axis| rather than the |x axis| and the |y axis|. The
- idea is that in addition to a ``major'' $xy$-coordinate system this is also
- a ``smaller'' or ``minor'' coordinate system in use for depicting, say,
- small vectors with respect to this second coordinate system.
-
- \begin{key}{/tikz/data visualization/uv axes=\meta{options}}
- Applies the \meta{options} to both the |u axis| and the |y axis|.
- \end{key}
-\end{key}
-
-\begin{key}{/tikz/data visualization/uvw Cartesian cabinet}
- Like |xyz Cartesian cabinet|, but for the $uvw$-system.
-
- \begin{key}{/tikz/data visualization/uvw axes=\meta{options}}
- Like |xyz axes|.
- \end{key}
-\end{key}
-
-
-\subsection{Ticks and Grids}
-\label{section-dv-ticks-and-grids}
-
-\subsubsection{Concepts}
-
-A \emph{tick} is a small visual indication on an axis of the value of the
-axis's attribute at the position where the tick is shown. A tick may be
-accompanied additionally by a textual representation, but it need not. A
-\emph{grid line} is similar to a tick, but it is not an indication on the axis,
-but rather a whole line that indicates all positions where the attribute has a
-certain value. Unlike ticks, grid lines (currently) are not accompanied by a
-textual representation.
-
-Just as for axes, the data visualization system decouples the specification of
-which ticks are present \emph{in principle} from where they are visualized. In
-the following, I describe how you specify which ticks and grid lines you would
-like to be drawn and how they should look like (their styling). The axis system
-of your choice will then visualize the ticks at a sensible position for the
-chosen system. For details on how to change where whole axis is shown along
-with its ticks, see Section~\ref{section-dv-visualize-ticks}.
-
-Specifying which ticks you are interested in is done as follows: First, you use
-|ticks| key (or, for specifying which grid lines should be present, the |grid|
-key). This key takes several possible options, described in detail in the
-following, which have different effects:
-%
-\begin{enumerate}
- \item Keys like |step=10| or |minor steps between steps| cause a
- ``semi-automatic'' computation of possible steps. Here, you explicitly
- specify the stepping of steps, but the first stepping and their number
- are computed automatically according to the range of possible values
- for the attribute.
- \item Keys like |few|, |some|, or |many| can be passed to |ticks| in order
- to have \tikzname\ compute good tick positions automatically. This is
- usually what you want to happen, which is why most axis system will
- implicitly say |ticks={some}|.
- \item Keys like |at| or |also at| provide ``absolute control'' over which
- ticks or grid lines are shown. For these keys, you can not only specify
- at what value a tick should be shown, but also its styling and also
- whether it is a major, minor, or subminor tick or grid line.
-\end{enumerate}
-
-In the following, the main keys |ticks| and |grids| are documented first. Then
-the different kinds of ways of specifying where ticks or grid lines should be
-shown are explained.
-
-
-\subsubsection{The Main Options: Tick and Grid}
-
-\begin{key}{/tikz/data visualization/axis options/ticks=\meta{options} (default some)}
- This key can be passed to an axis in order to configure which ticks are
- present for the axis. The possible \meta{options} include, for instance,
- keys like |step|, which is used to specify a stepping for the ticks, but
- also keys like |major| or |minor| for specifying the positions of major and
- minor ticks in detail. The list of possible options is described in the
- rest of this section.
-
- Note that the |ticks| option will only configure which ticks should be
- shown in principle. The actual rendering is done only when the
- |visualize ticks| key is used, documented in
- Section~\ref{section-dv-visualize-ticks}, which is typically done only
- internally by an axis system.
-
- The \meta{options} will be executed with the path prefix
- |/tikz/data visualization/|. When the |ticks| key is used multiple times
- for an axis, the \meta{options} accumulate.
- %
-\begin{codeexample}[width=6cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- scientific axes, visualize as line,
- x axis={ticks={step=24, minor steps between steps=3},
- label=hours}]
- data {
- x, y
- 0, 0
- 10, 0
- 20, 0.5
- 30, 0.75
- 40, 0.7
- 50, 0.6
- 60, 0.5
- 70, 0.45
- 80, 0.47
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/axis options/grid=\meta{options} (default at default ticks)}
- This key is similar to |ticks|, only it is used to configure where grid
- lines should be shown rather than ticks. In particular, the options that
- can be passed to the |ticks| key can also be passed to the |grid| key. Just
- like |ticks|, the \meta{options} only specify which grid lines should be
- drawn in principle; it is the job of the |visualize grid| key to actually
- cause any grid lines to be shown.
-
- If you do not specify any \meta{options}, the default text
- |at default ticks| is used. This option causes grid lines to be drawn at
- all positions where ticks are shown by default. Since this usually exactly
- what you would like to happen, most of the time you just need to
- |all axes=grid| to cause a grid to be shown.
-\end{key}
-
-\begin{key}{/tikz/data visualization/axis options/ticks and grid=\meta{options}}
- This key passes the \meta{options} to both the |ticks| key and also to the
- |grid| key. This is useful when you want to specify some special points
- explicitly where you wish a tick to be shown and also a grid line.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [scientific axes,
- visualize as smooth line,
- all axes= {grid, unit length=1.25cm},
- y axis={ ticks=few },
- x axis={ ticks=many, ticks and grid={ major also at={(pi/2) as $\frac{\pi}{2}$}}}]
- data [format=function] {
- var x : interval [-pi/2:3*pi] samples 50;
- func y = sin(\value x r);
- };
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Semi-Automatic Computation of Tick and Grid Line Positions}
-\label{section-dv-concept-tick-placement-strategies}
-
-Consider the following problem: The data visualization engine determines that
-in a plot the $x$-values vary between $17.4$ and $34.5$. In this case, we
-certainly do not want, say, ten ticks at exactly ten evenly spaced positions
-starting with $17.4$ and ending with $34.5$, because this would yield ticks at
-positions like $32.6$. Ticks should be placed at ``nice'' positions like $20$,
-$25$, and $30$.
-
-Determining which positions are ``nice'' is somewhat difficult. In the above
-example, the positions $20$, $25$, and $30$ are certainly nice, but only three
-ticks may be a bit few of them. Better might be the tick positions $17.5$,
-$20$, $22.5$, through to $32.5$. However, users might prefer even numbers over
-fractions like $2.5$ as the stepping.
-
-A \emph{tick placement strategy} is a method of automatically deciding which
-positions are \emph{good} for placing ticks. The data visualization engine
-comes with a number of predefined strategies, but you can also define new ones
-yourself. When the data visualization is requested to automatically determine
-``good'' positions for the placement of ticks on an axis, it uses one of
-several possible \emph{basic strategies}. These strategies differ dramatically
-in which tick positions they will choose: For a range of values between $5$ and
-$1000$, a |linear steps| strategy might place ticks at positions $100$, $200$,
-through to $1000$, while an |exponential steps| strategy would prefer the tick
-positions $10$, $100$ and $1000$. The exact number and values of the tick
-positions chosen by either strategy can be fine-tuned using additional options
-like |step| or |about|.
-
-Here is an example of the different stepping chosen when one varies the tick
-placement strategy:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [scientific axes, visualize as smooth line]
- data [format=function] {
- var x : interval [1:11];
- func y = \value x*\value x;
- };
-\end{tikzpicture}
-\qquad
-\begin{tikzpicture}
- \datavisualization [scientific axes, visualize as smooth line,
- y axis={exponential steps},
- x axis={ticks={quarter about strategy}},
- ]
- data [format=function] {
- var x : interval [1:11];
- func y = \value x*\value x;
- };
-\end{tikzpicture}
-\end{codeexample}
-
-Two strategies are always available: |linear steps|, which yields
-(semi)automatic ticks are evenly spaced positions, and |exponential steps|,
-which yields (semi)automatic steps at positions at exponentially increasing
-positions -- which is exactly what is needed for logarithmic plots. These
-strategies are details in Section~\ref{section-dv-strategies}.
-
-The following options are used to configure tick placement strategies like
-|linear steps|. Unlike the basic choice of a placement strategy, which is an
-axis option, the following should be passed to the option |ticks| or |grid|
-only. So, you would write things like |x axis={ticks={step=2}}|, but
-|x axis={linear steps}|.
-
-\begin{key}{/tikz/data visualization/step=\meta{value} (initially 1)}
- The value of this key is used to determine the spacing of the major ticks.
- The key is used by the |linear steps| and |exponential steps| strategies,
- see the explanations in Section~\ref{section-dv-strategies} for details.
- Basically, all ticks are placed at all multiples of \meta{value} that lie
- in the attribute range interval.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [
- school book axes, visualize as smooth line,
- y axis={ticks={step=1.25}},
- ]
- data [format=function] {
- var x : interval [0:3];
- func y = \value x*\value x/2;
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/minor steps between steps=\meta{number} (default 9)}
- Specifies that between any two major steps (whose positions are specified
- by the |step| key), there should be \meta{number} many minor steps. Note
- that the default of |9| is exactly the right number so that each interval
- between two minor steps is exactly a tenth of the size of a major step. See
- also Section~\ref{section-dv-strategies} for further details.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [school book axes, visualize as smooth line,
- x axis={ticks={minor steps between steps=3}},
- y axis={ticks={minor steps between steps}},
- ]
- data [format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/phase=\meta{value} (initially 0)}
- See Section~\ref{section-dv-strategies} for details on how the phase of
- steps influences the tick placement.
-\end{key}
-
-
-\subsubsection{Automatic Computation of Tick and Grid Line Positions}
-
-The |step| option gives you ``total control'' over the stepping of ticks on an
-axis, but you often do not know the correct stepping in advance. In this case,
-you may prefer to have a good value for |step| being computed for you
-automatically.
-
-Like the |step| key, these options are passed to the |ticks| option. So, for
-instance, you would write |x axis={ticks={about=4}}| to request about four
-ticks to be placed on the $x$-axis.
-
-\begin{key}{/tikz/data visualization/about=\meta{number}}
- This key asks the data visualization to place \emph{about} \meta{number}
- many ticks on an axis. It is not guaranteed that \emph{exactly}
- \meta{number} many ticks will be used, rather the actual number will be the
- closest number of ticks to \meta{number} so that their stepping is still
- ``good''. For instance, when you say |about=10|, it may happen that exactly
- |10|, but perhaps even |13| ticks are actually selected, provided that
- these numbers of ticks lead to good stepping values like |5| or |2.5|
- rather than numbers like |3.4| or |7|. The method that is used to determine
- which steppings a deemed to be ``good'' depends on the current tick
- placement strategy.
-
-
- \medskip
- \textbf{Linear steps.}
- Let us start with |linear steps|: First, the difference between the maximum
- value $v_{\max}$ and the minimum value $v_{\min}$ on the axis is computed;
- let us call it $r$ for ``range''. Then, $r$ is divided by \meta{number},
- yielding a target stepping~$s$. If $s$ is a number like $1$ or $5$ or $10$,
- then this number could be used directly as the new value of |step|.
- However, $s$ will typically something strange like $0.023\,45$ or
- $345\,223.76$, so $s$ must be replaced by a better value like $0.02$ in the
- first case and perhaps $250\,000$ in the second case.
-
- In order to determine which number is to be used, $s$ is rewritten in the
- form $m \cdot 10^k$ with $1 \le m < 10$ and $k \in \mathbb Z$. For
- instance, $0.023\,45$ would be rewritten as $2.345 \cdot 10^{-2}$ and
- $345\,223.76$ as $3.452\,2376 \cdot 10^5$. The next step is to replace the
- still not-so-good number $m$ like $2.345$ or $3.452\,237$ by a ``good''
- value $m'$. For this, the current value of the |about strategy| is used:
- %
- \begin{key}{/tikz/data visualization/about strategy=\meta{list}}
- The \meta{list} is a comma-separated sequence of pairs
- \meta{threshold}/\meta{value} like for instance |1.5/1.0| or |2.3/2.0|.
- When a good value $m'$ is sought for a given $m$, we iterate over the
- list and find the first pair \meta{threshold}/\meta{value} where
- \meta{threshold} exceeds~$m$. Then $m'$ is set to \meta{value}. For
- instance, if \meta{list} is |1.5/1.0,2.3/2.0,4/2.5,7/5,11/10|, which is
- the default, then for $m=3.141$ we would get $m'=2.5$ since $4 >
- 3.141$, but $2.3 \le 3.141$. For $m=6.3$ we would get $m'=5$.
- \end{key}
- %
- Once $m'$ has been determined, the stepping is set to $s' = m' \cdot 10^k$.
-
- % Define an axis type
- \tikzdatavisualizationset{
- one dimensional axis/.style={
- new Cartesian axis=axis,
- axis={
- attribute=main,
- unit vector={(0pt,1pt)},
- visualize axis={style=->},
- visualize ticks={major={tick text at low},direction axis=perpendicular},
- length=3cm
- },
- new Cartesian axis=perpendicular,
- perpendicular={
- attribute=perp,
- unit vector={(1pt,0pt)},
- include value=0,
- include value=1
- }
- }
- }
-
- \def\showstrategy#1{
- % Show the effect for the different strategies
- \medskip
- \begin{tikzpicture}
- \foreach \max/\about [count=\c] in {10/5,20/5,30/5,40/5,50/5,60/5,70/5,80/5,90/5,100/5,100/3,100/10}
- {
- \begin{scope}[xshift=\c pt*30]
- \datavisualization [#1,
- one dimensional axis,
- axis={
- ticks={about=\about},
- include value=0,
- include value=\max
- }
- ];
-
- \node at (0,-5mm) [anchor=mid] {\texttt{\about}};
- \end{scope}
- }
-
- \node at (30pt,-5mm) [anchor=mid east] {\texttt{about=\ \ }};
- \end{tikzpicture}
- }
-
- The net effect of all this is that for the default strategy the only valid
- stepping are the values $1$, $2$, $2.5$ and $5$ and every value obtainable
- by multiplying one of these values by a power of ten. The following example
- shows the effects of, first, setting |about=5| (corresponding to the |some|
- option) and then having axes where the minimum value is always |0| and
- where the maximum value ranges from |10| to |100| and, second, setting
- |about| to the values from |3| (corresponding to the |few| option) and to
- |10| (corresponding to the |many| option) while having the minimum at |0|
- and the maximum at |100|:
-
- \showstrategy{standard about strategy}
-
- \medskip
- \textbf{Exponential steps.}
- For |exponential steps| the strategy for determining a good stepping value
- is similar to |linear steps|, but with the following differences:
- %
- \begin{itemize}
- \item Naturally, since the stepping value refers to the exponent, the
- whole computation of a good stepping value needs to be done ``in
- the exponent''. Mathematically spoken, instead of considering the
- difference $r = v_{\max} - v_{\min}$, we consider the difference $r
- = \log v_{\max} - \log v_{\min}$. With this difference, we still
- compute $s = r / \meta{number}$ and let $s = m \cdot 10^k$ with $1
- \le m < 10$.
- \item It makes no longer sense to use values like $2.5$ for $m'$ since
- this would yield a fractional exponent. Indeed, the only sensible
- values for $m'$ seem to be $1$, $3$, $6$, and $10$. Because of
- this, the |about strategy| is ignored and one of these values or a
- multiple of one of them by a power of ten is used.
- \end{itemize}
-
- The following example shows the chosen steppings for a maximum varying from
- $10^1$ to $10^5$ and from $10^{10}$ to $10^{50}$ as well as for $10^{100}$
- for |about=3|:
-
- \medskip
- \begin{tikzpicture}
- \foreach \max [count=\c] in {1,...,5,10,20,...,50,100}
- {
- \begin{scope}[xshift=\c pt*40]
- \datavisualization [
- one dimensional axis,
- axis={
- logarithmic,
- ticks={about=3},
- include value=1,
- include value=1e\max
- }
- ];
- \end{scope}
- }
- \end{tikzpicture}
-
-
- \medskip
- \textbf{Alternative strategies.}
-
- In addition to the standard |about strategy|, there are some additional
- strategies that you might wish to use instead:
-
- \begin{key}{/tikz/data visualization/standard about strategy}
- Permissible values for $m'$ are: $1$, $2$, $2.5$, and~$5$. This
- strategy is the default strategy.
- \end{key}
-
- \begin{key}{/tikz/data visualization/euro about strategy}
- Permissible values for $m'$ are: $1$, $2$, and~$5$. These are the same
- values as for the Euro coins, hence the name.
-
- \showstrategy{euro about strategy}
- \end{key}
-
- \begin{key}{/tikz/data visualization/half about strategy}
- Permissible values for $m'$: $1$ and $5$. Use this strategy if only
- powers of $10$ or halves thereof seem logical.
-
- \showstrategy{half about strategy}
- \end{key}
-
- \begin{key}{/tikz/data visualization/decimal about strategy}
- The only permissible value for $m'$ is $1$. This is an even more
- radical version of the previous strategy.
-
- \showstrategy{decimal about strategy}
- \end{key}
-
- \begin{key}{/tikz/data visualization/quarter about strategy}
- Permissible values for $m'$ are: $1$, $2.5$, and $5$.
-
- \showstrategy{quarter about strategy}
- \end{key}
-
- \begin{key}{/tikz/data visualization/int about strategy}
- Permissible values for $m'$ are: $1$, $2$, $3$, $4$, and $5$.
-
- \showstrategy{int about strategy}
- \end{key}
-\end{key}
-
-\begin{key}{/tikz/data visualization/many}
- This is an abbreviation for |about=10|.
-\end{key}
-
-\begin{key}{/tikz/data visualization/some}
- This is an abbreviation for |about=5|.
-\end{key}
-
-\begin{key}{/tikz/data visualization/few}
- This is an abbreviation for |about=3|.
-\end{key}
-
-\begin{key}{/tikz/data visualization/none}
- Switches off the automatic step computation. Unless you use |step=|
- explicitly to set a stepping, no ticks will be (automatically) added.
-\end{key}
-
-
-\subsubsection{Manual Specification of Tick and Grid Line Positions}
-
-The automatic computation of ticks and grid lines will usually do a good job,
-but not always. For instance, you might wish to have ticks exactly at, say,
-prime numbers or at Fibonacci numbers or you might wish to have an additional
-tick at $\pi$. In these cases you need more direct control over the
-specification of tick positions.
-
-First, it is important to understand that the data visualization system
-differentiates between three kinds of ticks and grid lines: major, minor, and
-subminor. The major ticks are the most prominent ticks where, typically, a
-textual representation of the tick is shown; and the major grid lines are the
-thickest. The minor ticks are smaller, more numerous, and lie between major
-ticks. They are used, for instance, to indicate positions in the middle between
-major ticks or at all integer positions between major ticks. Finally, subminor
-ticks are even smaller than minor ticks and they lie between minor ticks.
-
-Four keys are used to configure the different kinds:
-
-\begin{key}{/tikz/data visualization/major=\meta{options}}
- The key can be passed as an option to the |ticks| key and also to the
- |grid| key, which in turn is passed as an option to an axis. The
- \meta{options} passed to |major| specify at which positions major
- ticks/grid lines should be shown (using the |at| option and |also at|
- option) and also any special styling. The different possible options are
- described later in this section.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [ school book axes, visualize as smooth line,
- x axis={ticks={major={at={1, 1.5, 2}}}}]
- data [format=function] {
- var x : interval [-1.25:2];
- func y = \value x * \value x / 2;
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/minor=\meta{options}}
- Like |major|, only for minor ticks/grid lines.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [ school book axes, visualize as smooth line,
- x axis={grid={minor={at={1, 1.5, 2}}}}]
- data [format=function] {
- var x : interval [-1.25:2];
- func y = \value x * \value x / 2;
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/subminor=\meta{options}}
- Like |major|, only for subminor ticks/grid lines.
-\end{key}
-
-\begin{key}{/tikz/data visualization/common=\meta{options}}
- This key allows you to specify \meta{options} that apply to |major|,
- |minor| and |subminor| alike. It does not make sense to use |common| to
- specify positions (since you typically do not want both a major and a minor
- tick at the same position), but it can be useful to configure, say, the
- size of all kinds of ticks:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [ school book axes, visualize as smooth line,
- x axis={ticks={minor steps between steps, common={low=0}}} ]
- data [format=function] {
- var x : interval [-1.25:2];
- func y = \value x * \value x / 2;
- };
-\end{codeexample}
- %
-\end{key}
-
-The following keys can now be passed to the |major|, |minor|, and |subminor|
-keys to specify where ticks or grid lines should be shown:
-
-\begin{key}{/tikz/data visualization/at=\meta{list}}
- Basically, the \meta{list} must be a list of values that is processed with
- the |\foreach| macro (thus, it can contain ellipses to specify ranges of
- value). Empty values are skipped.
-
- The effect of passing |at| to a |major|, |minor|, or |subminor| key is that
- ticks or grid lines on the axis will be placed exactly at the values in
- \meta{list}. Here is an example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [ school book axes, visualize as smooth line,
- x axis={ticks={major={at={-1,0.5,(pi/2)}}}}]
- data [format=function] {
- var x : interval [-1.25:2];
- func y = \value x * \value x / 2;
- };
-\end{codeexample}
- When this option is used, any previously specified tick positions are
- overwritten by the values in \meta{list}. Automatically computed ticks are
- also overwritten. Thus, this option gives you complete control over where
- ticks should be placed.
-
- Normally, the individual values inside the \meta{list} are just numbers
- that are specified in the same way as an attribute value. However, such a
- value may also contain the keyword |as|, which allows you so specify the
- styling of the tick in detail. Section~\ref{section-dv-ticks-styling}
- details how this works.
-
- It is often a bit cumbersome that one has to write things like
- %
-\begin{codeexample}[code only]
-some axis = {ticks = {major = {at = {...}}}}
-\end{codeexample}
- %
- A slight simplification is given by the following keys, which can be passed
- directly to |ticks| and |grid|:
- %
- \begin{key}{/tikz/data visualization/major at=\meta{list}}
- A shorthand for |major={at={|\meta{list}|}}|.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/minor at=\meta{list}}
- A shorthand for |major={at={|\meta{list}|}}|.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/subminor at=\meta{list}}
- A shorthand for |major={at={|\meta{list}|}}|.
- \end{key}
-\end{key}
-
-\begin{key}{/tikz/data visualization/also at=\meta{list}}
- This key is similar to |at|, but it causes ticks or grid lines to be placed
- at the positions in the \meta{list} \emph{in addition} to the ticks that
- have already been specified either directly using |at| or indirectly using
- keys like |step| or |some|. The effect of multiple calls of this key
- accumulate. However, when |at| is used after an |also at| key, the |at| key
- completely resets the positions where ticks or grid lines are shown.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [ school book axes, visualize as smooth line,
- x axis={grid, ticks and grid={major={also at={0.5}}}}]
- data [format=function] {
- var x : interval [-1.25:2];
- func y = \value x * \value x / 2;
- };
-\end{codeexample}
- %
- As for |at|, there are some shorthands available:
- %
- \begin{key}{/tikz/data visualization/major also at=\meta{list}}
- A shorthand for |major={also at={|\meta{list}|}}|.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/minor also at=\meta{list}}
- A shorthand for |major={also at={|\meta{list}|}}|.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/subminor also at=\meta{list}}
- A shorthand for |major={also at={|\meta{list}|}}|.
- \end{key}
-\end{key}
-
-
-\subsubsection{Styling Ticks and Grid Lines: Introduction}
-\label{section-dv-ticks-styling}
-
-When a tick, a tick label, or a grid line is visualized on the page, a whole
-regiment of styles influences the appearance. The reason for this large number
-of interdependent styles is the fact that we often wish to influence only a
-very certain part of how a tick is rendered while leaving the other aspects
-untouched: Sometimes we need to modify just the font of the tick label;
-sometimes we wish to change the length of the tick label and the tick label
-position at the same time; sometimes we wish to change the color of grid line,
-tick, and tick label; and sometimes we wish to generally change the thickness
-of all ticks.
-
-Let us go over the different kinds of things that can be styled (grid lines,
-ticks, and tick labels) one by one and let us have a look at which styles are
-involved. We will start with the grid lines, since they turn out to be the most
-simple, but first let us have a look at the general |style| and |styling|
-mechanism that is used in many placed in the following:
-
-
-\subsubsection{Styling Ticks and Grid Lines: The Style and Node Style Keys}
-\label{section-dv-style}
-
-All keys of the data visualization system have the path prefix
-|/tikz/data visualization|. This is not only true for the main keys like
-|scientific axes| or |visualize as line|, but also for keys that govern how
-ticks are visualized. In particular, a style like |every major grid| has the
-path prefix |/tikz/data visualization| and all keys stored in this style are
-also executed with this path prefix.
-
-Normally, this does not cause any trouble since most of the keys and even
-styles used in a data visualization are intended to configure what is shown in
-the visualization. However, at some point, we may also with to specify options
-that no longer configure the visualization in general, but specify the
-appearance of a line or a node on the \tikzname\ layer.
-
-Two keys are used to ``communicate'' with the \tikzname\ layer:
-
-\begin{key}{/tikz/data visualization/style=\meta{\tikzname\ options}}
- This key takes options whose path prefix is |/tikz|, not
- |/tikz/data visualization|. These options will be \emph{appended} to a
- current list of such options (thus, multiple calls of this key accumulate).
- The resulting list of keys is not executed immediately, but it will be
- executed whenever the data visualization engine calls the \tikzname\ layer
- to draw something (this placed will be indicated in the following).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [scientific axes,
- all axes={ticks={style=blue}, length=3cm},
- y axis={grid, grid={minor steps between steps, major={style=red}}},
- visualize as line]
- data [format=function] {
- var x : interval [5:10];
- func y = \value x * \value x;
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/styling}
- Executing this key will cause all ``accumulated'' \tikzname\ options from
- previous calls to the key |/tikz/data visualization/style| to be executed.
- Thus, you use |style| to set \tikzname\ options, but you use |styling| to
- actually apply these options. Usually, you do not call this option directly
- since this application is only done deep inside the data visualization
- engine.
-\end{key}
-
-Similar to |style| (and |styling|) there also exist the |node style| (and
-|node styling|) key that takes \tikzname\ options that apply to nodes only --
-in addition to the usual |style|.
-
-\begin{key}{/tikz/data visualization/node style=\meta{\tikzname\ options}}
- This key works like |style|, but it has an effect only on nodes that are
- created during a data visualization. This includes tick labels and axis
- labels:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [scientific axes,
- all axes={ticks={node style=red}, length=3cm},
- visualize as line]
- data [format=function] {
- var x : interval [5:10];
- func y = \value x * \value x;
- };
-\end{codeexample}
- %
- Note that in the example the ticks themselves (the little thicker lines)
- are not red.
-\end{key}
-
-\begin{key}{/tikz/data visualization/node styling}
- Executing this key will cause all ``accumulated'' node stylings to be
- executed.
-\end{key}
-
-
-\subsubsection{Styling Ticks and Grid Lines: Styling Grid Lines}
-\label{section-dv-styling-grid-lines}
-
-When a grid line is visualized, see
-Section~\ref{section-dv-visualize-gridlines} for details on when this happens,
-the following styles are executed in the specified order.
-%
-\begin{enumerate}
- \item |grid layer|.
- \item |every grid|.
- \item |every major grid| or |every minor grid| or |every subminor grid|,
- depending on the kind of grid line.
- \item locally specified options for the individual grid line, see
- Section~\ref{section-dv-local-styles}.
- \item |styling|, see Section~\ref{section-dv-style}.
-\end{enumerate}
-
-All of these keys have the path prefix |/tikz/data visualization|. However, the
-options stored in the first style (|grid layer|) and also in the last
-(|styling|) are executed with the path prefix |/tikz| (see
-Section~\ref{section-dv-style}).
-
-Let us now have a look at these keys in detail:
-
-\begin{stylekey}{/tikz/data visualization/grid layer (initially on background layer)}
-\label{section-dv-grid-layer}%
- This key is used to specified the \emph{layer} on which grid lines should
- be drawn (layers are explained in Section~\ref{section-tikz-backgrounds}).
- By default, all grid lines are placed on the |background| layer and thus
- behind the data visualization. This is a sensible strategy since it avoids
- obscuring the more important data with the far less important grid lines.
- However, you can change this style to ``get the grid lines to the front'':
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [scientific axes,
- all axes={
- length=3cm,
- grid,
- grid={minor steps between steps}
- },
- grid layer/.style=, % none, so on top of data (bad idea)
- visualize as line]
- data [format=function] {
- var x : interval [5:10];
- func y = \value x * \value x;
- };
-\end{codeexample}
- %
- When this style is executed, the keys stored in the style will be executed
- with the prefix |/tikz|. Normally, you should only set this style to be
- empty or to |on background layer|.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/data visualization/every grid}
- This style provides overall configuration options for grid lines. By
- default, it is set to the following:
- %
-\begin{codeexample}[code only]
-low=min, high=max
-\end{codeexample}
- %
- This causes grid lines to span all possible values when they are
- visualized, which is usually the desired behavior (the |low| and |high|
- keys are explained in Section~\ref{section-dv-visualize-ticks}. You can
- append the |style| key to this style to configure the overall appearance of
- grid lines. It should be noted that settings to |style| inside |every grid|
- will take precedence over ones in |every major grid| and |every minor grid|.
- In the following example we cause all grid lines to be dashed (which is not
- a good idea in general since it creates a distracting background pattern).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [scientific axes,
- all axes={length=3cm, grid},
- every grid/.append style={style=densely dashed},
- visualize as line]
- data [format=function] {
- var x : interval [5:10];
- func y = \value x * \value x;
- };
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/data visualization/every major grid}
- This style configures the appearance of major grid lines. It does so by
- calling the |style| key to setup appropriate \tikzname\ options for
- visualizing major grid lines. The default definition of this style is:
- %
-\begin{codeexample}[code only]
-style = {help lines, thin, black!25}
-\end{codeexample}
- %
- In the following example, we use thin major blue grid lines:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [scientific axes,
- all axes={
- length=3cm,
- grid,
- grid={minor steps between steps}
- },
- every major grid/.style = {style={blue, thin}},
- visualize as line]
- data [format=function] {
- var x : interval [5:10];
- func y = \value x * \value x;
- };
-\end{codeexample}
- %
- As can be seen, this is not exactly visually pleasing. The default settings
- for the grid lines should work in most situations; you may wish to increase
- the blackness level, however, when you experience trouble during printing
- or projecting graphics.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/data visualization/every minor grid}
- Works like |every major grid|. The default is
- %
-\begin{codeexample}[code only]
-style = {help lines, black!25}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/data visualization/every subminor grid}
- Works like |every major grid|. The default is
- %
-\begin{codeexample}[code only]
-style = {help lines, black!10}
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsubsection{Styling Ticks and Grid Lines: Styling Ticks and Tick Labels}
-\label{section-dv-styling-ticks}
-
-Styling ticks and tick labels is somewhat similar to styling grid lines. Let us
-start with the tick \emph{mark}, that is, the small line that represents the
-tick. When this mark is drawn, the following styles are applied:
-%
-\begin{enumerate}
- \item |every ticks|.
- \item |every major ticks| or |every minor ticks| or |every subminor ticks|,
- depending on the kind of ticks to be visualized.
- \item locally specified options for the individual tick, see
- Section~\ref{section-dv-local-styles}.
- \item |tick layer|
- \item |every odd tick| or |every even tick|, see
- Section~\ref{section-dv-stacking}.
- \item |draw|
- \item |styling|, see Section~\ref{section-dv-style}.
-\end{enumerate}
-
-For the tick label node (the node containing the textual representation of the
-attribute's value at the tick position), the following styles are applied:
-%
-\begin{enumerate}
- \item |every ticks|.
- \item |every major ticks| or |every minor ticks| or |every subminor ticks|,
- depending on the kind of ticks to be visualized.
- \item locally specified options for the individual tick, see
- Section~\ref{section-dv-local-styles}.
- \item |tick node layer|
- \item |every odd tick| or |every even tick|, see
- Section~\ref{section-dv-stacking}.
- \item |styling|, see Section~\ref{section-dv-style}.
- \item |node styling|, see Section~\ref{section-dv-style}.
-\end{enumerate}
-
-\begin{stylekey}{/tikz/data visualization/every ticks}
- This style allows you to configure the appearance of ticks using the
- |style| and |node style| key. Here is (roughly) the default definition of
- this style:
- %
-\begin{codeexample}[code only]
-node style={
- font=\footnotesize,
- inner sep=1pt,
- outer sep=.1666em,
- rounded corners=1.5pt
-}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/data visualization/every major ticks}
- The default is
- %
-\begin{codeexample}[code only]
- style={line cap=round}, tick length=2pt
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/data visualization/every minor ticks}
- The default is
- %
-\begin{codeexample}[code only]
- style={help lines,thin, line cap=round}, tick length=1.4pt
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/data visualization/every subminor ticks}
- The default is
- %
-\begin{codeexample}[code only]
- style={help lines, line cap=round}, tick length=0.8pt
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/data visualization/tick layer (initially on background layer)}
- Like |grid layer|, this key specifies on which layer the ticks should be
- placed.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/data visualization/tick node layer (initially \normalfont empty)}
- Like |tick layer|, but now for the nodes. By default, tick nodes are placed
- on the main layer and thus on top of the data in case that the tick nodes
- are inside the data.
-\end{stylekey}
-
-
-\subsubsection{Styling Ticks and Grid Lines: Exceptional Ticks}
-
-You may sometimes wish to style a few ticks differently from the other ticks.
-For instance, in the axis system |school book axes| there should be a tick
-label at the |0| position only on one axis and then this label should be offset
-a bit. In many cases this is easy to achieve: When you add a tick ``by hand''
-using the |at| or |also at| option, you can add any special options in square
-brackets.
-
-However, in some situations the special tick position has been computed
-automatically for you, for instance by the |step| key or by saying |tick=some|.
-In this case, adding a tick mark with the desired options using |also at| would
-cause the tick mark with the correct options to be shown in addition to the
-tick mark with the wrong options. In cases like this one, the following option
-may be helpful:
-
-\begin{key}{/tikz/data visualization/options at=\meta{value} |as [|\meta{options}|]|}
- This key causes the \meta{options} to be executed for any tick mark(s) at
- \meta{value} in addition to any options given already for this position:
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line,
- x axis={ticks={major={
- options at = 3 as [no tick text],
- also at = (pi) as
- [{tick text padding=1ex}] $\pi$}}}]
-data [format=function] {
- var x : interval[0:2*pi];
- func y = sin(\value x r);
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/no tick text at=\meta{value}}
- Shorthand for |options at=|\meta{value}| as [no tick text]|.
-\end{key}
-
-
-\subsubsection{Styling Ticks and Grid Lines: Styling and Typesetting a Value}
-\label{section-dv-local-styles}
-\label{section-dv-tick-labels}
-
-The \todosp{why 2 labels?} |at| and |also at| key allow you to provide a
-comma-separated \meta{list} of \meta{value}s where ticks or grid lines should
-be placed. In the simplest case, the \meta{value} is simply a number. However,
-the general syntax allows three different kinds of \meta{value}s:
-%
-\begin{enumerate}
- \item \meta{value}
- \item \meta{value} |as| |[|\meta{local options}|]|
- \item \meta{value} |as| \opt{|[|\meta{local options}|]|} \meta{text}
-\end{enumerate}
-
-In the first case, the \meta{value} is just a number that is interpreted like
-any other attribute value.
-
-In the second case, where the keyword |as| is present, followed by some option
-in square brackets, but nothing following the closing square bracket, when the
-tick or grid line at position \meta{value} is shown, the \meta{local options}
-are executed first. These can use the |style| key or the |node style| key to
-configure the appearance of this single tick or grid line. You can also use
-keys like |low| or |high| to influence how large the grid lines or the ticks
-are or keys like |tick text at low| to explicitly hide or show a tick label.
-
-In the third case, which is only important for |ticks| and not for |grid|, the
-same happens as in the second case, but the text that is shown as tick label is
-\meta{text} rather than the automatically generated tick label. This automatic
-generation of tick labels is explained in the following.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [scientific axes=clean,
- x axis={length=2.5cm, ticks={major at={
- 5,
- 6 as [style=red],
- 7 as [{style=blue, low=-1em}],
- 8 as [style=green] $2^3$,
- 10 as ten
- }}},
- visualize as line]
- data [format=function] {
- var x : interval [5:10];
- func y = \value x * \value x;
- };
-\end{codeexample}
-
-A value like ``2'' or ``17'' could just be used as \meta{text} to be displayed
-in the node of a tick label. However, things are more difficult when the
-to-be-shown value is $0.0000000015$, because we then would typically (but not
-always) prefer something like $1.5 \cdot 10^{-9}$ to be shown. Also, we might
-wish a unit to be added like $23\mathrm{m}/\mathrm{s}$. Finally, we might wish
-a number like $3.141$ to be replaced by $\pi$. For these reasons, the data
-visualization system does not simply put the to-be-shown value in a node as
-plain text. Instead, the number is passed to a \emph{typesetter} whose job it
-is to typeset this number nicely using \TeX's typesetting capabilities. The
-only exception is, as indicated above, the third syntax version of the |at| and
-|also at| keys, where \meta{text} is placed in the tick label's node,
-regardless of what the typesetting would usually do.
-
-The text produced by the automatic typesetting is computed as follows:
-%
-\begin{enumerate}
- \item The current contents of the key |tick prefix| is put into the node.
- \item This is followed by a call of the key |tick typesetter| which gets
- the \meta{value} of the tick as its argument in scientific notation.
- \item This is followed by the contents of the key |tick suffix|.
-\end{enumerate}
-
-Let us have a look at these keys in detail:
-
-\begin{key}{/tikz/data visualization/tick prefix=\meta{text} (initially \normalfont empty)}
- The \meta{text} will be put in front of every typeset tick:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [scientific axes, all axes={ticks=few, length=2.5cm},
- x axis={ticks={tick prefix=$\langle$, tick suffix=$]$}},
- visualize as line]
- data [format=function] {
- var x : interval [5:10];
- func y = \value x * \value x;
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/tick suffix=\meta{text} (initially \normalfont empty)}
- Works like |tick prefix|. This key is especially useful for adding units
- like ``cm'' or ``$\mathrm m/\mathrm s$'' to every tick label. For this
- reason, there is a (near) alias that is easier to memorize:
- %
- \begin{key}{/tikz/data visualization/tick unit=\meta{roman math text}}
- A shorthand for |tick suffix={$\,\rm|\meta{roman math text}|$}|:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization
- [scientific axes, all axes={length=3cm},
- x axis={ticks={tick unit=s}},
- y axis={ticks={tick unit=m/s^2}},
- visualize as line]
- data [format=function] {
- var x : interval [5:10];
- func y = \value x * \value x;
- };
-\end{codeexample}
- \end{key}
-\end{key}
-
-\begin{key}{/tikz/data visualization/tick typesetter=\meta{value}}
- The key gets called for each number that should be typeset. The argument
- \meta{value} will be in scientific notation (like |1.0e1| for $10$). By
- default, this key applies |\pgfmathprintnumber| to its argument. This
- command is a powerful number printer whose configuration is documented in
- Section~\ref{pgfmath-numberprinting}.
-
- You are invited to code underlying this key so that a different typesetting
- mechanism is used. Here is a (not quite finished) example that shows how,
- say, numbers could be printed in terms of multiples of $\pi$:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\def\mytypesetter#1{%
- \pgfmathparse{#1/pi}%
- \pgfmathprintnumber{\pgfmathresult}$\pi$%
-}
-\tikz \datavisualization
- [school book axes, all axes={unit length=1.25cm},
- x axis={ticks={step=(0.5*pi), tick typesetter/.code=\mytypesetter{##1}}},
- y axis={include value={-1,1}},
- visualize as smooth line]
- data [format=function] {
- var x : interval [0.5:7];
- func y = sin(\value x r);
- };
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Stacked Ticks}
-\label{section-dv-stacking}
-
-Sometimes, the text of tick labels are so long or so numerous that the text of
-adjacent tick labels overlap (or have too little padding):
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes,
- all axes={length=2.5cm},
- visualize as smooth line]
- data [format=function] {
- var y : interval[-100:100];
- func x = \value y*\value y;
- };
-\end{codeexample}
-%
-There are two ways to address this problem:
-%
-\begin{itemize}
- \item One can rotate the labels on horizontal axes:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes,
- all axes={length=2.5cm},
- x axis={ticks={node style={rotate=90, anchor=east}}},
- visualize as smooth line]
- data [format=function] {
- var y : interval[-100:100];
- func x = \value y*\value y;
- };
-\end{codeexample}
- %
- This is often a good solution, but may be hard to read. Also consider
- rotating labels only by $45^\circ$ or $30^\circ$.
- \item One can specify different shifts of the nodes for the different
- ticks, whereby the ticks text no longer overlap.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes,
- all axes={length=2.5cm},
- x axis={ticks={major at={0,4000,8000,
- 2000 as [node style={yshift=-1em}],
- 6000 as [node style={yshift=-1em}],
- 10000 as [node style={yshift=-1em}]}}},
- visualize as smooth line]
- data [format=function] {
- var y : interval[-100:100];
- func x = \value y*\value y;
- };
-\end{codeexample}
- %
- However, specifying shifts ``by hand'' in the above way is not always
- an option, especially when the tick positions should be computed
- automatically. Instead, the |stack| option can be used, which is much
- easier to use and gives better results:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes,
- all axes={length=2.5cm}, x axis={ticks=stack},
- visualize as smooth line]
- data [format=function] {
- var y : interval[-100:100];
- func x = \value y*\value y;
- };
-\end{codeexample}
- %
-\end{itemize}
-
-The |stack| option is actually just a style that gives you access to the
-general even/odd mechanism for ticks with labels. Whenever a tick mark is
-created where a tick label is also to be drawn, two special things happen:
-%
-\begin{enumerate}
- \item For every odd tick mark, the |every odd tick| style is executed, for
- every even tick mark the |every even tick|. Here, ``odd'' and ``even''
- are with respect to the order in which the ticks have been added to the
- list of |at| positions for each major, minor, or subminor tick list,
- not with respect to the order in which they will appear on the axis.
- Thus, when you write
- %
-\begin{codeexample}[code only]
-ticks={major at={1,2,3,4}, major at={0,-1,-2}, minor at={9,8,7}}
-\end{codeexample}
- %
- then for |1|, |3|, |0|, and |-2| as well as |9| and |7| the key
- |every odd tick| will be executed, while |every even tick| will be
- executed for positions |2|, |4|, |-1|, and also |8|.
- \item When a tick node label is shown at the |low| position of the tick
- mark, the dimension stored in the key |tick text low even padding| is
- added to the |low| value. Provided that this padding is not zero (which
- is the default), the length of the even tick marks will be increased
- and the tick label node will be placed at a greater distance from the
- axis.
-
- Similar keys exist for padding ticks with labels at high positions and
- also at even positions.
-\end{enumerate}
-
-\begin{key}{/tikz/data visualization/tick text low even padding=\meta{dimension} (initially 0pt)}
- When a tick label is shown at the low position of an even tick, the
- \meta{distance} is added to the |low| value, see also
- Section~\ref{section-dv-visualize-ticks}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes,
- all axes={length=2.5cm},
- x axis={ticks={tick text low even padding=-1em}},
- visualize as smooth line]
- data [format=function] {
- var y : interval[-100:100];
- func x = \value y*\value y;
- };
-\end{codeexample}
- %
- Note that \meta{dimension} should usually be non-positive.
-\end{key}
-
-The following keys work similarly:
-%
-\begin{key}{/tikz/data visualization/tick text low odd padding=\meta{dimension} (initially 0pt)}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/tick text high even padding=\meta{dimension} (initially 0pt)}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/tick text high odd padding=\meta{dimension} (initially 0pt)}
-\end{key}
-
-\begin{key}{/tikz/data visualization/tick text odd padding=\meta{dimension}}
- A shorthand for setting |tick text odd low padding| and
- |tick text odd high padding| at the same time.
-\end{key}
-
-\begin{key}{/tikz/data visualization/tick text even padding=\meta{dimension}}
- A shorthand for setting |tick text even low padding| and
- |tick text even high padding| at the same time.
-\end{key}
-
-\begin{key}{/tikz/data visualization/tick text padding=\meta{dimension}}
- Sets all text paddings to \meta{dimension}.
-\end{key}
-
-\begin{key}{/tikz/data visualization/stack=\meta{dimension} (default 1em)}
- Shorthand for |tick text even padding=|\meta{dimension}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes,
- all axes={length=2.5cm},
- x axis={ticks={stack=1.5em}},
- visualize as smooth line]
- data [format=function] {
- var y : interval[-100:100];
- func x = \value y*\value y;
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/stack'=\meta{dimension}}
- Shorthand for |tick text odd padding=|\meta{dimension}. The difference to
- |stack| is that the set of value that are ``lowered'' is exactly exchanged
- with the set of value ``lowered'' by |stack|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes,
- all axes={length=2.5cm},
- x axis={ticks=stack'},
- visualize as smooth line]
- data [format=function] {
- var y : interval[-100:100];
- func x = \value y*\value y;
- };
-\end{codeexample}
- %
-\end{key}
-
-Note that the above keys have an effect on all tick labels of an axis, also on
-special ticks that you may have added using the |also at| key. When using the
-|stack| key, you should specify a |tick text padding| explicitly for such keys:
-%
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization
- [scientific axes,
- x axis={ticks={stack, many, major also at=
- {(pi) as [{tick text padding=2.5em}] $\pi$}}},
- visualize as smooth line]
- data [format=function] {
- var x : interval[0:(2*pi)];
- func y = sin(\value x r);
- };
-\end{codeexample}
-
-
-\subsubsection{Reference: Basic Strategies}
-\label{section-dv-strategies}
-
-\begin{key}{/tikz/data visualization/axis options/linear steps}
- This strategy places ticks at positions that are evenly spaced by the
- current value of |step|.
-
- In detail, the following happens: Let $a$ be the minimum value of the data
- values along the axis and let $b$ be the maximum. Let the current
- \emph{stepping} be $s$ (the stepping is set using the |step| option, see
- below) and let the current \emph{phasing} be $p$ (set using the |phase|)
- option. Then ticks are placed all positions $i\cdot s + p$ that lie in the
- interval $[a,b]$, where $i$ ranges over all integers.
-
- The tick positions computed in the way described above are \emph{major}
- step positions. In addition to these, if the key
- |minor steps between steps| is set to some number $n$, then $n$ many minor
- ticks are introduced between each two major ticks (and also before and
- after the last major tick, provided the values still lie in the interval
- $[a,b]$). Note that is $n$ is $1$, then one minor tick will be added in the
- middle between any two major ticks. Use a value of $9$ (not $10$) to
- partition the interval between two major ticks into ten equally sized minor
- intervals.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\begin{tikzpicture}
- \datavisualization
- [scientific axes={inner ticks, width=3cm},
- x axis={ticks={step=3, minor steps between steps=2}},
- y axis={ticks={step=.36}},
- visualize as scatter]
- data {
- x, y
- 17, 30
- 34, 32
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\label{section-dv-exponential-strategy}
-
-\begin{key}{/tikz/data visualization/axis options/exponential steps}
- This strategy produces ticks at positions that are appropriate for
- logarithmic plots. It is automatically selected when you use the
- |logarithmic| option with an axis.
-
- In detail, the following happens: As for |linear steps| let numbers $a$,
- $b$, $s$, and $p$ be given. Then, major ticks are placed at all positions
- $10^{i\cdot s+p}$ that lie in the interval $[a,b]$ for $i \in \mathbb{Z}$.
-
- The minor steps are added in the same way as for |linear steps|. In
- particular, they interpolate \emph{linearly} between major steps.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\begin{tikzpicture}
- \datavisualization
- [scientific axes,
- x axis={logarithmic, length=2cm, ticks={step=1.5}},
- y axis={logarithmic, ticks={step=1, minor steps between steps=9}},
- visualize as scatter]
- data {
- x, y
- 1, 10
- 1000, 1000000
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Advanced: Defining New Placement Strategies}
-
-\begin{key}{/tikz/data visualization/axis options/tick placement strategy=\meta{macro}}
- This key can be used to install a so-called \emph{tick placement strategy}.
- Whenever |visualize ticks| is used to request some ticks to be visualized,
- it is checked whether some automatic ticks should be created. This is the
- case when the following key is set:
- %
- \begin{key}{/tikz/data visualization/compute step=\meta{code}}
- The \meta{code} should compute a suitable value for the stepping to be
- used by the \meta{macro} in the tick placement strategy.
-
- For instance, the |step| key sets |compute step| to
- |\def\tikz@lib@dv@step{#1}|. Thus, when you say |step=5|, then the
- desired stepping of |5| is communicated to the \meta{macro} via the
- macro |\tikz@lib@dv@step|.
- \end{key}
-
- Provided |compute step| is set to some nonempty value, upon visualization
- of ticks the \meta{macro} is executed. Typically, \meta{macro} will first
- call the \meta{code} stored in the key |compute step|. Then, it should
- implement some strategy then uses the value of the computed or desired
- stepping to create appropriate |at| commands. To be precise, it should set
- the keys |major|, |minor|, and/or |subminor| with some appropriate |at|
- values.
-
- Inside the call of \meta{macro}, the macro |\tikzdvaxis| will have been set
- to the name of the axis for which default ticks need to be computed. This
- allows you to access the minimum and the maximum value stored in the
- |scaling mapper| of that axis.
- %
-\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
-\def\silly{
- \tikzdatavisualizationset{major={at={
- 2,3,5,7,11,13}}}
-}
-\begin{tikzpicture}
- \datavisualization [
- scientific axes, visualize as scatter,
- x axis={tick placement strategy=\silly}
- ]
- data {
- x, y
- 0, 0
- 15, 15
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Advanced: Creating New Axis Systems}
-
-The |datavisualization| library comes with a number of predefined axis systems,
-like |scientific axes=clean|, but it is also possible and to define new axis
-systems. Doing so involves the following steps:
-%
-\begin{enumerate}
- \item Creating a number of axes.
- \item Configuring attributes of these axes like their length or default
- scaling.
- \item Creating visual representations of the axes.
- \item Creating visual representations of the ticks and grid lines.
-\end{enumerate}
-
-The first step uses |new ... axis| keys to create new axes, the last steps use
-|visualize ...| keys to create the visual representations of the axes.
-
-Note that the axis system has no control over the actual attribute value ranges
-and neither over which ticks need to be drawn. The axis system can only provide
-good defaults and then specify \emph{how} the ticks or labels should be drawn
-and \emph{where} on the page -- but not at which values.
-
-In the following, as a running example let us develop an axis system
-|our system| that does the following: For the $x$-axis is looks like a normal
-scientific axis system, but there are actually two $y$-axes: One at the left
-and one at the right, each using a different attribute, but both coexisting in
-the same picture.
-
-
-\subsubsection{Creating the Axes}
-
-A new axis system is created as a style key with the prefix
-|/tikz/data visualization|. Thus, we would write:
-%
-\begin{codeexample}[code only]
-\tikzset{
- data visualization/our system/.style={
- ...
- }
-}
-\end{codeexample}
-
-In our system we need three axis: The $x$-axis, the left axis and the right
-axis. Since all of these axes are Cartesian axes, we write the following:
-%
-\begin{codeexample}[code only]
-\tikzset{
- data visualization/our system/.style={
- new Cartesian axis=x axis,
- new Cartesian axis=left axis,
- new Cartesian axis=right axis,
- x axis={attribute=x},
- left axis={unit vector={(0cm,1pt)}},
- right axis={unit vector={(0cm,1pt)}},
- }
-}
-\end{codeexample}
-%
-As can be seen, we also configure things so that the $x$-axis will use the |x|
-attribute by default (users can later change this by saying
-|x axis={attribute=|\meta{some other attribute}|}|), but we do not configure
-the attributes of the |left axis| nor the |right axis|. We also make the left
-and right axis point upward (the |x axis| needs no configuration here since a
-Cartesian axis points right by default). The reason is the |left| would not be
-a particularly good attribute name and this way we ensure that users have to
-pick names themselves (hopefully good ones).
-
-The next step is to define a standard scaling for the axes. Here, we can use
-the same as for |scientific axes|, so we would add the following keys to the
-definition of |our system|:
-%
-\begin{codeexample}[code only]
-x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
-left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
-right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
-\end{codeexample}
-
-We now already have enough to try our system, although we will not yet see any
-axes or ticks, but we will see the correct scaling of the attributes. Let us
-first define a data group:
-%
-\begin{codeexample}[setup code]
-\tikz \datavisualization data group {people and money} = {
- data [set=people 1] {
- time, people
- 1900, 1000000000
- 1920, 1500000000
- 1930, 2000000000
- 1980, 3000000000
- }
- data [set=people 2] {
- time, people
- 1900, 2000000000
- 1920, 2500000000
- 1940, 4000000000
- 2000, 5700000000
- }
- data [set=money 1] {
- time, money
- 1910, 1.1
- 1920, 2
- 1930, 5
- 1980, 2
- }
- data [set=money 2] {
- time, money
- 1950, 3
- 1960, 3
- 1970, 4
- 1990, 3.5
- }
- };
-\end{codeexample}
-
-\begin{codeexample}[setup code,hidden]
-\tikzdatavisualizationset{
- our system/.style={
- new Cartesian axis=x axis,
- new Cartesian axis=left axis,
- new Cartesian axis=right axis,
- x axis={attribute=x},
- left axis={unit vector={(0cm,1pt)}},
- right axis={unit vector={(0cm,1pt)}},
- x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
- left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
- right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
- }
-}
-\end{codeexample}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, length=4cm},
- left axis ={attribute=money},
- right axis={attribute=people},
- visualize as line/.list={people 1, people 2, money 1, money 2},
- people 1={style={visualizer color=blue}},
- people 2={style={visualizer color=blue!50}},
- money 1={style={visualizer color=red}},
- money 2={style={visualizer color=red!50}}]
- data group {people and money};
-\end{codeexample}
-
-
-\subsubsection{Visualizing the Axes}
-\label{section-dv-visualize-axis}
-
-We must now show the axes themselves. For this we can use the |visualize axis|
-key:
-
-\begin{key}{/tikz/data visualization/axis options/visualize axis=\meta{options}}
- This key is passed to an axis as an option. It causes a visual
- representation of the axis to be created during the data visualization. The
- \meta{options} are used to determine where the axis should be drawn and how
- long it should be. We can specify, for instance, that an axis should be
- drawn at the minimum value of another axis or where another axis has the
- value |0|.
-
-
- \medskip
- \textbf{The goto, high, and low Keys.}
- In our example, the |left axis| should be shown at the left hand side. This
- is the position where the |x axis| has its minimum value. To specify this,
- we would use the following code:
- %
-\begin{codeexample}[code only]
-left axis={ visualize axis={ x axis={ goto=min } }
-\end{codeexample}
- %
- As can be seen, we can pass another axis as an \meta{option} to
- |visualize axis|, where we pass the following key to the axis in turn:
- %
- \begin{key}{/tikz/data visualization/axis options/goto=\meta{value}}
- The key can be passed to an axis. It will set the attribute monitored
- by the axis to the given \meta{value}, which is usually some number.
- However, \meta{value} may also be one of the following, which causes a
- special behavior:
- %
- \begin{itemize}
- \item |min|: The attribute is set to the minimal value that the
- attribute has attained along this axis.
- \item |max|: Like |min|.
- \item |padded min|: This will also set the \meta{attribute}
- monitored by the axis to the same value as |min|.
- Additionally, however, the subkey
- |/data point/|\meta{attribute}|/offset| is set to the current
- padding for the minimum, see the description of |padding min|
- later on. The effect of this is that the actual point ``meant''
- by the attribute is offset by this padding along the
- attribute's axis.
- \item |padded max|: Like |padded min|.
- \end{itemize}
- \end{key}
-
- The |right axis| would be visualized the same way, only at |goto=max|. The
- $x$-axis actually needs to be visualized \emph{twice}: Once at the bottom
- and once at the top. Thus, we need to call |visualize axis| twice for this
- axis:
- %
-\tikzdatavisualizationset{
- our system/.style={
- new Cartesian axis=x axis,
- new Cartesian axis=left axis,
- new Cartesian axis=right axis,
- x axis={attribute=x},
- left axis={unit vector={(0cm,1pt)}},
- right axis={unit vector={(0cm,1pt)}},
- x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
- left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
- right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
- }
-}
-\begin{codeexample}[
- preamble={\usetikzlibrary{datavisualization}},
- pre={\tikzdatavisualizationset{
- our system/.style={
- new Cartesian axis=x axis,
- new Cartesian axis=left axis,
- new Cartesian axis=right axis,
- x axis={attribute=x},
- left axis={unit vector={(0cm,1pt)}},
- right axis={unit vector={(0cm,1pt)}},
- x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
- left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
- right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
- }
-}}]
-\tikzset{
- data visualization/our system/.append style={
- left axis= {visualize axis={x axis= {goto=min}}},
- right axis={visualize axis={x axis= {goto=max}}},
- x axis= {visualize axis={left axis={goto=min}},
- visualize axis={left axis={goto=max}}},
- }
-}
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, length=4cm},
- left axis ={attribute=money},
- right axis={attribute=people},
- visualize as line/.list={people 1, people 2, money 1, money 2}]
- data group {people and money};
-\end{codeexample}
-
- There is another key that is similar to |goto|, but has a slightly
- different semantics:
- %
- \begin{key}{/tikz/data visualization/axis options/goto pos=\meta{fraction}}
- The key works like |goto|, only the \meta{fraction} is not interpreted
- as a value but as a fraction of the way between the minimum and the
- maximum value for this axis.
-
- Suppose that for an axis the attribute range interval is $[500,1000]$
- and the reasonable interval is $[1,3]$. Then for a \meta{fraction} of
- |0|, the mapping process would choose value $1$ from the reasonable
- interval, for a \meta{fraction} of |1| the position $3$ from the
- reasonable interval, and for a \meta{fraction} or |0.25| the position
- $1.5$ since it is one quarter at the distance from $1$ to $3$.
-
- Note that neither the attribute range interval nor the transformation
- function for the attribute are important for the |goto pos| option --
- the \meta{fraction} is computed with respect to the reasonable
- interval. Also note that the values of the actual attribute
- corresponding to the fractional positions in the reasonable interval
- are not computed.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{datavisualization}},
- pre={\tikzdatavisualizationset{
- our system/.style={
- new Cartesian axis=x axis,
- new Cartesian axis=left axis,
- new Cartesian axis=right axis,
- x axis={attribute=x},
- left axis={unit vector={(0cm,1pt)}},
- right axis={unit vector={(0cm,1pt)}},
- x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
- left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
- right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
- }
-}}]
-\tikzset{
- data visualization/our system/.append style={
- x axis= {visualize axis={left axis={goto pos=0.25}},
- visualize axis={left axis={goto pos=0.5}}},
- }
-}
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, length=4cm},
- left axis ={attribute=money},
- right axis={attribute=people},
- visualize as line/.list={people 1, people 2, money 1, money 2}]
- data group {people and money};
-\end{codeexample}
- \end{key}
-
- By default, when an axis is visualized, it spans the set of all possible
- values for the monitored attribute, that is, from |min| to |max|. However,
- there are actually two keys that allow you to adjust this:
- %
- \begin{key}{/tikz/data visualization/low=\meta{value}}
- This is the attribute value where the axis visualization starts. The
- same special values as for |goto| are permissible (like |min| or
- |padded min|, but also |0| or |1|).
- \end{key}
- %
- \begin{key}{/tikz/data visualization/high=\meta{value}}
- Like |low|, only for where the axis ends.
- \end{key}
-
- By default, |low=min| and |high=max| are set for an axis visualization.
- Another sensible setting is |low=padded min| and |high=padded max|. The
- following key provides a shorthand for this:
- %
- \begin{key}{/tikz/data visualization/padded}
- Shorthand for |low=padded min, high=padded max|.
- \end{key}
- %
- As an example, consider the |scientific axes=clean|. Here, each axis is
- actually drawn three times: Once at the minimum, once at the maximum and
- then once more at the padded minimum.
-
-
- \medskip
- \textbf{The axis line.}
- When an axis is drawn, \tikzname\ does not simply draw a straight line from
- the |low| position to the |high| position. In reality, the data
- visualization system uses the two commands |\pgfpathdvmoveto| and
- |\pgfpathdvlineto| internally. These will replace the straight line by a
- curve in certain situations. For instance, in a polar coordinate system, if
- an axis should be drawn along an angle axis for a fixed radius, an arc will
- be used instead of a straight line.
-
-
- \medskip
- \textbf{Styling the axis.}
- As can be seen, we now get the axis we want (but without the ticks,
- visualizing them will be explained later). The axis is, however, simply a
- black line. We can \emph{style} the axis in a manner similar to styling
- ticks and grid lines, see Section~\ref{section-dv-style}. In detail, the
- following styles get executed:
- %
- \begin{enumerate}
- \item |axis layer|
- \item |every axis|
- \item |styling|
- \end{enumerate}
- %
- Additionally, even before |every axis| is executed, |low=min| and
- |high=max| are executed.
-
- \begin{stylekey}{/tikz/data visualization/axis layer (initially on background layer)}
- The layer on which the axis is drawn. See the description of
- |grid layer| on page~\pageref{section-dv-grid-layer} for details.
- \end{stylekey}
-
- \begin{stylekey}{/tikz/data visualization/every axis}
- Put styling of the axis here. It is usually a good idea to set this
- style to |style={black!50}|.
- \end{stylekey}
-
- Recall that the |styling| key is set using the |style| key, see
- Section~\ref{section-dv-style}.
- %
-% TODOsp: codeexamples: What is this empty `\tikzset` good for?
-\tikzset{
-}
-\begin{codeexample}[
- preamble={\usetikzlibrary{datavisualization}},
- pre={\tikzdatavisualizationset{
- our system/.style={
- new Cartesian axis=x axis,
- new Cartesian axis=left axis,
- new Cartesian axis=right axis,
- x axis={attribute=x},
- left axis={unit vector={(0cm,1pt)}},
- right axis={unit vector={(0cm,1pt)}},
- x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
- left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
- right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
- }
-}}]
-\tikzset{
- data visualization/our system/.append style={
- every axis/.style={style=black!50}, % make this the default
- left axis= {visualize axis={x axis= {goto=min}, style=red!75}},
- right axis={visualize axis={x axis= {goto=max}, style=blue!75}},
- x axis= {visualize axis={left axis={goto=min}},
- visualize axis={left axis={goto=max}}},
- }
-}
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, length=4cm},
- left axis ={attribute=money},
- right axis={attribute=people},
- visualize as line/.list={people 1, people 2, money 1, money 2}]
- data group {people and money};
-\end{codeexample}
-\tikzset{
- data visualization/our system/.append style={
- every axis/.style={style=black!50}, % make this the default
- left axis= {visualize axis={x axis= {goto=min}, style=red!75}},
- right axis={visualize axis={x axis= {goto=max}, style=blue!75}},
- x axis= {visualize axis={left axis={goto=min}},
- visualize axis={left axis={goto=max}}},
- }
-}
-
-
- \medskip
- \textbf{Padding the Axis.}
- When an axis is visualized, it is often a good idea to make it ``a little
- bit longer'' or to ``remove it a bit from the border'', because the
- visualization of an axis should not interfere with the actual data. For
- this reason, a \emph{padding} can be specified for axes:
-
- \begin{key}{/tikz/data visualization/axis options/padding min=\meta{dimension}}
- This is the dimension that is used whenever |goto=padded min| is used.
- The \meta{dimension} is then put into the |offset| subkey of the
- attribute monitored by the axis. When a data point is transformed by a
- linear transformer and when this subkey is nonzero, this offset is
- added. (For an angle axis of a polar transformer, the \meta{dimension}
- is interpreted as an additional angle rather than as an additional
- distance). Note that \meta{dimension} should typically be negative
- since ``adding the \meta{dimension}'' will then make the axis longer
- (because it starts at a smaller value). The standard axis systems set
- the padding to some default and take its value into account:
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\begin{tikzpicture}
- \datavisualization [scientific axes=clean,
- x axis={padding min=-1cm},
- visualize as smooth line]
- data [format=function] {
- var x : interval [-3:5];
- func y = \value x * \value x;
- };
-\end{tikzpicture}
-\end{codeexample}
-
- Using padded and using the |padded| key, we can visualize our axis ``a
- little removed from the actual data'':
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{datavisualization}},
- pre={\tikzdatavisualizationset{
- our system/.style={
- new Cartesian axis=x axis,
- new Cartesian axis=left axis,
- new Cartesian axis=right axis,
- x axis={attribute=x},
- left axis={unit vector={(0cm,1pt)}},
- right axis={unit vector={(0cm,1pt)}},
- x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
- left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
- right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}}
- }
-}%
-\tikzset{
- data visualization/our system/.append style={
- every axis/.style={style=black!50}, % make this the default
- left axis= {visualize axis={x axis= {goto=min}, style=red!75}},
- right axis={visualize axis={x axis= {goto=max}, style=blue!75}},
- x axis= {visualize axis={left axis={goto=min}},
- visualize axis={left axis={goto=max}}},
- }
-}}]
-\tikzset{
- data visualization/our system/.append style={
- all axes= {padding=.5em},
- left axis= {visualize axis={x axis= {goto=padded min}, padded}},
- right axis={visualize axis={x axis= {goto=padded max}, padded}},
- x axis= {visualize axis={left axis={goto=padded min}, padded},
- visualize axis={left axis={goto=padded max}, padded}},
- }
-}
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, length=3cm},
- left axis ={attribute=money},
- right axis={attribute=people},
- visualize as line/.list={people 1, people 2, money 1, money 2}]
- data group {people and money};
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/data visualization/axis options/padding max=\meta{dimension}}
- Works like |padding min|, but \meta{dimension} should typically be
- positive.
- \end{key}
-
- \begin{key}{/tikz/data visualization/axis options/padding=\meta{dimension}}
- Sets both |padding min| to the negated value of \meta{dimension} and
- |padding max| to \meta{dimension}.
- \end{key}
-\end{key}
-
-
-\subsubsection{Visualizing Grid Lines}
-\label{section-dv-visualize-gridlines}
-
-As explained earlier, the |grid| key is used to specify at which positions grid
-lines should be drawn in principle. However, this key does not actually cause
-any grid lines to be drawn. Instead, the |visualize grid| key is used by the
-axis system to specify how grid lines are drawn.
-
-\begin{key}{/tikz/data visualization/axis options/visualize grid=\meta{options}}
- This key is passed to an axis. It causes grid lines to be drawn at the
- positions specified by the |grid| key for this axis. The \meta{options}
- govern where and how the grid lines will be drawn.
-
-
- \medskip
- \textbf{The direction axis.}
- At first sight, one might expect that the grid lines for an axis should
- simply be drawn perpendicular to the axis between the minimum and maximum
- value of the axis. However, things are somewhat more difficult in reality:
- %
- \begin{enumerate}
- \item A grid line is supposed to indicate all positions where a certain
- attribute attains a fixed value. But, then, a grid line does not
- really need to be a grid \emph{line}. Consider for instance a three
- dimensional axis system. A ``grid line'' for the $x$-coordinate |3|
- would actually be a ``grid plane''.
- \item For a polar coordinate system and a fixed radius, this set of
- positions at a certain radius is not a straight line, but an arc.
- For more complicated coordinate systems such as the one arising
- from three-dimensional spherical projections, a grid line may well
- be a fairly involved curve.
- \end{enumerate}
- %
- The |visualize grid| command addresses these complications as follows:
- %
- \begin{enumerate}
- \item A grid line is always a line, not a plane or a volume. This means
- that in the example of a three dimensional axis system and the
- $x$-attribute being |3|, one would have to choose whether the grid
- line should go ``along'' the $y$-axis or ``along'' the $z$-axis for
- this position. One can, however, call the |visualize grid| command
- twice, once for each direction, to cause grid lines to be shown for
- both directions.
- \item A grid line is created by moving to a start position and then
- doing a lineto to the target position. However, the ``moveto'' and
- ``lineto'' are done by calling special commands of the data
- visualization system. These special commands allow coordinate
- system to ``notice'' that the line is along an axis and will allow
- them to replace the straight line by an appropriate curve. The
- polar axes systems employ this strategy, for instance.
- \end{enumerate}
-
- By the above discussion, in order to create a grid line for attribute $a$
- having value $v$, we need to specify an axis ``along'' which the line
- should be drawn. When there are only two axes, this is usually ``the other
- axis''. This ``other axis'' is specified using the following key:
- %
- \begin{key}{/tikz/data visualization/direction axis=\meta{axis name}}
- You must pass this key as an \meta{option} each time you use
- |visualize axis|. When the grid line is drawn, the attribute $a$ is set
- to $v$ and the axis \meta{axis name}'s attribute is set once to the
- current value of |low| and once to |high|. Then a line is drawn between
- these two positions using |\pgfpathdvlineto|.
- \end{key}
- %
- The |low| and |high| keys are the same as the ones used in the
- |visualize axis| key.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- xyz Cartesian cabinet,
- all axes={visualize axis={low=0, style=->}},
- x axis={visualize grid={direction axis=y axis}, grid=many},
- visualize as scatter]
- data {
- x, y, z
- 0, 0, 1
- 0, 1, 0
- 2, 2, 2
- };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- xyz Cartesian cabinet,
- all axes={visualize axis={low=0, style=->}, grid=many},
- x axis={visualize grid={direction axis=z axis}},
- z axis={visualize grid={direction axis=x axis},
- visualize grid={direction axis=y axis},},
- visualize as scatter]
- data {
- x, y, z
- 0, 0, 1
- 0, 1, 0
- 2, 2, 2
- };
-\end{codeexample}
-
-
- \medskip
- \textbf{Styling the grid lines.}
- When a grid line is draw, styles are applied as described in
- Section~\ref{section-dv-styling-grid-lines}.
-
-
- \medskip
- \textbf{The major, minor, and subminor grid lines.}
- The |grid| option allows you to specify for each kind of grid line (major,
- minor, or subminor) a set of different values for which these grid lines
- should be drawn. Correspondingly, it is also possible to configure for each
- kind of grid line how it should be drawn. For this, the |major|, |minor|,
- |subminor|, and also the |common| keys can be used inside the
- \meta{options} of |visualize grid|. While as option to |grid| these keys
- are used to specify |at| values, as options of |visualize grid| they are
- used to configure the different kinds of grid lines.
-
- Most of the time, no special configuration is necessary since all styling
- is best done by configuring keys like |every major grid|. You need to use a
- key like |major| only if you wish to configure for instance the |low| or
- |high| values of a |major| grid line differently from those of |minor| grid
- lines -- are rather unlikely setting -- or when the styling should deviate
- from the usual settings.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- xy Cartesian,
- all axes={visualize axis={low=0, style=->},
- grid={some, minor steps between steps}},
- x axis= {visualize grid={
- direction axis=y axis,
- minor={low=0.25, high=1.75, style=red!50}}},
- visualize as scatter]
- data {
- x, y
- 0, 0
- 3, 3
- };
-\end{codeexample}
- %
-\end{key}
-
-Returning to the example of |our system| with the two axis systems, it is
-straight-forward to configure the grid lines of the $x$-axis: The direction
-axis is either of the other two axis (they point in the same direction and they
-have the same range). For the other two axes, we visualize one grid
-independently of the other, using different colors.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikzset{
- data visualization/our system/.append style={
- x axis= {visualize grid={direction axis=left axis}},
- left axis= {visualize grid={direction axis=x axis,
- common={style=red!50}}},
- right axis={visualize grid={direction axis=x axis,
- common={style=blue!50}}},
- }
-}
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, length=3cm, grid=many},
- left axis ={attribute=money, grid=some},
- right axis={attribute=people, grid=few},
- visualize as line/.list={people 1, people 2, money 1, money 2}]
- data group {people and money};
-\end{codeexample}
-
-
-\subsubsection{Visualizing the Ticks and Tick Labels}
-\label{section-dv-visualize-ticks}
-
-\begin{key}{/tikz/data visualization/axis options/visualize ticks=\meta{options}}
- Visualizing a tick involves (possibly) drawing a tick mark and adding
- (possibly) the tick node. The process is similar to |visualize grid|: Users
- use the |ticks| key to configure how many ticks they would like for an axis
- and at which positions. The axis system uses the |visualize ticks| key to
- specify where these ticks should actually be shown.
-
- Unlike grid lines, which are typically only visualized once for each
- combination of an axis and a direction axis, tick marks might be visualized
- at different places for the same axis. Consider for instance the
- |scientific axes|:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes, all axes={length=3cm},
- x axis={ticks={stack}},
- visualize as smooth line]
- data [format=function] {
- var x : interval [0:2];
- func y = \value x*\value x;
- };
-\end{codeexample}
- %
- Have a look at the ticks on the $y$-axis: There are ticks at values |0|,
- |1|, |2|, |3|, and~|4|. These are visualized both at the left side (where
- the tick nodes are also shown) and additionally also at the right side, but
- only as small marks. Similarly, the ticks on the $x$-axis appear at the
- bottom, but also (in much simpler versions) at the top. Both for the
- $x$-axis and for the $y$-axis the |visualize ticks| key was called twice.
-
-
- \medskip
- \textbf{The tick marks.}
- Drawing a tick mark is quite similar to visualizing a grid line; indeed a
- tick mark can be thought of as a ``mini grid line'': Just like a grid line
- it ``points a long an axis''. However, a tick will always be a short
- straight line -- even when the coordinate system is actually twisted
- (experimentation has shown that ticks that follow the curvature of the
- coordinate system like grid lines are hard to recognize). For this reason,
- the |low| and |high| keys have a different meaning from the one used with
- the |visualize grid| key. In detail to configure the size and position of a
- tick mark for the value $v$ of attribute $a$, proceed as follows:
- %
- \begin{itemize}
- \item The |visualize ticks| key will have setup attribute $a$ to be
- equal to $v$.
- \item You should now use the |goto| or |goto pos| key together with all
- \emph{other} axes to configure at which position with respect to
- these other options the tick mark should be shown. For instance,
- suppose we want tick marks in |our system| for the $x$-axis at the
- bottom and at the top. This corresponds to once setting the
- |left axis| to its minimal value and once to its maximal value:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikzset{
- data visualization/our system/.append style={
- x axis={visualize ticks={direction axis=left axis, left axis={goto=min}},
- visualize ticks={direction axis=left axis, left axis={goto=max}},
- }
- }
-}
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, length=3cm, ticks=many},
- left axis ={attribute=money},
- right axis={attribute=people},
- visualize as line/.list={people 1, people 2, money 1, money 2}]
- data group {people and money};
-\end{codeexample}
- %
- \item In the above example, we may wish to shorten the ticks a bit at
- the bottom and at the top. For this, we use the |low| and |high|
- key:
- %
- \begin{key}{/tikz/data visualization/low=\meta{dimension}}
- When used with the |visualize ticks| option, the |low| key
- contains a dimension that specifies the extend of the tick
- going ``toward the minimum'' of the direction axis. More
- precisely, when a tick mark is visualized, a unit tangent
- vector at the current data point in the direction of the
- |direction axis| is computed and this vector is multiplied by
- \meta{dimension} to compute the start position of the tick
- line. The end position is given by this vector times the |high|
- value.
-
- Note that the \meta{dimension} should usually be negative for
- the |low| key and positive for the |high| key.
-
- For tick marks where a tick label node is shown, the
- \meta{dimension} is increased by the current values of keys
- like |tick text even low padding|, see
- Section~\ref{section-dv-stacking} for details.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/high=\meta{dimension}}
- Like |low|.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/tick length=\meta{dimension}}
- Shorthand for |low=-|\meta{dimension}|, high=|\meta{dimension}.
- \end{key}
-
- What we want to happen is that in the upper visualization of the
- ticks the |low| value is |0pt|, while in the lower one the |high|
- value is |0pt|:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikzset{
- data visualization/our system/.append style={
- x axis={
- visualize ticks={direction axis=left axis,high=0pt,left axis={goto=min}},
- visualize ticks={direction axis=left axis,low=0pt,left axis={goto=max}},
- }
- }
-}
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, length=3cm, ticks=many},
- left axis ={attribute=money},
- right axis={attribute=people},
- visualize as line/.list={people 1, people 2, money 1, money 2}]
- data group {people and money};
-\end{codeexample}
- %
- \end{itemize}
- %
- In order to style the tick mark, use the styling mechanism that is detailed
- in Section~\ref{section-dv-styling-ticks}.
-
-
- \medskip
- \textbf{The tick label node.}
- At certain tick positions, we may wish to add a node indicating the value
- of the attribute at the given position. The |visualize ticks| command has
- no influence over which text should be shown at a node -- the text is
- specified and typeset as explained in Section~\ref{section-dv-tick-labels}.
-
- Each time |visualize ticks|, for each tick position up to two tick label
- nodes will be created: One at the |low| position and one at the |high|
- position. The following keys are used to configure which of these cases
- happen:
- %
- \begin{key}{/tikz/data visualization/tick text at low=\opt{\meta{true or false}} (default true)}
- Pass this option to |visualize ticks| when you want tick label nodes to
- be placed at the |low| position of each tick mark.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikzset{
- data visualization/our system/.append style={
- x axis={
- visualize ticks={direction axis=left axis, left axis={goto=min},
- high=0pt, tick text at low, stack},
- visualize ticks={direction axis=left axis, left axis={goto=max},
- low=0pt, tick text at high, stack}
- }
- }
-}
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, length=3cm, ticks=some},
- left axis ={attribute=money},
- right axis={attribute=people},
- visualize as line/.list={people 1, people 2, money 1, money 2}]
- data group {people and money};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/data visualization/tick text at high=\opt{\meta{true or false}} (default true)}
- Like |tick text at low|.
- \end{key}
-
- \begin{key}{/tikz/data visualization/no tick text}
- Shorthand for |tick text at low=false, tick text at high=false|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes, all axes={length=3cm},
- x axis={ticks={
- major also at={6.5 as [no tick text]}}},
- visualize as smooth line]
- data [format=function] {
- var x : interval [5:10];
- func y = \value x * \value x;
- };
-\end{codeexample}
- \end{key}
-
- When a tick label node is to be placed at the low or the high position, the
- next step is to determine the exact position and the correct anchor of the
- node. This is done as follows:
- %
- \begin{itemize}
- \item In order to compute an appropriate |anchor|, the tick mark is
- considered: This is a short line pointing in a certain direction.
- For a tick label node at the |low| position, the |anchor| attribute
- is setup in such a way that the node label will be below the |low|
- position when the tick mark direction points up, it will be to the
- right when the direction points left, above when it points down,
- and so on also for diagonal directions. Similarly, for the |high|
- position, when the direction points up, the node will be placed
- above the tick mark and so on.
-
- This computation is done automatically.
- \item The tick label node is styled. The styles that are applied are
- described in Section~\ref{section-dv-styling-ticks}.
- \item A tick label node for the |low| position is usually anchored at
- this |low| position, but an additional padding will be added as
- described in Section~\ref{section-dv-stacking}.
- \end{itemize}
-\end{key}
-
-
-\subsubsection{Visualizing the Axis Labels}
-\label{section-dv-visualize-label}
-
-The |label| option can be used with an axis to specify a text should be shown
-next to the axis to indicates which attribute this axis refers to. Like |ticks|
-or |grid|, the |label| option does not actually draw the label, this is the job
-of the |visualize label| key, which is configured by the axis system.
-
-\begin{key}{/tikz/data visualization/axis options/visualize label=\meta{options}}
- The \meta{options} should be used to configure a ``good place'' for the
- axis label. Usually, you will use the |goto| or the |goto pos| key.
-
- For the example of |our system|, we would like the label of the |x axis| to
- be placed below at the middle of the axis, so we use |goto pos=.5| to
- determine this position. Concerning the other axes, we want it to be placed
- at the minimum position of the |left axis| with a lot of padding.
- %
-\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikzdatavisualizationset{
- our system/.append style={
- x axis={visualize label={
- x axis={goto pos=.5},
- left axis={padding=1.5em, goto=padded min}}}
- }
-}
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, ticks=some, label},
- left axis ={attribute=money},
- right axis={attribute=people},
- visualize as line/.list={
- people 1, people 2, money 1, money 2}]
- data group {people and money};
-\end{codeexample}
-
- In the above example, the |padding| of |1.5em| was rather arbitrary and
- ``suboptimal''. It would be outright wrong if the labels on the |x axis|
- were larger or if they were missing. It would be better if the vertical
- position of the |x axis| label were always ``below'' all other options. For
- such cases a slightly strange approach is useful: You position the node
- using |node style={at=...}| where |at| is now the normal \tikzname\ option
- that is used to specify the position of a node. Inside the |...|, you
- specify that the horizontal position should be the bottom of
- up-to-now-constructed data visualization and the vertical position should
- be at the ``origin'', which is, however, the position computed by the
- |goto| keys for the axes:
- %
-\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikzdatavisualizationset{
- our system/.append style={
- x axis={visualize label={
- x axis={goto pos=.5},
- node style={
- at={(0,0 |- data visualization bounding box.south)},
- below
-} } } } }
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, ticks=some, label=Year},
- left axis ={attribute=money},
- right axis={attribute=people},
- visualize as line/.list={
- people 1, people 2, money 1, money 2}]
- data group {people and money};
-\end{codeexample}
-
- Two additional keys are useful for positioning axis labels:
- %
- \begin{key}{/tikz/data visualization/axis option/anchor at min}
- When passed to an axis, this key sets the |anchor| so that a node
- positioned at either the |min| or the |padded min| value of the axis
- will be placed ``nicely'' with respect to the axis. For instance, if
- the axis points upwards from the |min| value to the |max| value, the
- |anchor| would be set to |north| since this gives a label below the
- axis's start. Similarly, if the axis points right, the anchor would be
- set to |east|, and so on.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/axis option/anchor at max}
- Like |anchor at min|.
- \end{key}
-\end{key}
-
-
-\subsubsection{The Complete Axis System}
-
-Here is the code for the complete axis system developed above and an example of
-how it is used:
-%
-\begin{codeexample}[code only]
-\tikzdatavisualizationset{ our system/.style={
- % The axes
- new Cartesian axis=x axis, new Cartesian axis=left axis, new Cartesian axis=right axis,
- % The directions of the axes
- all axes={padding=.5em}, left axis={unit vector={(0cm,1pt)}}, right axis={unit vector={(0cm,1pt)}},
- % The default attributes, other attributes must be configured
- x axis={attribute=x},
- % The lengths of the axes
- x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
- left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
- right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
- % The styling of the axes
- every axis/.style={style=black!50}, % make this the default
- % Visualizing the axes themselves
- left axis= {visualize axis={x axis= {goto=padded min}, style=red!75, padded}},
- right axis={visualize axis={x axis= {goto=padded max}, style=blue!75,padded}},
- x axis= {visualize axis={left axis={goto=padded min}, padded},
- visualize axis={left axis={goto=padded max}, padded}},
- % Visualizing the grid, when requested
- x axis= {visualize grid={direction axis=left axis}},
- left axis= {visualize grid={direction axis=x axis, common={style=red!50}}},
- right axis={visualize grid={direction axis=x axis, common={style=blue!50}}},
- % Visualizing the ticks, when requested
- left axis={visualize ticks={style={red!50!black}, direction axis=x axis,
- x axis={goto=padded min}, high=0pt, tick text at low}},
- right axis={visualize ticks={style={blue!80!black}, direction axis=x axis,
- x axis={goto=padded max}, low=0pt, tick text at high}},
- x axis={visualize ticks={direction axis=left axis, left axis={goto=padded min}, high=0pt,
- tick text at low},
- visualize ticks={direction axis=left axis, left axis={goto=padded max}, low=0pt}},
- % By default, there are ticks on all axes
- all axes={ticks},
- % Visualizing the axis labels, when requested
- x axis={visualize label={x axis={goto pos=.5}, node style={
- at={(0,0 |- data visualization bounding box.south)}, below}}},
- left axis={visualize label={left axis={goto pos=.5}, node style={
- at={(0,0 -| data visualization bounding box.west)}, rotate=90, anchor=south, red!50!black}}},
- right axis={visualize label={right axis={goto pos=.5}, node style={
- at={(0,0 -| data visualization bounding box.east)}, rotate=-90, anchor=south, blue!80!black}}},
-}}
-\end{codeexample}
-
-\begin{codeexample}[
- preamble={\usetikzlibrary{datavisualization}},
- pre={\tikzdatavisualizationset{
- our system/.style={
- % The axes
- new Cartesian axis=x axis,
- new Cartesian axis=left axis,
- new Cartesian axis=right axis,
- % The default attributes, other attributes must be configured
- x axis={attribute=x},
- % The directions of the axes
- all axes={padding=.5em},
- left axis={unit vector={(0cm,1pt)}},
- right axis={unit vector={(0cm,1pt)}},
- % The lengths of the axes
- x axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/width}},
- left axis ={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
- right axis={length=\pgfkeysvalueof{/tikz/data visualization/scientific axes/height}},
- % The styling of the axes
- every axis/.style={style=black!50}, % make this the default
- % Visualizing the axes themselves
- left axis= {visualize axis={x axis= {goto=padded min}, style=red!75, padded}},
- right axis={visualize axis={x axis= {goto=padded max}, style=blue!75,padded}},
- x axis= {visualize axis={left axis={goto=padded min}, padded},
- visualize axis={left axis={goto=padded max}, padded}},
- % Visualizing the grid, when requested
- x axis= {visualize grid={direction axis=left axis, padded}},
- left axis= {visualize grid={direction axis=x axis, padded, common={style=red!50}}},
- right axis={visualize grid={direction axis=x axis, padded, common={style=blue!50}}},
- % Visualizing the ticks, when requested
- left axis={
- visualize ticks={style={red!50!black}, direction axis=x axis, x axis={goto=padded min}, high=0pt, tick text at low}},
- right axis={
- visualize ticks={style={blue!80!black}, direction axis=x axis, x axis={goto=padded max}, low=0pt, tick text at high}},
- x axis={
- visualize ticks={direction axis=left axis, left axis={goto=padded min}, high=0pt, tick text at low},
- visualize ticks={direction axis=left axis, left axis={goto=padded max}, low=0pt}
- },
- % By default, there are ticks on all axes
- all axes={ticks},
- % Visualizing the axis labels, when requested
- x axis={visualize label={
- x axis={goto pos=.5}, node style={at={(0,0 |- data visualization bounding box.south)}, below}}},
- left axis={visualize label={
- left axis={goto pos=.5}, node style={
- at={(0,0 -| data visualization bounding box.west)}, rotate=90, anchor=south, red!50!black}}},
- right axis={visualize label={
- right axis={goto pos=.5}, node style={
- at={(0,0 -| data visualization bounding box.east)}, rotate=-90, anchor=south, blue!80!black}}},
- }
-}}]
-\tikz \datavisualization [
- our system,
- x axis={attribute=time, label=Year,
- ticks={tick text padding=2pt, style={/pgf/number format/set thousands separator=}}},
- left axis={attribute=money, label=Spending,
- padding min=0, include value=0, grid,
- ticks={tick prefix=\$, style={/pgf/number format/fixed,
- /pgf/number format/fixed zerofill, /pgf/number format/precision=2}}},
- right axis={attribute=people,
- label=Population,
- padding min=0, include value=0,
- ticks={style=/pgf/number format/fixed}},
- visualize as line/.list={
- people 1, people 2, money 1, money 2},
- people 1={style={visualizer color=blue}},
- people 2={style={visualizer color=blue!50}},
- money 1={style={visualizer color=red}},
- money 2={style={visualizer color=red!50}} ]
-data group {people and money};
-\end{codeexample}
-
-
-\subsubsection{Using the New Axis System Key}
-
-The axis system |our system| that we developed in the course of the previous
-section is not yet ``configurable''. The only configuration that was possible
-was to ``misuse'' the |width| and |height| keys of the |scientific axes|.
-
-In order to make |our system| configurable so that we can say
-|our system=|\meta{options}, where \meta{options} are executed with the path
-prefix
-%
-\begin{codeexample}[code only]
-/tikz/data visualization/our system
-\end{codeexample}
-%
-we can use the following key:
-
-\begin{key}{/tikz/data visualization/new axis system=\marg{axis system
- name}\marg{axis setup}\marg{default options}\\ \marg{application
- options}%
-}
- The |new axis system| key takes four parameters. The first one,
- \meta{system name}, is the name of the to-be-created axis system,
- |our system| in our case. The |new axis system| will create the following
- new key:
- %
- \begin{key}{/tikz/data visualization/\meta{axis system name}=\opt{\meta{options}}}
- When the key \meta{axis system name} is used, the following keys will be
- executed in the following order:
- %
- \begin{enumerate}
- \item The \meta{axis setup} with the path prefix
- |/tikz/data visualization/|.
- \item The \meta{default options} with the same path prefix.
- \item The following style:
- %
- \begin{stylekey}{/tikz/data visualization/every \meta{axis system name}}
- Even though this style has the path prefix
- |/tikz/data visualization| itself, the keys stored in this
- style will be executed with the path prefix
- |/tikz/data visualization/|\meta{axis system name}.
- \end{stylekey}
- \item The \meta{options} with the path prefix
- |/tikz/data visualization/|\meta{axis system name}.
- \item The \meta{application options} with the path prefix
- |/tikz/data visualization/|
- \end{enumerate}
- \end{key}
-
- Let us now have a look at what all of this means. First, the \meta{axis
- setup} will contain all options that setup the axis system in all ways that
- need not be configured. For instance, the \meta{axis setup} for the
- |scientific axes| will create an |x axis| and also a |y axis| (because
- these are always present), but will not setup the label visualization
- (because this can be configured in different ways). For |our system|, which
- cannot be configured at all, we would place all of our configuration in the
- \meta{axis setup}.
-
- The \meta{default options} can be used to pick default values that would
- usually be passed to the \meta{options} of the newly created axis system.
- For instance, for |scientific axis|, the \meta{default options} are set to
- |outer ticks,standard labels|, because these are the defaults.
-
- Finally, the \meta{application options} can be used to actually apply the
- configuration that has been chosen by the \meta{options}. The idea is that
- \meta{default options}, \meta{options}, and also |every| \meta{axis system
- name} all have a chance of changing, re-changing and re-setting all sorts
- of styles and keys. Then, with the last change ``winning'', the resulting
- setting of a style can be executed, which may then cause a label
- visualization to be installed.
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-backend.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-backend.tex
deleted file mode 100644
index baf60247e2..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-backend.tex
+++ /dev/null
@@ -1,34 +0,0 @@
-% Copyright 2018 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{The Data Visualization Backend}
-\label{section-dv-backend}
-
-\subsection{Overview}
-
-The present section explains the mechanisms behind the data visualization
-engine.
-
-Until it is documented properly, we will have to make do with the documentation
-in the source code.
-
-
-\subsection{The Rendering Pipeline}
-
-To be written...
-
-\subsection{Usage}
-
-To be written...
-
-\subsection{The Mathematical Micro-Kernel}
-\label{section-dv-math-kernel}
-
-To be written...
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-examples.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-examples.tex
deleted file mode 100644
index 75271694ca..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-examples.tex
+++ /dev/null
@@ -1,95 +0,0 @@
-% 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.
-
-
-A first example:
-
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}[baseline]
- \datavisualization [
- school book axes,
- visualize as smooth line,
- clean ticks,
- all axes={grid={step=1,minor steps between steps=1}},
- x axis={
- ticks={
- major={
- also at={(0.5*pi) as $\pi/2$},
- also at={(pi) as $\pi$},
- options at=3 as [no tick text]
- }
- },
- label=$x$
- },
- y axis={
- label=$y$,
- }
- ]
- data [format=function] {
- var x : interval [-0.5*pi:4] samples 50;
- func y = sin(\value x r);
- };
-\end{tikzpicture}
-\end{codeexample}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}[baseline]
- \datavisualization [
- scientific axes=clean,
- visualize as line,
- all axes={padding=4pt},
- x axis={logarithmic,
- ticks={many, tick unit={ms},
- node style={rotate=45,anchor=north east}},
- label={time},
- grid},
- y axis={label={distance}},
- ]
- data {
- x, y, z
- 0.001, 0, 0
- 2000, 2.23, 2
- 20670, 1, 3
- 501, -2, 0
- };
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\begin{tikzpicture}[baseline,mark=*]
- \datavisualization [
- scientific axes=inner ticks,
- all axes={padding=4pt},
- euro about strategy,
- visualize as scatter,
- x axis={attribute=x2},
- y axis={attribute=y2}
- ]
- data [separator=\space] {
-x y x1 y1 x2 y2 x3 y3
-10.0 8.04 10.0 9.14 10.0 7.46 8.0 6.58
-8.0 6.95 8.0 8.14 8.0 6.77 8.0 5.76
-13.0 7.58 13.0 8.74 13.0 12.74 8.0 7.71
-9.0 8.81 9.0 8.77 9.0 7.11 8.0 8.84
-11.0 8.33 11.0 9.26 11.0 7.81 8.0 8.47
-14.0 9.96 14.0 8.10 14.0 8.84 8.0 7.04
-6.0 7.24 6.0 6.13 6.0 6.08 8.0 5.25
-4.0 4.26 4.0 3.10 4.0 5.39 19.0 12.50
-12.0 10.84 12.0 9.13 12.0 8.15 8.0 5.56
-7.0 4.82 7.0 7.26 7.0 6.42 8.0 7.91
-5.0 5.68 5.0 4.74 5.0 5.73 8.0 6.89
- };
-\end{tikzpicture}
-\end{codeexample}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-formats.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-formats.tex
deleted file mode 100644
index 69468800d0..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-formats.tex
+++ /dev/null
@@ -1,645 +0,0 @@
-% 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{Providing Data for a Data Visualization}
-\label{section-dv-formats}
-
-\subsection{Overview}
-
-The data visualization system needs a stream of data points as input. These
-data points can be directly generated by repeatedly calling the |\pgfdatapoint|
-command, but usually data is available in some special (text) format and one
-would like to visualize this data. The present section explains how data in
-some specific format can be fed to the data visualization system.
-
-This section starts with an explanation of the main concepts. Then, the
-standard formats are listed in the reference section. It is also possible to
-define new formats, but this an advanced concept which requires an
-understanding of some of the internals of the parsing mechanism, explained in
-Section~\ref{section-dv-parsing}, and the usage of a rather low-level command,
-explained in Section~\ref{section-dv-declaring-formats}.
-
-
-\subsection{Concepts}
-
-For the purposes of this section, let call a \emph{data format} some
-standardized way of writing down a list of data points. A simple example of a
-data format is the \textsc{csv} format (the acronym stands for \emph{comma
-separated values}), where each line contains a data point, specified by values
-separated by commas. A different format is the \emph{key--value format}, where
-data points are specified by lists of key--value pairs. A far more complex
-format is the \textsc{pdb}-format used by the protein database to describe
-molecules.
-
-The data visualization system does not use any specific format. Instead,
-whenever data is read by the data visualization system, you must specify a
-format parser (or it is chosen automatically for you). It is the job of the
-parser to read (parse) the data lines and to turn them into data points, that
-is, to setup appropriate subkeys of |/data point/|.
-
-To give a concrete example, suppose a file contains the following
-lines:
-%
-\begin{codeexample}[code only]
-x, y, z
-0, 0, 0
-1, 1, 0
-1, 1, 0.5
-0, 1, 0.5
-\end{codeexample}
-%
-This file is in the \textsc{csv}-format. This format can be read by the |table|
-parser (which is called thus, rather than ``|csv|'', since it can also read
-files in which the columns are separated by, say, a semicolon or a space). The
-|table| format will then read the data and for each line of the data, except
-for the headline of course, it will produce one data point. For instance, for
-the last data point the key |/data point/x| will be set to |0|, the key
-|/data point/y| will be set to |1|, and the key |/data point/z| will be set to
-|0.5|.
-
-All parsers are basically line-oriented. This means that, normally, each line
-in the input data should contain one data point. This rule may not always
-apply, for instance empty lines are typically ignored and sometimes a data
-point may span several lines, but deviating from this ``one data point per
-line'' rule makes parsers harder to program.
-
-
-\subsection{Reference: Built-In Formats}
-
-The following format is the default format, when no |format=...| is specified.
-
-\begin{dataformat}{table}
- This format is used to parse data that is formatted in the following
- manner: Basically, each line consists of \emph{values} that are separated
- by a \emph{separator} like a comma or a space. The values are stored in
- different \emph{attributes}, that is, subkeys of |/data point| like
- |/data point/x|. In order to decide which attribute is chosen for a give
- value, the headline is important. This is the first non-empty line of a
- table. It is formatted in the same way as normal data lines (value
- separated by the separator), but the meaning of the values is different:
- The first value in the headline is the name of the attribute where the
- first values in the following lines should go each time. Similarly, the
- second value in the headline is the name of the attribute for the second
- values in the following lines, and so on.
-
- A simple example is the following:
- %
-\begin{codeexample}[code only]
-angle, radius
-0, 1
-45, 2
-90, 3
-135, 4
-\end{codeexample}
- %
- The headline states that the values in the first column should be stored in
- the |angle| attribute (|/data point/angle| to be precise) and that the
- values in the second column should be stored in the |radius| attribute.
- There are four data points in this data set.
-
- The format will tolerate too few or too many values in a line. If there are
- less values in a line than in the headline, the last attributes will simply
- be empty. If there are more values in a line than in the headline, the
- values are stored in attributes called |/data point/attribute |\meta{column
- number}, where the first value of a line gets \meta{column number} equal to
- |1| and so on.
-
- The |table| format can be configured using the following options:
- %
- \begin{key}{/pgf/data/separator=\meta{character} (initially ,)}
- Use this key to change which character is used to separate values in
- the headline and in the data lines. To set the separator to a space,
- either set this key to an empty value or say |separator=\space|. Note
- that you must surround a comma by curly braces if you which to (re)set
- the separator character to a space.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\begin{tikzpicture}
- \datavisualization [school book axes, visualize as line]
- data [separator=\space] {
- x y
- 0 0
- 1 1
- 2 1
- 3 0
- }
- data [separator=;] {
- x; y; z
- 3; 1; 0
- 2; 2; 0
- };
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/data/headline=\meta{headline}}
- When this key is set to a non-empty value, the value of \meta{headline}
- is used as the headline and the first line of the data is treated as a
- normal line rather than as a headline.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\begin{tikzpicture}
- \datavisualization [school book axes, visualize as line]
- data [headline={x, y}] {
- 0, 0
- 1, 1
- 2, 1
- 3, 0
- };
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{dataformat}
-
-\begin{dataformat}{named}
- Basically, each line of the data must consist of a comma-separated sequence
- of attribute--values pairs like |x=5, lo=500|. This will cause the
- attribute |/data point/x| to be set to |5| and |/data point/lo| to be set
- to |500|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\begin{tikzpicture}
- \datavisualization [school book axes, visualize as line]
- data [format=named] {
- x=0, y=0
- x=1, y=1
- x=2, y=1
- x=3, y=0
- };
-\end{tikzpicture}
-\end{codeexample}
- %
- However, instead of just specifying a single value for an attribute as in
- |x=5|, you may also specify a whole set of values as in |x={1,2,3}|. In
- this case, three data points will be created, one for each value in the
- list. Indeed, the |\foreach| statement is used to iterate over the list of
- values, so you can write things like |x={1,...,5}|.
-
- It is also permissible to specify lists of values for more than one
- attribute. In this case, a data point is created for each possible
- combination of values in the different lists:
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization}},
-]
-\tikz \datavisualization
- [scientific axes=clean,
- visualize as scatter/.list={a,b,c},
- style sheet=cross marks]
-data [format=named] {
- x=0, y={1,2,3}, set=a
- x={2,3,4}, y={3,4,5,7}, set=b
- x=6, y={5,7,...,15}, set=c
-};
-\end{codeexample}
- %
-\end{dataformat}
-
-\begin{dataformat}{TeX code}
- This format will simply execute each line of the data, each of which should
- contain some normal TeX code. Note that at the end of each line control
- returns to the format handler, so for instance the arguments of a command
- may not be spread over several lines. However, not each line needs to
- produce a data point.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\begin{tikzpicture}
- \datavisualization [school book axes, visualize as line]
- data [format=TeX code] {
- \pgfkeys{/data point/.cd,x=0, y=0} \pgfdatapoint
- \pgfkeys{/data point/.cd,x=1, y=1} \pgfdatapoint
- \pgfkeys{/data point/x=2} \pgfdatapoint
- \pgfkeyssetvalue{/data point/x}{3}
- \pgfkeyssetvalue{/data point/y}{0} \pgfdatapoint
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{dataformat}
-
-
-\subsection{Reference: Advanced Formats}
-
-\begin{tikzlibrary}{datavisualization.formats.functions}
- This library defines the formats described in the following, which allow
- you to specify the data points indirectly, namely via a to-be-evaluated
- function.
-
- \begin{dataformat}{function}
- This format allows you to specify a function that is then evaluated in
- order to create the desired data points. In other words, the data lines
- do not contain the data itself, but rather a functional description of
- the data.
-
- The format used to specify the function works as follows: Each nonempty
- line of the data should contain at least one of either a \emph{variable
- declaration} or a \emph{function declaration}. A variable declaration
- signals that a certain attribute will range over a given interval. The
- function declarations will then, later, be evaluated for values inside
- this interval. The syntax for a variable declaration is one of the
- following:
- %
- \begin{enumerate}
- \item |var |\declare{\meta{variable}}| : interval[|\meta{low}|:|\meta{high}|]|
- \opt{|samples |\meta{number}}|;|
- \item |var |\declare{\meta{variable}}| : interval[|\meta{low}|:|\meta{high}%
- |] step |\meta{step}|;|
- \item |var |\declare{\meta{variable}}| : {|\meta{values}|};|
- \end{enumerate}
- %
- In the first case, if the optional |samples| part is missing, the
- number of |samples| is taken from the value stored in the following
- key:
- %
- \begin{key}{/pgf/data/samples=\meta{number} (initially 25)}
- Sets the number of samples to be used when no sample number is
- specified.
- \end{key}
- %
- The meaning of declaring a variable declaration to range over an
- |interval| is that the attribute named \meta{variable}, that is, the
- key |/data point/|\meta{variable}, will range over the interval
- $[\meta{low},\meta{high}]$. If the number of |samples| is given
- (directly or indirectly), the interval is evenly divided into
- \meta{number} many points and the attribute is set to each of these
- values. Similarly, when a \meta{step} is specified, this stepping is
- used to increase \meta{low} iteratively up to the largest value that is
- still less or equal to \meta{high}.
-
- The meaning of declaring a variable using a list of \meta{values} is
- that the variable will simply iterate over the values using |\foreach|.
-
- You can specify more than one variable. In this case, each variable is
- varied independently of the other variables. For instance, if you
- declare an $x$-variable to range over the interval $[0,1]$ in $25$
- steps and you also declare a $y$-variable to range over the same
- interval, you get a total of $625$ value pairs.
-
- The variable declarations specify which (input) variables will take
- which values. It is the job of the \emph{function declarations} to
- specify how some additional attributes are to be computed. The syntax
- of a function declaration is as follows:
- %
- \begin{quote}
- |func |\declare{\meta{attribute}}| = |\meta{expression}|;|
- \end{quote}
- %
- The meaning of such a declaration is the following: For each setting of
- the input variables (the variables specified using the |var|
- declaration), evaluate the \meta{expression} using the standard
- mathematical parser of \tikzname. The resulting value is then stored in
- |/data point/|\meta{attribute}.
-
- Inside \meta{expression} you can reference data point attributes using
- the following command, which is only defined inside such an expression:
- %
- \begin{command}{\value\marg{variable}}
- This expands to the current value of the key
- |/data point/|\meta{variable}.
- \end{command}
-
- There can be multiple function declarations in a single data
- specification. In this case, all of these functions will be evaluated
- for each setting of input variables.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz
- \datavisualization [school book axes, visualize as smooth line]
- data [format=function] {
- var x : interval [-1.5:1.5];
-
- func y = \value x * \value x;
- };
-\end{codeexample}
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization [
- school book axes,
- all axes={unit length=5mm, ticks={step=2}},
- visualize as smooth line]
-data [format=function] {
- var t : interval [0:2*pi];
-
- func x = \value t * cos(\value t r);
- func y = \value t * sin(\value t r);
-};
-\end{codeexample}
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization [
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- visualize as smooth line/.list={1,2,3,4,5,6},
- style sheet=vary hue]
-data [format=function] {
- var set : {1,...,6};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
-};
-\end{codeexample}
- \end{dataformat}
-\end{tikzlibrary}
-
-
-\subsection{Advanced: The Data Parsing Process}
-\label{section-dv-parsing}
-
-Whenever data is fed to the data visualization system, it will be handled by
-the |\pgfdata| command, declared in the |datavisualization| module. The command
-is both used to parse data stored in external sources (that is, in external
-files or which is produced on the fly by calling an external command) as well
-as data given inline. A data format does not need to know whether data comes
-from a file or is given inline, the |\pgfdata| command will take care of this.
-
-Since \TeX\ will always read files in a line-wise fashion, data is always fed
-to data format parsers in such a fashion. Thus, even it would make more sense
-for a format to ignore line-breaks, the parser must still handle data given
-line-by-line.
-
-Let us now have a look at how |\pgfdata| works.
-
-\begin{command}{\pgfdata\opt{\oarg{options}\marg{inline data}}}
- This command is used to feed data to the visualization pipeline. This
- command can only be used when a data visualization object has been properly
- setup, see Section~\ref{section-dv-main-setup}.
-
-
- \medskip
- \textbf{Basic options.}
- The |\pgfdata| command may be followed by \meta{options}, which are
- executed with the path |/pgf/data/|. Depending on these options, the
- \meta{options} may either be followed by \meta{inline data} or,
- alternatively, no \meta{inline data} is present and the data is read from
- an external source.
-
- The first important option is \meta{source}, which governs which of these
- two alternatives applies:
- %
- \begin{key}{/pgf/data/read from file=\meta{filename} (initially \normalfont empty)}
- If you set the |read from file| attribute to a non-empty
- \meta{filename}, the data will be read from this file. In this case, no
- \meta{inline data} may be present, not even empty curly braces should
- be provided. If |read from file| is empty, the data must directly
- follow as \meta{inline data}.
- %
-\begin{codeexample}[code only]
-% Data is read from two external files:
-\pgfdata[format=table, read from file=file1.csv]
-\pgfdata[format=table, read from file=file2.csv]
-\end{codeexample}
- %
-\begin{codeexample}[code only]
-% Data is given inline:
-\pgfdata[format=table]
-{
- x, y
- 1, 2
- 2, 3
-}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/data/inline}
- This is a shorthand file |read from file={}|. You can add this to make
- it clear(er) to the reader that data follows inline.
- \end{key}
- %
- The second important key is |format|, which is used to specify the data
- format:
- %
- \begin{key}{/pgf/data/format=\meta{format} (initially table)}
- Use this key to locally set the format used for parsing the data. The
- \meta{format} must be a format that has been previously declared using
- the |\pgfdeclaredataformat| command. See the reference section for a
- list of the predefined formats.
- \end{key}
- %
- In case all your data is in a certain format, you may wish to generally set
- the above key somewhere at the beginning of your file. Alternatively, you
- can use the following style to setup the |format| key and possibly further
- keys concerning the data format:
- %
- \begin{stylekey}{/pgf/every data}
- This style is executed by |\pgfdata| before the \meta{options} are
- parsed.
-
- Note that the path of this key is just |/pgf/|, not |/pgf/data/|. Also
- note that \tikzname\ internally sets the value of this key up in such a
- way that the keys |/tikz/every data| and also
- |/tikz/data visualization/every data| are executed. The bottom line of
- this is that when using \tikzname, you should not set this key
- directly, set |/tikz/every data| instead.
- \end{stylekey}
-
- \medskip
- \textbf{Gathering of the data.}
- Once the data format and the source have been decided upon, the data is
- ``gathered''. During this phase the data is not actually parsed in detail,
- but just gathered so that it can later be parsed during the visualization.
- There are two different ways in which the data is gathered:
- %
- \begin{itemize}
- \item In case you have specified an external source, the data
- visualization object is told (by means of invoking the |add data|
- method) that it should (later) read data from the file specified
- by the |source| key using the format specified by the |format| key.
- The file is not read at this point, but only later during the
- actual visualization.
- \item Otherwise, namely when data is given inline, depending on which
- format is used, some catcodes get changed. This is necessary since
- \TeX's special characters are often not-so-special in a certain
- format.
-
- Independently of the format, the end-of-line character (carriage
- return) is made an active character.
-
- Finally, the \meta{inline data} is then read as a normal argument
- and the data visualization object is told that later on it should
- parse this data using the given format parser. Note that in this
- case the data visualization object must store the whole data
- internally.
- \end{itemize}
- %
- In both cases the ``data visualization object'' is the object stored
- in the |/pgf/data visualization/obj| key.
-
-
- \medskip
- \textbf{Parsing of the data.}
- During the actual data visualization, all code that has been added to the
- data visualization object by means of the |add data| method is executed
- several times. It is the job of this code to call the |\pgfdatapoint|
- method for all data points present in the data.
-
- When the |\pgfdata| method calls |add data|, the code that is passed to the
- data visualization object is just a call to internal macros of |\pgfdata|,
- which are able to parse the data stored in an external file or in the
- inlined data. Independently of where the data is stored, these macros
- always do the following:
- %
- \begin{enumerate}
- \item The catcodes are setup according to what the data format
- requires.
- \item Format-specific startup code gets called, which can initialize
- internal variables of the parsing process. (The catcode changes are
- not part of the startup code since in order to read inline data
- |\pgfdata| must be able to setup to temporarily setup the catcodes
- needed later on by the parsers, but since no reading is to be done,
- no startup code should be called at this point.)
- \item For each line of the data a format-specific code handler, which
- depends on the data format, is called. This handler gets the
- current line as input and should call |\pgfdatapoint| once for each
- data point that is encoded by this line (a line might define
- multiple data points or none at all). Empty lines are handled by
- special format-specific code.
- \item At the end, format-specific end code is executed.
- \end{enumerate}
- %
- For an example of how this works, see the description of the
- |\pgfdeclaredataformat| command.
-
-
- \medskip
- \textbf{Data sets.}
- There are three options that allow you to create \emph{data sets}. Such a
- data set is essentially a macro that stores a pre-parsed set of data that
- can be used multiple times in subsequent visualizations (or even in the
- same visualization).
- %
- \begin{key}{/pgf/data/new set=\meta{name}}
- Creates an empty data set called \meta{name}. If a data set of the same
- name already exists, it is overwritten and made empty. Data sets are
- global.
- \end{key}
- %
- \begin{key}{/pgf/data/store in set=\meta{name}}
- When this key is set to any non-empty \meta{name} and if this
- \meta{name} has previously been used with the |new set| key, then the
- following happens: For the current |\pgfdata| command, all parsed data
- is not passed to the rendering pipeline. Instead, the parsed data is
- appended to the data set \meta{name}. This includes all options parsed
- to the |\pgfdata| command, which is why neither this key nor the
- previous key should be passed as options to a |\pgfdata| command.
- \end{key}
- %
- \begin{key}{/pgf/data/use set=\meta{name}}
- This works similar to |read from file|. When this key is used with a
- |\pgfdata| command, no inline data may follow. Instead, the data stored
- in the data set \meta{name} is used.
- \end{key}
-\end{command}
-
-
-\subsection{Advanced: Defining New Formats}
-\label{section-dv-declaring-formats}
-
-In order to define a new data format you can use the following command, which
-is basic layer command defined in the module |datavisualization|:
-
-\begin{command}{\pgfdeclaredataformat\marg{format name}\marg{catcode
- code}\marg{startup code}\marg{line arguments}\\\marg{line
- code}\marg{empty line code}\marg{end code}%
-}
- This command defines a new data format called \meta{format name}, which can
- subsequently be used in the |\pgfdata| command. (The \tikzname's |data|
- maps directly to |\pgfdata|, so the following applies to \tikzname\ as
- well.)
-
- As explained in the description of the |\pgfdata| command, when data is
- being parsed that is formatted according to \meta{format name}, the
- following happens:
- %
- \begin{enumerate}
- \item The \meta{catcode code} is executed. This code should just
- contain catcode changes. The \meta{catcode code} will also be
- executed when inline data is read.
- \item Next, the \meta{startup code} is executed.
- \item Next, for each non-empty line of the data, the line is passed to
- a macro whose argument list is given by \meta{line arguments} and
- whose body is given by \meta{line code}. The idea is that you can
- use \TeX's powerful pattern matching capabilities to parse the
- non-empty lines. See also the below example.
- \item Empty lines are not processed by the \meta{line code}, but rather
- by the \meta{empty line code}. Typically, empty lines can simply be
- ignored and in this case you can let this parameter be empty.
- \item At the end of the data, the \meta{end code} is executed.
- \end{enumerate}
-
- As an example, let us now define a simple data format for reading files
- formatted in the following manner: Each line should contain a coordinate
- pair as in |(1.2,3.2)|, so two numbers separated by a comma and surrounded
- by parentheses. To make things more interesting, suppose that the hash mark
- symbol can be used to indicate comments. Here is an example of some data
- given in this format:
- %
-\begin{codeexample}[code only]
-# This is some data formatted according to the "coordinates" format
-(0,0)
-(0.5,0.25)
-(1,1)
-(1.5,2.25)
-(2,4)
-\end{codeexample}
-
- A format parser for this format could be defined as follows:
- %
-\begin{codeexample}[code only]
-\pgfdeclaredataformat{coordinates}
-% First comes the catcode argument. We turn the hash mark into a comment character.
-{\catcode`\#=14\relax}
-% Second comes the startup code. Since we do not need to setup things, we can leave
-% it empty. Note that we could also set it to something like \begingroup, provided we
-% put an \endgroup in the end code
-{}
-% Now comes the arguments for non-empty lines. Well, these should be of the form
-% (#1,#2), so we specify that:
-{(#1,#2)}
-% Now we must do something with a line of this form. We store the #1 argument in
-% /data point/x and #2 in /data point/y. Then we call \pgfdatapoint to create a data point.
-{
- \pgfkeyssetvalue{/data point/x}{#1}
- \pgfkeyssetvalue{/data point/y}{#2}
- \pgfdatapoint
-}
-% We ignore empty lines:
-{}
-% And we also have no end-of-line code.
-{}
-\end{codeexample}
- %
- This format could now be used as follows:
- %
-\begin{codeexample}[code only]
-\begin{tikzpicture}
- \datavisualization[school book axes, visualize as smooth line]
- data [format=coordinates] {
- # This is some data formatted according
- # to the "coordinates" format
- (0,0)
- (0.5,0.25)
- (1,1)
- (1.5,2.25)
- (2,4)
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-introduction.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-introduction.tex
deleted file mode 100644
index 88641aea6b..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-introduction.tex
+++ /dev/null
@@ -1,148 +0,0 @@
-% 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{Introduction to Data Visualization}
-
-\emph{Data visualization} is the process of converting \emph{data points,}
-which typically consist of multiple numerical values, into a graphical
-representation. Examples include the well-known function plots, but pie charts,
-bar diagrams, box plots, or vector fields are also examples of data
-visualizations.
-
-The data visualization subsystem of \pgfname\ takes a general, open approach to
-data visualization. Like everything else in \pgfname, there is a powerful, but
-not-so-easy-to-use basic layer in the data visualization system and a less
-flexible, but much simpler-to-use frontend layer. The present section gives an
-overview of the basic ideas behind the data visualization system.
-
-
-\subsection{Concept: Data Points}
-\label{section-dv-intro-data-points}
-
-The most important input for a data visualization is always raw data. This data
-is typically present in different formats and the data visualization subsystem
-provides methods for reading such formats and also for defining new input
-formats. However, independently of the input format, we may ask what kind of
-data the data visualization subsystem should be able to process. For
-two-dimensional plots we need lists of pairs of real numbers. For a bar plot we
-usually need a list of numbers, possibly together with some colors and labels.
-For a surface plot we need a matrix of triples of real numbers. For a vector
-field we need even more complex data.
-
-The data visualization subsystem makes no assumption concerning which kind of
-data is being processed. Instead, the whole ``rendering pipeline'' is centered
-around a concept called the \emph{data point}. Conceptually, a data point is an
-arbitrarily complex record that represents one piece of data that should be
-visualized. Data points are \emph{not} just coordinates in the plane or the
-numerical values that need to be visualized. Rather, they represent the basic
-units of the data that needs to be visualized.
-
-Consider the following example: In an experiment we drive a car along a road
-and have different measurement instruments installed. We measure the position
-of the car, the time, the speed, the direction the car is heading, the
-acceleration, and perhaps some further values. A data point would consist of a
-record consisting of a timestamp together with the current position of the car
-(presumably two or three numbers), the speed vector (another two or three
-numbers), the acceleration (another two or three numbers), and perhaps the
-label text of the current experiment.
-
-Data points should be ``information rich''. They might even contain more
-information than what will actually be visualized. It is the job of the
-rendering pipeline to pick out the information relevant to one particular data
-visualization -- another visualization of the same data might pick different
-aspects of the data points, thereby hopefully allowing new insights into the
-data.
-
-Technically, there is no special data structure for data points. Rather, when a
-special macro called |\pgfdatapoint| is called, the ``totality'' of all
-currently set keys with the |/data point/| prefix in the current scope forms
-the data point. This is both a very general approach and quite fast since no
-extra data structures need to be created.
-
-
-\subsection{Concept: Visualization Pipeline}
-
-The \emph{visualization pipeline} is a series of actions that are performed on
-the to-be-visualized data. The data is presented to the visualization pipeline
-in the form of a long stream of complex data points. The visualization
-pipeline makes several passes over this stream of data points. During the first
-pass(es), called the \emph{survey phase(s)}, information is gathered about the
-data points such as minimal and maximal values, which can be useful for
-automatic fitting of the data into a given area. In the main pass over the
-data, called the \emph{visualization phase}, the data points are actually
-visualized, for instance in the form of lines or points.
-
-Like as for data points, the visualized pipeline makes no assumptions
-concerning what kind of visualization is desired. Indeed, one could even use it
-to produce a plain-text table. This flexibility is achieved by extensive use of
-objects and signals: When a data visualization starts, a number of signals (see
-Section~\ref{section-signals} for an introduction to signals) are initialized.
-Then, numerous ``visualization objects'' are created that listen to these
-signals. These objects are all involved in processing the data points. For
-instance, the job of an |interval mapper| object is to map one attribute of a
-data point, such as a car's velocity, to another, such as the $y$-axis of a
-plot. For each data point the different signals are raised in a certain order
-and the different visualization objects now have a chance of preparing the data
-point for the actual visualization. Continuing the above example, there might
-be a second |interval mapper| that takes the computed $y$-position and applies
-a logarithm to it, because a log-plot was requested. Then another mapper, this
-time a |polar mapper| might be used to map everything to polar coordinates.
-Following this, a |plot mark visualizer| might actually draw something at the
-computed position.
-
-The whole idea behind the rendering pipeline is that new kinds of data
-visualizations can be implemented, ideally, just by adding one or two new
-objects to the visualization pipeline. Furthermore, different kinds of plots
-can be combined in novel ways in this manner, which is usually very hard to do.
-For instance, the visualization pipeline makes it easy to create, say,
-polar-semilog-box-plots. At first sight, such new kinds of plots may seem
-frivolous, but data visualization is all about gaining insights into the data
-from as many different angles as possible.
-
-Naturally, creating new classes and objects for the rendering pipeline is not
-trivial, so most users will just use the existing classes, which should, thus,
-be as flexible as possible. But even when one only intends to use existing
-classes, it is still tricky to setup the pipeline correctly since the ordering
-is obviously important and since things like axes and ticks need to be
-configured and taken care of. For this reason, the frontend libraries provide
-preconfigured rendering pipelines so that one can simply say that a data
-visualization should look like a |line plot| with |school book axes| or with
-|scientific axes|, which selects a certain visualization pipeline that is
-appropriate for this kind of plot:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}[scale=.7]
- \datavisualization [school book axes, visualize as smooth line]
- data [format=function] {
- var x : interval [-2:2];
- func y = \value x*\value x + 1;
- };
-\end{tikzpicture}
-\end{codeexample}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}[scale=.7]
- \datavisualization [scientific axes, visualize as smooth line]
- data [format=function] {
- var x : interval [-2:2];
- func y = \value x*\value x + 1;
- };
-\end{tikzpicture}
-\end{codeexample}
-%
-One must still configure such a plot (choose styles and themes and also specify
-which attributes of a data point should be used), but on the whole the plot is
-quite simple to specify.
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-main.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-main.tex
deleted file mode 100644
index 9f95a44606..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-main.tex
+++ /dev/null
@@ -1,828 +0,0 @@
-% 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{Creating Data Visualizations}
-\label{section-dv-main}
-\label{section-dv-main-setup}
-
-\subsection{Overview}
-
-The \todosp{why two labels? The first doesn't seem to be used.} present section
-explains how a data visualization is created in \tikzname. For this, you need
-to include the |datavisualization| library and then use the command
-|\datavisualization| whose syntax is explained in the rest of the present
-section. This command is part of the following library:
-
-\begin{tikzlibrary}{datavisualization}
- This library must be loaded if you wish to use the |\datavisualization|
- command. It defines all styles needed to create basic data visualizations;
- additional, more specialized libraries need to be loaded for more advanced
- features.
-\end{tikzlibrary}
-
-In order to visualize, you basically need to do three things:
-%
-\begin{enumerate}
- \item You need to select what kind of plot you would like to have (a
- ``school book plot'' or a ``scientific 2d plot'' or a ``scientific
- spherical plot'' etc.). This is done by passing an option to the
- |\datavisualization| command that selects this kind of plot.
- \item You need to provide data points, which is done using the |data|
- command.
- \item Additionally, you can add options that give you more fine-grained
- control over the way the visualization will look. You can configure the
- number of ticks and grid lines, where the labels are placed, the
- colors, or the fonts. Indeed, since the data visualization engine
- internally uses \tikzname-styles, you can have extremely fine-grained
- control over how a plot will look like.
-\end{enumerate}
-
-The syntax of the |\datavisualization| command is designed in such a way that
-you only need to provide very few options to create plots that ``look good by
-default''.
-
-This section is structured as follows: First, the philosophy behind concepts
-like ``data points'', ``axes'', or ``visualizers'' is explained. Each of these
-concepts is further detailed in later section. Then, the syntax of the
-|\datavisualization| command is covered. The reference sections explain which
-predefined plot kinds are available.
-
-
-\subsection{Concept: Data Points and Data Formats}
-
-As explained in Section~\ref{section-dv-intro-data-points}, data points are the
-basic entities that are processed by the data visualization engine. In order to
-specify data points, you use the |data| command, whose syntax is explained in
-more detail in Section~\ref{section-dv-data-syntax}. The |data| command allows
-you to either specify points ``inline'', directly inside your \TeX-file; or you
-can specify the name of file that contains the data points.
-
-\medskip
-\textbf{Specifying data points.}
-Data points can be formatted in different ways. For instance, in the so called
-\emph{comma separated values} format, there is one line for each data point and
-the different attributes of a data point are separated by commas. Another
-common format is to specify data points using the so called \emph{key--value}
-format, where on each line the different attributes of a data point are set
-using a comma-separated list of strings of the form |attribute=value|.
-
-Here are two examples, where similar data is given in different formats:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\begin{tikzpicture}
- \datavisualization [school book axes, visualize as smooth line]
- data {
- x, y
- -1.5, 2.25
- -1, 1
- -.5, .25
- 0, 0
- .5, .25
- 1, 1
- 1.5, 2.25
- };
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [school book axes, visualize as smooth line]
- data [format=function] {
- var x : interval [-1.5:1.5] samples 7;
- func y = \value x*\value x;
- };
-\end{tikzpicture}
-\end{codeexample}
-
-In the first example, no format needed to be specified explicitly since the
-default format is the one used for the data following the |data| keyword: A
-list of comma-separated values, where each line represents a data point.
-
-\medskip
-\textbf{Number accuracy.}\label{section-dv-expressions}
-Data visualizations typically demand a much higher accuracy and range of values
-than \TeX\ provides: \TeX\ numbers are limited to 13 bits for the integer part
-and 16 bits for the fractional part. Because of this, the data visualization
-engine does not use \pgfname's standard representation of numbers and \TeX\
-dimensions and is does not use the standard parser when reading numbers in a
-data point. Instead, the |fpu| library, described in
-Section~\ref{section-library-fpu}, is used to handle numbers.
-
-This use of the |fpu| library has several effects that users of the data
-visualization system should be aware of:
-%
-\begin{enumerate}
- \item You can use numbers like |100000000000000| or |0.00000000001| in a
- data points.
- \item Since the |fpu| library does not support advanced parsing, you
- currently \emph{cannot} write things like |3+2| in a data point number.
- This will result in an error.
- \item However, there is a loop-hole: If a ``number'' in a data point starts
- with a parenthesis, the value between the parentheses \emph{is} parsed
- using the normal parser:
- %
- \begin{itemize}
- \item |100000| is allowed.
- \item |2+3| yields an error.
- \item |(2+3)| is allowed and evaluates to |5|.
- \item |(100000)| yields an error since $100\,000$ is beyond the
- normal parser's precision.
- \end{itemize}
- %
- The bottom line is that any normal calculations should be set inside
- round parentheses, while large numbers should not be surrounded by
- parentheses. Hopefully, in the future, these restrictions will be
- lifted.
-\end{enumerate}
-
-Section~\ref{section-dv-formats} gives an in-depth coverage of the available
-data formats and explains how new data formats can be defined.
-
-
-\subsection{Concept: Axes, Ticks, and Grids}
-
-Most plots have two or three axes: A horizontal axis usually called the
-$x$-axis, a vertical axis called the $y$-axis, and possibly some axis pointing
-in a sloped direction called the $z$-axis. Axes are usually drawn as lines with
-\emph{ticks} indicating interesting positions on the axes. The data
-visualization engine gives you detailed control over where these ticks are
-rendered and how many of them are used. Great care is taken to ensure that the
-position of ticks are chosen well by default.
-
-From the point of view of the data visualization engine, axes are a somewhat
-more general concept than ``just'' lines that point ``along'' some dimension:
-The data visualization engine uses axes to visualize any change of an attribute
-by varying the position of data points in the plane. For instance, in a polar
-plot, there is an ``axis'' for the angle and another ``axis'' for the distance
-if the point from the center. Clearly these axes vary the position of data
-points in the plane according to some attribute of the data points; but just as
-clearly they do not point in any ``direction''.
-
-A great benefit of this approach is that the powerful methods for specifying
-and automatic inference of ``good'' positions for ticks or grid lines apply to
-all sorts of situations. For instance, you can use it to automatically put
-ticks and grid lines at well-chosen angles of a polar plot.
-
-Typically, you will not need to specify axes explicitly. Rather, predefined
-styles take care of this for you:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [
- scientific axes,
- x axis={length=3cm, ticks=few},
- visualize as smooth line
- ]
- data [format=function] {
- var x : interval [-1.5:1.5] samples 7;
- func y = \value x*\value x;
- };
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [
- scientific axes=clean,
- x axis={length=3cm, ticks=few},
- all axes={grid},
- visualize as smooth line
- ]
- data [format=function] {
- var x : interval [-1.5:1.5] samples 7;
- func y = \value x*\value x;
- };
-\end{tikzpicture}
-\end{codeexample}
-
-Section~\ref{section-dv-axes} explains in more detail how axes, ticks, and grid
-lines can be chosen and configured.
-
-
-\subsection{Concept: Visualizers}
-
-Data points and axes specify \emph{what} is visualized and \emph{where}. A
-\emph{visualizer} specifies \emph{how} they are visualized. One of the most
-common visualizers is a \emph{line visualizer} which connects the positions of
-the data points in the plane using a line. Another common visualizer is the
-\emph{scatter plot visualizer} where small marks are drawn at the positions of
-the data points. More advanced visualizers include, say, box plot visualizers
-or pie chart visualizers.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [
- scientific axes=clean,
- x axis={length=3cm, ticks=few},
- visualize as smooth line
- ]
- data [format=function] {
- var x : interval [-1.5:1.5] samples 7;
- func y = \value x*\value x;
- };
-\end{tikzpicture}
-\end{codeexample}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}
- \datavisualization [
- scientific axes=clean,
- x axis={length=3cm, ticks=few},
- visualize as scatter
- ]
- data [format=function] {
- var x : interval [-1.5:1.5] samples 7;
- func y = \value x*\value x;
- };
-\end{tikzpicture}
-\end{codeexample}
-
-Section~\ref{section-dv-visualizers} provides more information on visualizers
-as well as reference lists.
-
-
-\subsection{Concept: Style Sheets and Legends}
-
-A single data visualizations may use more than one visualizer. For instance, if
-you wish to create a plot containing several lines, a separate visualizer is
-used for each line. In this case, two problems arise:
-%
-\begin{enumerate}
- \item You may wish to make it easy for the reader to differentiate between
- the different visualizers. For instance, one line should be black,
- another should be red, and another blue. Alternatively, you might wish
- one line to be solid, another to be dashed, and a third to be dotted.
-
- Specifying such styles is trickier than one might expect; experience
- shows that many plots use ill-chosen and inconsistent styling. For this
- reason, the data visualization introduces the notion of \emph{style
- sheets} for visualizers and comes with some well-designed predefined
- style sheets.
- \item You may wish to add information concerning what the different
- visualizers represent. This is typically done using a legend, but it is
- even better to add labels directly inside the visualization. Both
- approaches are supported.
-\end{enumerate}
-
-An example where three functions are plotted and a legend is added is shown
-below. Two style sheets are used so that \emph{both} the coloring and the
-dashing is varied.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}[baseline]
- \datavisualization [ scientific axes=clean,
- y axis=grid,
- visualize as smooth line/.list={sin,cos,tan},
- style sheet=strong colors,
- style sheet=vary dashing,
- sin={label in legend={text=$\sin x$}},
- cos={label in legend={text=$\cos x$}},
- tan={label in legend={text=$\tan x$}},
- data/format=function ]
- data [set=sin] {
- var x : interval [-0.5*pi:4];
- func y = sin(\value x r);
- }
- data [set=cos] {
- var x : interval [-0.5*pi:4];
- func y = cos(\value x r);
- }
- data [set=tan] {
- var x : interval [-0.3*pi:.3*pi];
- func y = tan(\value x r);
- };
-\end{tikzpicture}
-\end{codeexample}
-
-Section~\ref{section-dv-style-sheets} details style sheets and legends.
-
-
-\subsection{Usage}
-\label{section-dv-data-syntax}
-
-Inside a \tikzname\ picture you can use the |\datavisualization| command to
-create a data visualization. You can use this command several times in a
-picture to create pictures containing multiple data visualizations.
-
-\begin{command}{\datavisualization\opt{\oarg{data visualization options}}\meta{data specification}|;|}
- This command is available only inside a |{tikzpicture}| environment.
-
- The \meta{data visualization options} are used to configure the data
- visualization, that is, how the data is to be depicted. The options are
- executed with the path prefix |/tikz/data visualization|. This means that
- normal \tikzname\ options like |thin| or |red| cannot be used here. Rather,
- a large number of options specific to data visualizations are available.
-
- As a minimum, you should specify at least two options: First, you should
- use an option that selects an axis system that is appropriate for your
- plot. Typical possible keys are |school book axes| or |scientific axes|,
- detailed information on them can be found in Section~\ref{section-dv-axes}.
-
- Second, you use an option to select \emph{how} the data should be
- visualized. This is done using a key like |visualize as line| which will,
- as the name suggests, visualize the data by connecting data points in the
- plane using a line. Similarly, |visualize as smooth cycle| will try to fit
- a smooth cycle through the data points. Detailed information on possible
- visualizers can be found in Section~\ref{section-dv-visualizers}.
-
- Following these options, the \meta{data specification} is used to provide
- the actual to-be-visualized data. The syntax is somewhat similar to
- commands like |\path|: The \meta{data specification} is a sequence of
- keywords followed by local options and parameters, terminated with a
- semicolon. (Indeed, like for the |\path| command, the \meta{data
- visualizers options} need not be specified at the beginning, but additional
- option surrounded by square brackets may be given anywhere inside the
- \meta{data specification}.)
-
- The different possible keywords inside the \meta{data specification} are
- explained in the following.
-\end{command}
-
-\begin{datavisualizationoperation}{data}{\opt{\oarg{options}}\opt{\marg{inline data}}}
- This command is used to specify data for the data visualization. It can be
- used several times inside a single visualization and each time the
- to-be-read data may have a different format, but the data will be
- visualized as if it have been specified inside a single |data| command.
-
- The behavior of the |data| command depends on whether the \meta{inline
- data} is present. If it is not present, the \meta{options} must be used to
- specify a source file from which the data is read; if the \meta{inline
- data} is present no file will be used, instead the data should directly
- reside inside the \TeX-file and be given between the curly braces
- surrounding the \meta{inline data}.
-
- The \meta{options} are executed with the prefix |/pgf/data|. The following
- options are always available:
- %
- \begin{key}{/pgf/data/read from file=\meta{filename} (initially \normalfont empty)}
- If you set the |source| attribute to a non-empty \meta{filename}, the
- data will be read from this file. In this case, no \meta{inline data}
- may be present, not even empty curly braces should be provided.
- %
-\begin{codeexample}[code only]
-\datavisualization ...
- data [read from file=file1.csv]
- data [read from file=file2.csv];
-\end{codeexample}
- %
- The other way round, if |read from file| is empty, the data must
- directly follow as \meta{inline data}.
- %
-\begin{codeexample}[code only]
-\datavisualization ...
- data {
- x, y
- 1, 2
- 2, 3
- };
-\end{codeexample}
- \end{key}
- %
- The second important key is |format|, which is used to specify the data
- format:
- %
- \begin{key}{/pgf/data/format=\meta{format} (initially table)}
- Use this key to locally set the format used for parsing the data, see
- Section~\ref{section-dv-formats} for a list of predefined formats.
-
- The default format is the |table|-format, also known as
- ``comma-separated values''. The first line contains names of attributes
- separated by commas, all following lines constitute a data point where
- the attributes are given by the comma-separated values in that line.
- \end{key}
-
-
- \medskip
- \textbf{Presetting attributes.}
- Normally, the inline data or the external data contains for each data point
- the values of the different attributes. However, sometimes you may also
- wish to set an attribute to a fixed value for all data points of a data
- set. Suppose, for instance, that you have to source files
- |experiment007.csv| and |experiment023.csv| and you would like that for all
- data points of the first file the attribute |/data point/experiment id| is
- set to 7 while for the data points of the second file they are set to 23.
- In this case, you can specify the desired settings using an absolute path
- inside the \meta{options}. The effect will be local to the current |data|
- command:
- %
-\begin{codeexample}[code only]
-\datavisualization...
- data [/data point/experiment=7, read from file=experiment007.csv]
- data [/data point/experiment=23, read from file=experiment023.csv];
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz
- \datavisualization [school book axes, visualize as line]
- data [/data point/x=1] {
- y
- 1
- 2
- }
- data [/data point/x=2] {
- y
- 2
- 0.5
- };
-\end{codeexample}
-
-
- \medskip
- \textbf{Setting options for multiple |data| commands.}
- You may wish to generally set the format once and for all. This can be done
- by using the following key:
- %
- \begin{stylekey}{/tikz/every data}
- This key is executed for every |data| command.
- \end{stylekey}
-
- Another way of passing options to multiple |data| commands is to use the
- following facility: Whenever an option with the path
- |/tikz/data visualization/data| is used, the path will be remapped to
- |/pgf/data|. This means, in particular, that you can pass an option like
- |data/format=table| to the |\datavisualization| command to set the data
- format for all |data| commands of the data visualization.
-
-
- \medskip
- \textbf{Parsing inline data.}
- When you specify data inline, \TeX\ needs to read the data
- ``line-by-line'', while \TeX\ normally largely ignores end-of-line
- characters. For this reason, the data visualization system temporarily
- changes the meaning of the end-of-line character. This is only possible if
- \TeX\ has not already processed the data in some other way (namely as the
- parameter to some macro).
-
- The bottom line is that you cannot use inline data when the whole
- |\datavisualization| command is passed as a parameter to some macro that is
- not setup to handle ``fragile'' code. For instance, in a \textsc{beamer}
- |frame| you need to add the |fragile| option when a data visualization
- contains inline data.
-
- The problem does not arise when an external data |source| is specified.
-\end{datavisualizationoperation}
-
-\begin{datavisualizationoperation}{data point}{\opt{\oarg{options}}}
- This command is used to specify data a single data point. The
- \meta{options} are simply executed with the path |/data point| and then a
- data point is created. This means that inside the \meta{options} you just
- specify the values of all attributes in key--value syntax.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [school book axes, visualize as line]
- data point [x=1, y=1] data point [x=1, y=2]
- data point [x=2, y=2] data point [x=2, y=0.5];
-\end{codeexample}
- %
-\end{datavisualizationoperation}
-
-\begin{key}{/tikz/data visualization/data point=\meta{options}}
- This key is the ``key version'' of the previous command. The difference is
- that this key can be used internally inside styles.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikzdatavisualizationset{
- horizontal/.style={
- data point={x=#1, y=1}, data point={x=#1, y=2}},
-}
-\tikz \datavisualization
-[ school book axes, visualize as line,
- horizontal=1,
- horizontal=2 ];
-\end{codeexample}
- %
-\end{key}
-
-\begin{datavisualizationoperation}{data group}{\opt{\oarg{options}}\marg{name}\opt{|+=|\marg{data specifications}}}
- You can store a whole \meta{data specification} in a \emph{data group}.
- This allows you to reuse data in multiple places without having to write
- the data to an external file.
-
- The syntax of this command comes in the following three variants:
- %
- \begin{itemize}
- \item |data group| \opt{\oarg{options}} \marg{name} |=| \marg{data
- specifications}
- \item |data group| \opt{\oarg{options}} \marg{name} |+=| \marg{data
- specifications}
- \item |data group| \opt{\oarg{options}} \marg{name}
- \end{itemize}
- %
- In the first case, a new data group called \meta{name} is created (an
- existing data group of the same name will be erased) and the following
- \meta{data specifications} is stored in this data group. The data group
- will not be fed to the rendering pipeline, but it is parsed at this point
- as if it were. The defined data group is defined globally, so you can used
- it in subsequent visualizations. The \meta{options} are saved with the
- parsed \meta{data specifications}.
-
- In the second case, an already existing data group is extended by adding
- the \meta{data specifications} to it.
-
- In the third case (detected by noting that the \meta{name} is neither
- followed by an equal sign nor a plus sign), the contents of the previously
- defined data group \meta{name} is inserted. The \meta{options} are also
- executed.
-
- Let is now first create a data group. Note that nothing is drawn since the
- ``dummy'' data visualization is empty and used only for the definition of
- the data group.
- %
-\begin{codeexample}[setup code]
-\tikz \datavisualization data group {points} = {
- data {
- x, y
- 0, 1
- 1, 2
- 2, 2
- 5, 1
- 2, 0
- 1, 1
- }
-};
-\end{codeexample}
-
- We can now use this data in different plots:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [school book axes, visualize as line] data group {points};
-\qquad
-\tikz \datavisualization [scientific axes=clean, visualize as line] data group {points};
-\end{codeexample}
- %
-\end{datavisualizationoperation}
-
-\begin{datavisualizationoperation}{scope}{\opt{\oarg{options}}\marg{data specification}}
- Scopes can be used to nest hierarchical data sets. The \meta{options} will
- be executed with the path |/pgf/data| and will only apply to the data sets
- specified inside the \meta{data specification}, which may contain |data| or
- |scope| commands once more:
- %
-\begin{codeexample}[code only]
-\datavisualization...
- scope [/data point/experiment=7]
- {
- data [read from file=experiment007-part1.csv]
- data [read from file=experiment007-part2.csv]
- data [read from file=experiment007-part3.csv]
- }
- scope [/data point/experiment=23, format=foo]
- {
- data [read from file=experiment023-part1.foo]
- data [read from file=experiment023-part2.foo]
- };
-\end{codeexample}
- %
-\end{datavisualizationoperation}
-
-\begin{datavisualizationoperation}{info}{\opt{\oarg{options}}\marg{code}}
- This command will execute normal \tikzname\ \meta{code} at the end of a
- data visualization. The \meta{options} are executed with the normal path
- |/tikz/|.
-
- The only difference between this command and just giving the \meta{code}
- directly following the data visualization is that inside the \meta{code}
- following an |info| command you still have access to the coordinate system
- of the data visualization. In sharp contrast, \tikzname\ code given after a
- data visualization can no longer access this coordinate system.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}[baseline]
- \datavisualization [ school book axes, visualize as line ]
- data [format=function] {
- var x : interval [-0.1*pi:2];
- func y = sin(\value x r);
- }
- info {
- \draw [red] (visualization cs: x={(.5*pi)}, y=1) circle [radius=1pt]
- node [above,font=\footnotesize] {extremal point};
- };
-\end{tikzpicture}
-\end{codeexample}
-
- As can be seen, inside a data visualization a special coordinate system is
- available:
-
- \begin{coordinatesystem}{visualization}
- As for other coordinate systems, the syntax is
- \declare{|(visualization cs:|\meta{list of attribute-value pairs}|)|}.
- The effect is the following: For each pair
- \meta{attribute}|=|\meta{value} in the \meta{list} the key
- |/data point/|\meta{attribute} is set to \meta{value}. Then, it is
- computed where the resulting data point ``would lie'' on the canvas
- (however, no data point is passed to the visualizers).
- \end{coordinatesystem}
-\end{datavisualizationoperation}
-
-\begin{datavisualizationoperation}{info'}{\opt{\oarg{options}}\marg{code}}
- This command works like |info|, only the \meta{code} will be executed just
- before the visualization is done. This allows you to draw things
- \emph{behind} the visualization.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\begin{tikzpicture}[baseline]
- \datavisualization [ school book axes, visualize as line ]
- data [format=function] {
- var x : interval [-0.1*pi:2];
- func y = sin(\value x r);
- }
- info' {
- \fill [red] (visualization cs: x={(.5*pi)}, y=1) circle [radius=2mm];
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{datavisualizationoperation}
-
-\label{section-dv-bounding-box}%
-\begin{predefinednode}{data visualization bounding box}
- This rectangle node stores a bounding box of the data visualization that is
- currently being constructed. This node can be useful inside |info| commands
- or when labels need to be added.
-\end{predefinednode}
-
-\begin{predefinednode}{data bounding box}
- This rectangle node is similar to |data visualization bounding box|, but it
- keeps track only of the actual data. The spaces needed for grid lines,
- ticks, axis labels, tick labels, and other all other information that is
- not part of the actual data is not part of this box.
-\end{predefinednode}
-
-
-\subsection{Advanced: Executing User Code During a Data Visualization}
-\label{section-dv-user-code}
-
-The following keys can be passed to the |\datavisualization| command and allow
-you to execute some code at some special time during the data visualization
-process. For details of the process and on which signals are emitted when, see
-Section~\ref{section-dv-backend}.
-
-\begin{key}{/tikz/data visualization/before survey=\meta{code}}
- The \meta{code} is passed to the |before survey| method of the data
- visualization object and then executed at the appropriate time (see
- Section~\ref{section-dv-backend} for details).
-
- The following commands work likewise:
-\end{key}
-%
-\begin{key}{/tikz/data visualization/at start survey=\meta{code}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/at end survey=\meta{code}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/after survey=\meta{code}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/before visualization=\meta{code}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/at start visualization=\meta{code}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/at end visualization=\meta{code}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/after visualization=\meta{code}}
-\end{key}
-
-
-\subsection{Advanced: Creating New Objects}
-
-You will need the following key only when you wish to create new rendering
-pipelines from scratch -- instead of modifying an existing pipeline as you
-would normally do. In the following it is assumed that you are familiar with
-the concepts of Section~\ref{section-dv-backend}.
-
-\begin{key}{/tikz/data visualization/new object=\meta{options}}
- This key serves two purposes:
- %
- \begin{enumerate}
- \item This method makes it easy to create a new object as part of the
- rendering pipeline, using \meta{options} to specify arguments
- rather that directly calling |\pgfoonew|. Since you have the full
- power of the keys mechanism at your disposal, it is easy, for
- instance, to control whether or not parameters to the constructor
- are expanded or not.
- \item The object is not created immediately, but only just before the
- visualization starts. This allows you to specify that an object
- must be created, but the parameter values of for its constructor
- may depend on keys that are not yet set. A typical application is
- the creating of an axis object: When you say |scientific axes|, the
- |new object| command is used internally to create two objects
- representing these axes. However, keys like |x={length=5cm}| can
- only \emph{later} be used to specify the parameters that need to be
- passed to the constructor of the objects.
- \end{enumerate}
-
- The following keys may be used inside the \meta{options}:
- %
- \begin{key}{/tikz/data visualization/class=\meta{class name}}
- The class of the to-be-created object.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/when=\meta{phase name} (initially before survey)}
- This key is used to specify when the object is to be created. As
- described above, the object is not created immediately, but at some
- time during the rendering process. You can specify any of the phases
- defined by the data visualization object, see
- Section~\ref{section-dv-backend} for details.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/store=\meta{key name}}
- If the \meta{key name} is not empty, once the object has been created,
- a handle to the object will be stored in \meta{key name}. If a handle
- is already stored in \meta{key name}, the object is not created twice.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/before creation=\meta{code}}
- This code is executed right before the object is finally created. It
- can be used to compute values that are then passed to the constructor.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/after creation=\meta{code}}
- This code is executed right after the object has just been created. A
- handle to the just-created object is available in |\tikzdvobj|.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/arg1=\meta{value}}
- The value to be passed as the first parameter to the constructor.
- Similarly, the keys |arg2| to |arg8| specify further parameters passed.
- Naturally, only as many arguments are passed as parameters are set.
- Here is an example:
- %
-\begin{codeexample}[code only]
-\tikzdatavisualizationset{
- new object={
- class = example class,
- arg1 = foo,
- arg2 = \bar
- }
-}
-\end{codeexample}
- %
- causes the following object creation code to be executed later on:
- %
-\begin{codeexample}[code only]
-\pgfoonew \tikzdvobj=new example class(foo,\bar)
-\end{codeexample}
- %
- Note that you key mechanisms like |.expand once| to pass the value of a
- macro instead of the macro itself:
- %
-\begin{codeexample}[code only]
-\tikzdatavisualizationset{
- new object={
- class = example class,
- arg1 = foo,
- arg2/.expand once = \bar
- }
-}
-\end{codeexample}
- %
- Now, if |\bar| is set to |This \emph{is} it.|\@ at the moment to object
- is created later on, the following object creation code is executed:
- %
-\begin{codeexample}[code only]
-\pgfoonew \tikzdvobj=new example class(foo,This \emph{is} it)
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/data visualization/arg1 from key=\meta{key}}
- Works like the |arg1|, only the value that is passed to the constructor
- is the current value of the specified \meta{key} at the moment when the
- object is created.
- %
-\begin{codeexample}[code only]
-\tikzdatavisualizationset{
- new object={
- class = example class,
- arg1 from key = /tikz/some key
- }
-}
-\tikzset{some key/.initial=foobar}
-\end{codeexample}
- %
- causes the following to be executed:
- %
-\begin{codeexample}[code only]
-\pgfoonew \tikzdvobj=new example class(foobar)
-\end{codeexample}
- %
- Naturally, the keys |arg2 from key| to |arg8 from key| are also
- provided.
- \end{key}
-
- \begin{key}{/tikz/data visualization/arg1 handle from key=\meta{key}}
- Works like the |arg1 from key|, only the key must store an object and
- instead of the object a handle to the object is passed to the
- constructor.
- \end{key}
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-polar.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-polar.tex
deleted file mode 100644
index bbba69dee4..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-polar.tex
+++ /dev/null
@@ -1,458 +0,0 @@
-% 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{Polar Axes}
-\label{section-dv-polar}
-
-\subsection{Overview}
-
-\begin{tikzlibrary}{datavisualization.polar}
- This library contains keys that allow you to create plots in a polar axis
- system is used.
-\end{tikzlibrary}
-
-In a \emph{polar axis system} two attributes are visualized by displacing a
-data point as follows: One attribute is used to compute a an angle (a
-direction) while a second attribute is used as a radius (a distance). The angle
-can be measured in degrees, radians, or can be scaled arbitrarily.
-%
-\begin{codeexample}[
- width=8.5cm,
- preamble={\usetikzlibrary{
- datavisualization.formats.functions,
- datavisualization.polar,
-}},
-]
-\tikz \datavisualization [
- scientific polar axes={0 to pi, clean},
- all axes=grid,
- style sheet=vary hue,
- legend=below
- ]
- [visualize as smooth line=sin,
- sin={label in legend={text=$1+\sin \alpha$}}]
- data [format=function] {
- var angle : interval [0:pi];
- func radius = sin(\value{angle}r) + 1;
- }
- [visualize as smooth line=cos,
- cos={label in legend={text=$1+\cos\alpha$}}]
- data [format=function] {
- var angle : interval [0:pi];
- func radius = cos(\value{angle}r) + 1;
- };
-\end{codeexample}
-
-Most of the time, in order to create a polar axis system, you will just use the
-|scientific polar axes| key, which takes a number of options that allow you to
-configure the axis system in greater detail. This key is documented in
-Section~\ref{section-dv-sci-polar-axes}. Internally, this key uses more low
-level keys which are documented in the en suite sections.
-
-It is worthwhile to note that the axes of a polar axis system are, still,
-normal axes of the data visualization system. In particular, all the
-configurations possible for, say, Cartesian axes also apply to the ``angle
-axis'' and the ``radius axis'' of a polar axis system. For instance, you can
-could make both axes logarithmic or style their ticks:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{
- datavisualization.formats.functions,
- datavisualization.polar,
-}}]
-\tikz[baseline] \datavisualization [
- scientific axes={clean},
- x axis={attribute=angle, ticks={minor steps between steps=4}},
- y axis={attribute=radius, ticks={some, style=red!80!black}},
- all axes=grid,
- visualize as smooth line=sin]
- data [format=function] {
- var t : interval [-3:3];
- func angle = exp(\value t);
- func radius = \value{t}*\value{t};
- };
-\qquad
-\tikz[baseline] \datavisualization [
- scientific polar axes={right half clockwise, clean},
- angle axis={logarithmic,
- ticks={
- minor steps between steps=8,
- major also at/.list={2,3,4,5,15,20}}},
- radius axis={ticks={some, style=red!80!black}},
- all axes=grid,
- visualize as smooth line=sin]
- data [format=function] {
- var t : interval [-3:3];
- func angle = exp(\value t);
- func radius = \value{t}*\value{t};
- };
-\end{codeexample}
-
-
-\subsection{Scientific Polar Axis System}
-\label{section-dv-sci-polar-axes}
-
-\begin{key}{/tikz/data visualization/scientific polar axes=\meta{options}}
- This key installs a polar axis system that can be used in a ``scientific''
- publication. Two axes are created called the |angle axis| and the
- |radius axis|. Unlike ``normal'' Cartesian axes, these axes do not point in
- a specific direction. Rather, the |radius axis| is used to map the values
- of one attribute to a distance from the origin while the |angle axis| is
- used to map the values of another attribute to a rotation angle.
-
- The \meta{options} will be executed with the path prefix
- %
-\begin{codeexample}[code only]
-/tikz/data visualization/scientific polar axes
-\end{codeexample}
- %
- The permissible keys are documented in the later subsections of this
- section.
-
- Let us start with the configuration of the radius axis since it is easier.
- Firstly, you should specify which attribute is linked to the radius. The
- default is |radius|, but you will typically wish to change this. As with
- any other axis, the |attribute| key is used to configure the axis, see
- Section~\ref{section-dv-axis-attribute} for details. You can also apply all
- other configurations to the radius axis like, say, |unit length| or
- |length| or |style|. Note, however, that the |logarithmic| key will not
- work with the radius axis for a |scientific polar axes| system since the
- attribute value zero is always placed at the center -- and for a
- logarithmic plot the value |0| cannot be mapped.
- %
-\begin{codeexample}[
- width=8.8cm,
- preamble={\usetikzlibrary{
- datavisualization.formats.functions,
- datavisualization.polar,
-}},
-]
-\tikz \datavisualization [
- scientific polar axes,
- radius axis={
- attribute=distance,
- ticks={step=5000},
- padding=1.5em,
- length=3cm,
- grid
- },
- visualize as smooth line]
-data [format=function] {
- var angle : interval [0:100];
- func distance = \value{angle}*\value{angle};
-};
-\end{codeexample}
-
- For the |angle axis|, you can also specify an attribute using the
- |attribute| key. However, for this axis the mapping of a value to an actual
- angle is a complicated process involving many considerations of how the
- polar axis system should be visualized. For this reason, there are a large
- number of predefined such mappings documented in
- Section~\ref{section-dv-angle-ranges}. Finally, as for a |scientific plot|,
- you can configure where the ticks should be shown using the keys
- |inner ticks|, |outer ticks|, and |clean|, documented below.
-\end{key}
-
-
-\subsubsection{Tick Placements}
-
-\begin{key}{/tikz/data visualization/scientific polar axes/outer ticks}
- This key, which is the default, causes ticks to be drawn ``outside'' the
- outer ``ring'' of the polar axes:
- %
-\begin{codeexample}[
- width=8.8cm,
- preamble={\usetikzlibrary{
- datavisualization.formats.functions,
- datavisualization.polar,
-}},
-]
-\tikz \datavisualization [
- scientific polar axes={outer ticks, 0 to 180},
- visualize as smooth line]
-data [format=function] {
- var angle : interval [0:100];
- func radius = \value{angle};
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/scientific polar axes/inner ticks}
- This key causes the ticks to be ``turned to the inside''. I do not
- recommend using this key.
- %
-\begin{codeexample}[
- width=8.8cm,
- preamble={\usetikzlibrary{
- datavisualization.formats.functions,
- datavisualization.polar,
-}},
-]
-\tikz \datavisualization [
- scientific polar axes={inner ticks, 0 to 180},
- visualize as smooth line]
-data [format=function] {
- var angle : interval [0:100];
- func radius = \value{angle};
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/scientific polar axes/clean}
- This key separates the area where the data is shown from the area where the
- ticks are shown. Usually, this is the best choice for the tick placement
- since it avoids a collision of data and explanations.
- %
-\begin{codeexample}[
- width=8.8cm,
- preamble={\usetikzlibrary{
- datavisualization.formats.functions,
- datavisualization.polar,
-}},
-]
-\tikz \datavisualization [
- scientific polar axes={clean, 0 to 180},
- visualize as smooth line]
-data [format=function] {
- var angle : interval [0:100];
- func radius = \value{angle};
-};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Angle Ranges}
-\label{section-dv-angle-ranges}
-
-Suppose you create a polar plot in which the radius values vary between, say,
-$567$ and $1234$. Then the normal axis scaling mechanisms can be used to
-compute a good scaling for the ``radius axis'': Place the value $1234$ at a
-distance of , say, $5\,\mathrm{cm}$ from the origin and place the value $0$ at
-the origin. Now, by comparison, suppose that the values of the angle axis's
-attribute ranged between, say, $10$ and $75.7$. In this case, we may wish the
-angles to be scaled so that the minimum value is horizontal and the maximum
-value is vertical. But we may also wish the a value of $0$ is horizontal and a
-value of $90$ is vertical.
-
-Since it is unclear which interpretation is the right one, you have to use an
-option to select which should happen. The applicable options fall into three
-categories:
-%
-\begin{itemize}
- \item Options that request the scaling to be done in such a way that the
- attribute is interpreted as a value in degrees and such that the
- minimum and maximum of the depicted range is a multiple of $90^\circ$.
- For instance, the option |0 to 180| causes the angle axis to range from
- $0^\circ$ to $180^\circ$, independently of the actual range of the
- values.
- \item Options that work as above, but use radians rather than degrees. An
- example is the option |0 to pi|.
- \item Options that map the minimum value in the data to a horizontal or
- vertical line and the maximum value to another such line. This is
- useful when the values neither directly correspond to degrees or
- radians. In this case, the angle axis may also be a logarithmic axis.
-\end{itemize}
-
-In addition to the above categories, all of the option documented in the
-following implicitly also select quadrants that are used to depict the data.
-For instance, the |0 to 90| key and also the |0 to pi half| key setup the polar
-axis system in such a way that only first (upper right) quadrant is used. No
-check is done whether the data fill actually lie in this quadrant -- if it does
-not, the data will ``bleed outside'' the range. Naturally, with a key like
-|0 to 360| or |0 to 2pi| this cannot happen.
-
-In order to save some space in this manual, in the following the different
-possible keys are only given in a table together with a small example for each
-key. The examples were created using the following code:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
-\tikz \datavisualization [
- scientific polar axes={
- clean,
- 0 to 90 % the option
- },
- angle axis={ticks={step=30}},
- radius axis={length=1cm, ticks={step=1}},
- visualize as scatter]
-data point [angle=20, radius=0.5]
-data point [angle=30, radius=1]
-data point [angle=40, radius=1.5];
-\end{codeexample}
-
-For the options on radians, the angle values have been replaced by |0.2|,
-|0.3|, and |0.4| and the stepping has been changed by setting |step=(pi/6)|.
-For the quadrant options, no stepping is set at all (it is computed
-automatically).
-
-\def\polarexample#1#2#3#4#5{%
- \texttt{#1}%
- \indexkey{/tikz/data visualization/scientific polar axes/#1}&
- \tikz [baseline]{\path(-2.25cm,0)(2.25cm,0); \datavisualization [
- scientific polar axes={clean, #1},
- angle axis={ticks={#2}},
- radius axis={length=1cm, ticks={step=1}},
- visualize as scatter
- ]
- data point [angle=#3, radius=0.5]
- data point [angle=#4, radius=1]
- data point [angle=#5, radius=1.5];
- \path ([yshift=-1em]current bounding box.south);
- }&
- \tikz [baseline]{\path(-2.25cm,0)(2.25cm,0); \datavisualization [
- scientific polar axes={outer ticks, #1},
- angle axis={ticks={#2}},
- radius axis={length=1cm, ticks={step=1}},
- visualize as scatter
- ]
- data point [angle=#3, radius=0.5]
- data point [angle=#4, radius=1]
- data point [angle=#5, radius=1.5];
- \path ([yshift=-1em]current bounding box.south);
- }
- \\
-}
-
-\begin{tabular}{lcc}
- \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
- \polarexample{0 to 90}{step=30}{20}{30}{40}
- \polarexample{-90 to 0}{step=30}{20}{30}{40}
- \polarexample{0 to 180}{step=30}{20}{30}{40}
- \polarexample{-90 to 90}{step=30}{20}{30}{40}
- \polarexample{0 to 360}{step=30}{20}{30}{40}
- \polarexample{-180 to 180}{step=30}{20}{30}{40}
-\end{tabular}
-
-\begin{tabular}{lcc}
- \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
- \polarexample{0 to pi half}{step=(pi/6)}{0.2}{0.3}{0.4}
- \polarexample{-pi half to 0}{step=(pi/6)}{0.2}{0.3}{0.4}
- \polarexample{0 to pi}{step=(pi/6)}{0.2}{0.3}{0.4}
- \polarexample{-pi half to pi half}{step=(pi/6)}{0.2}{0.3}{0.4}
- \polarexample{0 to 2pi}{step=(pi/6)}{0.2}{0.3}{0.4}
- \polarexample{-pi to pi}{step=(pi/6)}{0.2}{0.3}{0.4}
-\end{tabular}
-
-\begin{tabular}{lcc}
- \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
- \polarexample{quadrant}{}{20}{30}{40}
- \polarexample{quadrant clockwise}{}{20}{30}{40}
- \polarexample{fourth quadrant}{}{20}{30}{40}
- \polarexample{fourth quadrant clockwise}{}{20}{30}{40}
- \polarexample{upper half}{}{20}{30}{40}
- \polarexample{upper half clockwise}{}{20}{30}{40}
- \polarexample{lower half}{}{20}{30}{40}
- \polarexample{lower half clockwise}{}{20}{30}{40}
-\end{tabular}
-
-\begin{tabular}{lcc}
- \emph{Option} & \emph{With clean ticks} & \emph{With outer ticks} \\
- \polarexample{left half}{}{20}{30}{40}
- \polarexample{left half clockwise}{}{20}{30}{40}
- \polarexample{right half}{}{20}{30}{40}
- \polarexample{right half clockwise}{}{20}{30}{40}
-\end{tabular}
-
-
-\subsection{Advanced: Creating a New Polar Axis System}
-
-\begin{key}{/tikz/data visualization/new polar axes=|\char`\{|\meta{angle axis name}|\char`\}||\char`\{|\meta{radius axis name}|\char`\}|}
- This key actually creates two axes, whose names are give as parameters: An
- \emph{angle axis} and a \emph{radius axis}. These two axes work in concert
- in the following way: Suppose a data point has two attributes called
- |angle| and |radius| (these attribute names can be changed by changing the
- |attribute| of the \meta{angle axis name} or the \meta{radius axis name},
- respectively). These two attributes are then scaled as usual, resulting in
- two ``reasonable'' values $a$ (for the angle) and $r$ (for the radius).
- Then, the data point gets visualized (in principle, details will follow) at
- a position on the page that is at a distance of $r$ from the origin and at
- an angle of~$a$.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
-\tikz \datavisualization
- [new polar axes={angle axis}{radius axis},
- radius axis={length=2cm},
- visualize as scatter]
- data [format=named] {
- angle={0,20,...,160}, radius={0,...,5}
- };
-\end{codeexample}
- %
- In detail, the \meta{angle axis} keeps track of two vectors $v_0$ and
- $v_{90}$, each of which will usually have unit length (length |1pt|) and
- which point in two different directions. Given a radius $r$ (measured in
- \TeX\ |pt|s, so if the radius attribute |10pt|, then $r$ would be $10$) and
- an angle $a$, let $s$ be the sine of $a$ and let $c$ be the cosine of $a$,
- where $a$ is a number is degrees (so $s$ would be $1$ for $a = 90$). Then,
- the current page position is shifted by $c \cdot r$ times $v_0$ and,
- additionally, by $s \cdot r$ times $v_{90}$. This means that in the ``polar
- coordinate system'' $v_0$ is the unit vector along the ``$0^\circ$-axis''
- and $v_{90}$ is the unit vector along ``$90^\circ$-axis''. The values of
- $v_0$ and $v_{90}$ can be changed using the following key on the
- \meta{angle axis}:
- %
- \begin{key}{/tikz/data visualization/axis options/unit vectors=%
- |\char`\{|\meta{unit vector 0 degrees}|\char`\}\char`\{|\meta{unit vector 90 degrees}|\char`\}|
- (initially {\char`\{(1pt,0pt)\char`\}\char`\{(0pt,1pt)\char`\}})%
- }
- Both the \meta{unit vector 0 degrees} and the \meta{unit vector 90 degrees}
- are \tikzname\ coordinates:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
-\tikz \datavisualization
- [new polar axes={angle axis}{radius axis},
- radius axis={unit length=1cm},
- angle axis={unit vectors={(10:1pt)}{(60:1pt)}},
- visualize as scatter]
- data [format=named] {
- angle={0,90}, radius={0.25,0.5,...,2}
- };
-\end{codeexample}
- \end{key}
-\end{key}
-
-Once created, the |angle axis| can be scaled conveniently using the following
-keys:
-
-\begin{key}{/tikz/data visualization/axis options/degrees}
- When this key is passed to the angle axis of a polar axis system, it sets
- up the scaling so that a value of |360| on this axis corresponds to a
- complete circle.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
-\tikz \datavisualization
- [new polar axes={angle axis}{radius axis},
- radius axis={unit length=1cm},
- angle axis={degrees},
- visualize as scatter]
- data [format=named] {
- angle={10,90}, radius={0.25,0.5,...,2}
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/axis options/radians}
- In contrast to |degrees|, this option sets up things so that a value of
- |2*pi| on this axis corresponds to a complete circle.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.polar}}]
-\tikz \datavisualization
- [new polar axes={angle axis}{radius axis},
- radius axis={unit length=1cm},
- angle axis={radians},
- visualize as scatter]
- data [format=named] {
- angle={0,1.5}, radius={0.25,0.5,...,2}
- };
-\end{codeexample}
- %
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-stylesheets.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-stylesheets.tex
deleted file mode 100644
index 98680aa335..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-stylesheets.tex
+++ /dev/null
@@ -1,4033 +0,0 @@
-% 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{Style Sheets and Legends}
-\label{section-dv-style-sheets}
-
-\subsection{Overview}
-
-In many data visualizations, different sets of data need to be visualized in a
-single visualization. For instance, in a plot there might be a line for the
-sine of~$x$ and another line for the cosine of~$x$; in another visualization
-there might be a set of points representing data from a first experiment and
-another set of points representing data from a second experiment; and so on. In
-order to indicate to which data set a data point belongs, one might plot the
-curve of the sine in, say, black, and the curve of the cosine in red; we might
-plot the data from the fist experiment using stars and the data from the second
-experiment using circles; and so on. Finally, at some place in the
-visualization -- either inside the data or in a legend next to it -- the
-meaning of the colors or symbols need to be explained.
-
-Just as you would like \tikzname\ to map the data points automatically onto the
-axes, you will also typically wish \tikzname\ to choose for instance the
-coloring of the lines automatically for you. This is done using \emph{style
-sheets}. There are at least two good reasons why you should prefer style sheets
-over configuring the styling of each visualizer ``by hand'' using the |style|
-key:
-%
-\begin{enumerate}
- \item It is far more convenient to just say |style sheet=strong colors|
- than having to individually picking the different colors.
- \item The style sheets were chosen and constructed rather carefully.
-
- For instance, the |strong colors| style sheet does not pick colors like
- pure green or pure yellow, which have very low contrast with respect to
- a white background and which often lead to unintelligible graphics.
- Instead, opposing primary colors with maximum contrast on a white
- background were picked that are visually quite pleasing.
-
- Similarly, the different dashing style sheets are constructed in such a
- way that there are only few and small gaps in the dashing so that no
- data points get lost because the dashes are spaced too far apart. Also
- dashing patterns were chosen that have a maximum optical difference.
-
- As a final example, style sheets for plot marks are constructed in such
- a way that even when two plot marks lie directly on top of each other,
- they are still easily distinguishable.
-\end{enumerate}
-%
-The bottom line is that whenever possible, you should use one of the predefined
-style sheets rather than picking colors or dashings at random.
-
-
-\subsection{Concepts: Style Sheets}
-
-A \emph{style sheet} is a predefined list of styles such as a list of colors, a
-list of dashing pattern, a list of plot marks, or a combinations thereof. A
-style sheet can be \emph{attached} to a data point attribute. Then, the value
-of this attribute is used with data points to choose which style in the list
-should be chosen to visualize the data point.
-
-In most cases, there is just one attribute to which style sheets get attached:
-the |/data point/visualizer| attribute. The effect of attaching a style sheet
-to this attribute is that each visualizer is styled differently.
-
-For the following examples, let us first define a simple data set:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};
-\end{codeexample}
-
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};}]
-\tikz \datavisualization [
- school book axes, all axes={unit length=7.5mm},
- visualize as smooth line/.list={log, lin, squared, exp},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
-
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};}]
-\tikz \datavisualization [
- school book axes, all axes={unit length=7.5mm},
- visualize as smooth line/.list={log, lin, squared, exp},
- style sheet=vary dashing]
-data group {function classes};
-\end{codeexample}
-
-
-\subsection{Concepts: Legends}
-\label{section-dv-labels-in}
-
-A \emph{legend} is a box that is next to a data visualization (or inside it at
-some otherwise empty position) that contains a textual explanation of the
-different colors or styles used in a data visualization.
-
-Just as it is difficult to get colors and dashing patterns right ``by hand'',
-it is also difficult to get a legend right. For instance, when a small line is
-shown in the legend that represents the actual line in the data visualization,
-if the line is too short and the dashing is too large, it may be impossible to
-discern which dashing is actually meant. Similarly, when plot marks are shown
-on such a short line, using a simple straight line may make it hard to read the
-plot marks correctly.
-
-The data visualization engine makes some effort to make it easy to create
-high-quality legends. Additionally, it also offers ways of easily adding labels
-for visualizers directly inside the data visualization, which is even better
-than adding a legend, in general.
-%
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};}]
-\tikz \datavisualization [
- school book axes, all axes={unit length=7.5mm},
- x axis={label=$x$},
- visualize as smooth line/.list={log, lin, squared, exp},
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=vary dashing]
-data group {function classes};
-\end{codeexample}
-
-\begin{codeexample}[
- width=6.3cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};}]
-\tikz \datavisualization [
- school book axes,
- x axis={label=$x$},
- visualize as smooth line/.list={log, lin, squared, exp},
- every data set label/.append style={text colored},
- log= {pin in data={text'=$\log x$, when=y is -1}},
- lin= {pin in data={text=$x/2$, when=x is 2,
- pin length=1ex}},
- squared={pin in data={text=$x^2$, when=x is 1.1,
- pin angle=230}},
- exp= {label in data={text=$e^x$, when=x is -2}},
- style sheet=vary hue]
-data group {function classes};
-\end{codeexample}
-
-
-\subsection{Usage: Style Sheets}
-
-\subsubsection{Picking a Style Sheet}
-
-To use a style sheet, you need to \emph{attach} it to an attribute. You can
-attach multiple style sheets to an attribute and in this case all of these
-style sheets can influence the appearance of the data points.
-
-Most of the time, you will attach a style sheet to the |set| attribute. This
-has the effect that each different data set inside the same visualization is
-rendered in a different way. Since this use of style sheets is the most common,
-there is a special, easy-to-remember option for this:
-
-\begin{key}{/tikz/data visualization/style sheet=\meta{style sheet}}
- Adds the \meta{style sheet} to the list of style sheets attached to the
- |set| attribute.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- school book axes, all axes={unit length=7.5mm},
- visualize as smooth line/.list={log, lin, squared, exp},
- style sheet=vary thickness and dashing,
- style sheet=vary hue]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-
-While the |style sheet| key will attach a style sheet only to the |set|
-attribute, the following key handler can be used to attach a style sheet to an
-arbitrary attribute:
-
-\begin{handler}{{.style sheet}=\meta{style sheet}}
- Inside a data visualization you can use this key handler together with an
- attribute, that is, with a key having the path prefix |/data point|. For
- instance, in order to attach the \meta{style sheet} |strong colors| to the
- attribute |set|, you could write
- %
-\begin{codeexample}[code only]
-/data point/set/.style sheet=strong colors
-\end{codeexample}
- %
- Indeed, the |style sheet| key is just a shorthand for the above.
-
- The effect of attaching a style sheet is the following:
- %
- \begin{itemize}
- \item A new object is created that will monitor the attribute.
- \item Each time a special \emph{styling key} is emitted by the data
- visualization engine, this object will inspect the current value of
- the attribute to which it is attached.
- \item Depending on this value, one of the styles stored in the style
- sheet is chosen (how this works, exactly, will be explained in a
- moment).
- \item The chosen style is then locally applied.
- \end{itemize}
-
- In reality, things are a bit more complicated: If the attribute of the data
- point happens to have a subkey named in the same way as the value, then the
- value of is this subkey is used instead of the value itself. This allows
- you to ``rename'' a value.
-
- In a sense, a style sheet behaves much like a visualizer (see
- Section~\ref{section-dv-visualizers}): In accordance with the value of a
- certain attribute, the appearance of data points change. However, there are
- a few differences: First, the styling of a data point needs to be triggered
- explicitly and this triggering is not necessarily done for each data point
- individually, but only for a whole visualizer. Second, styles can be
- computed even when no data point is present. This is useful for instance in
- a legend since, here, a visual representation of a visualizer needs to be
- created independently of the actual data points.
-\end{handler}
-
-
-\subsubsection{Creating a New Style Sheet}
-
-Creating a style sheet works as follows: For each possible value that an
-attribute can attain we must specify a style. This is done by creating a style
-key for each such possible value with a special path prefix and setting this
-style key to the desired value. The special path prefix is
-|/pgf/data visualization/style sheets| followed by the name of the style sheet.
-
-As an example, suppose we wish to create a style sheet |test| that makes styled
-data points |red| when the attribute has value |foo| and |green| when the
-attribute has value |bar| and |dashed, blue| when the attribute is |foobar|. We
-could then write
-%
-\begin{codeexample}[code only]
-/pgf/data visualization/style sheets/test/foo/.style={red},
-/pgf/data visualization/style sheets/test/bar/.style={green},
-/pgf/data visualization/style sheets/test/foobar/.style={dashed, blue},
-\end{codeexample}
-
-We could then attach this style sheet to the attribute |code| as follows:
-%
-\begin{codeexample}[code only]
-/data point/code/.style sheet=test
-\end{codeexample}
-
-Then, when |/data point/code=foobar| holds when the styling signal is raised,
-the style |dashed, blue| will get executed.
-
-A natural question arises concerning the situation that the value of the
-attribute is not defined as a subkey of the style sheet. In this case, a
-special key gets executed:
-
-\begin{stylekey}{/pgf/data visualization/style sheets/\meta{style sheet}/default style=\meta{value}}
- This key gets during styling whenever
- |/pgf/data visualization/style sheet/|\meta{style sheet}|/|\meta{value} is
- not defined.
-\end{stylekey}
-
-Let us put all of this together in a real-life example. Suppose we wish to
-create a style sheet that makes the first data set |green|, the second |yellow|
-and the third one |red|. Further data sets should be, say, |black|. The
-attribute that we intend to style is the |set| attribute. For the moment, we
-assume that the data sets will be named |1|, |2|, |3|, and so on (instead of,
-say, |experiment 1| or |sin| or something more readable -- we will get rid of
-this restriction in a minute).
-
-We would now write:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-\pgfkeys{
- /pgf/data visualization/style sheets/traffic light/.cd,
- % All these styles have the above prefix.
- 1/.style={green!50!black},
- 2/.style={yellow!90!black},
- 3/.style={red!80!black},
- default style/.style={black}
-}
-\tikz \datavisualization [
- school book axes,
- visualize as line=1,
- visualize as line=2,
- visualize as line=3,
- style sheet=traffic light]
-data point [x=0, y=0, set=1]
-data point [x=2, y=2, set=1]
-data point [x=0, y=1, set=2]
-data point [x=2, y=1, set=2]
-data point [x=0.5, y=1.5, set=3]
-data point [x=2.25, y=1.75, set=3];
-\end{codeexample}
-
-In the above example, we have to name the visualizers |1|, |2|, |3| and so one
-since the value of the |set| attribute is used both assign data points to
-visualizers and also pick a style sheet. However, it would be much nicer if we
-could name any way we want. To achieve this, we use the special rule for style
-sheets that says that if there is a subkey of an attribute whose name is the
-same name as the value, then the value of this key is used instead. This
-slightly intimidating definition is much easier to understand when we have a
-look at an example:
-%
-\pgfkeys{
- /pgf/data visualization/style sheets/traffic light/.cd,
- % All these styles have the above prefix.
- 1/.style={green!50!black},
- 2/.style={yellow!90!black},
- 3/.style={red!80!black},
- default style/.style={black}
-}
-\begin{codeexample}[
- preamble={\usetikzlibrary{datavisualization}},
- pre={\pgfkeys{
- /pgf/data visualization/style sheets/traffic light/.cd,
- % All these styles have the above prefix.
- 1/.style={green!50!black},
- 2/.style={yellow!90!black},
- 3/.style={red!80!black},
- default style/.style={black}
-}},
-]
-% Definition of traffic light keys as above
-\begin{tikzpicture}
- \datavisualization data group {lines} = {
- data point [x=0, y=0, set=normal]
- data point [x=2, y=2, set=normal]
- data point [x=0, y=1, set=heated]
- data point [x=2, y=1, set=heated]
- data point [x=0.5, y=1.5, set=critical]
- data point [x=2.25, y=1.75, set=critical]
- };
- \datavisualization [
- school book axes,
- visualize as line=normal,
- visualize as line=heated,
- visualize as line=critical,
- /data point/set/normal/.initial=1,
- /data point/set/heated/.initial=2,
- /data point/set/critical/.initial=3,
- style sheet=traffic light]
- data group {lines};
-\end{tikzpicture}
-\end{codeexample}
-
-Now, it is a bit bothersome that we have to set all these |/data point/set/...|
-keys by hand. It turns out that this is not necessary: Each time a visualizer
-is created, a subkey of |/data point/set| with the name of the visualizer is
-created automatically and a number is stored that is increased for each new
-visualizer in a data visualization. This means that the three lines starting
-with |/data point| are inserted automatically for you, so they can be left out.
-However, you would need them for instance when you would like several different
-data sets to use the same styling:
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{datavisualization}},
- pre={\pgfkeys{
- /pgf/data visualization/style sheets/traffic light/.cd,
- % All these styles have the above prefix.
- 1/.style={green!50!black},
- 2/.style={yellow!90!black},
- 3/.style={red!80!black},
- default style/.style={black}
-}%
-\tikz \datavisualization data group {lines} = {
- data point [x=0, y=0, set=normal]
- data point [x=2, y=2, set=normal]
- data point [x=0, y=1, set=heated]
- data point [x=2, y=1, set=heated]
- data point [x=0.5, y=1.5, set=critical]
- data point [x=2.25, y=1.75, set=critical]
-};},
-]
-% Definition of traffic light keys as above
-\tikz \datavisualization [
- school book axes,
- visualize as line=normal,
- visualize as line=heated,
- visualize as line=critical,
- /data point/set/critical/.initial=1, % same styling as first set
- style sheet=traffic light]
-data group {lines};
-\end{codeexample}
-
-We can a command that slightly simplifies the definition of style sheets:
-
-\begin{command}{\pgfdvdeclarestylesheet\marg{name}\marg{keys}}
- This command executes the \meta{keys} with the path prefix
- |/pgf/data visualization/style sheets/|\penalty0\meta{name}. The above
- definition of the traffic light style sheet could be rewritten as follows:
- %
-\begin{codeexample}[code only]
-\pgfdvdeclarestylesheet{traffic light}{
- 1/.style={green!50!black},
- 2/.style={yellow!90!black},
- 3/.style={red!80!black},
- default style/.style={black}
-}
-\end{codeexample}
- %
-\end{command}
-
-As a final example, let us create a style sheet that changes the dashing
-pattern according to the value of the attribute. We do not need to define an
-large number of styles in this case, but can use the |default style| key to
-``calculate'' the correct dashing.
-
-\begin{codeexample}[
- preamble={\usetikzlibrary{datavisualization}},
- pre={\tikz \datavisualization data group {lines} = {
- data point [x=0, y=0, set=normal]
- data point [x=2, y=2, set=normal]
- data point [x=0, y=1, set=heated]
- data point [x=2, y=1, set=heated]
- data point [x=0.5, y=1.5, set=critical]
- data point [x=2.25, y=1.75, set=critical]
-};},
-]
-\pgfdvdeclarestylesheet{my dashings}{
- default style/.style={dash pattern={on #1pt off 1pt}}
-}
-\tikz \datavisualization [
- school book axes,
- visualize as line=normal,
- visualize as line=heated,
- visualize as line=critical,
- style sheet=my dashings]
-data group {lines};
-\end{codeexample}
-
-
-\subsubsection{Creating a New Color Style Sheet}
-
-Creating a style sheet that varies colors according to an attribute works the
-same way as creating a normal style sheet: Subkeys lies |1|, |2|, and so on use
-the |style| attribute to setup a color. However, instead of using the |color|
-attribute to set the color, you should use the |visualizer color| key to set
-the color:
-
-\begin{key}{/tikz/visualizer color=\meta{color}}
- This key is used to set the color |visualizer color| to \meta{color}. This
- color is used by visualizers to color the data they visualize, rather than
- the current ``standard color''. The reason for not using the normal current
- color is simply that it makes many internals of the data visualization
- engine a bit simpler.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{datavisualization}},
- pre={\tikz \datavisualization data group {lines} = {
- data point [x=0, y=0, set=normal]
- data point [x=2, y=2, set=normal]
- data point [x=0, y=1, set=heated]
- data point [x=2, y=1, set=heated]
- data point [x=0.5, y=1.5, set=critical]
- data point [x=2.25, y=1.75, set=critical]
-};},
-]
-\pgfdvdeclarestylesheet{my colors}
-{
- default style/.style={visualizer color=black},
- 1/.style={visualizer color=black},
- 2/.style={visualizer color=red!80!black},
- 3/.style={visualizer color=blue!80!black},
-}
-\tikz \datavisualization [
- school book axes,
- visualize as line=normal,
- visualize as line=heated,
- visualize as line=critical,
- style sheet=my colors]
-data group {lines};
-\end{codeexample}
- %
-\end{key}
-
-There is an additional command that makes it easy to define a style sheet based
-on a \emph{color series}. Color series are a concept from the |xcolor| package:
-The idea is that we start with a certain color for the first data set and then
-add a certain ``color offset'' for each next data point. Please consult the
-documentation of the |xcolor| package for details.
-
-\begin{command}{\tikzdvdeclarestylesheetcolorseries\marg{name}\marg{color model}\marg{initial color}\marg{step}}
- This command creates a new style sheet using |\pgfdvdeclarestylesheet|.
- This style sheet will only have a default style setup that maps numbers to
- the color in the color series starting with \meta{initial color} and having
- a stepping of \meta{step}. Note that when the value of the attribute is
- |1|, which it is the first data set, the \emph{second} color in the color
- series is used (since counting starts at |0| for color series). Thus, in
- general, you need to start the \meta{initial color} ``one early''.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{datavisualization}},
- pre={\tikz \datavisualization data group {lines} = {
- data point [x=0, y=0, set=normal]
- data point [x=2, y=2, set=normal]
- data point [x=0, y=1, set=heated]
- data point [x=2, y=1, set=heated]
- data point [x=0.5, y=1.5, set=critical]
- data point [x=2.25, y=1.75, set=critical]
-};},
-]
-\tikzdvdeclarestylesheetcolorseries{greens}{hsb}{0.3,1.3,0.8}{0,-.4,-.1}
-\tikz \datavisualization [
- school book axes,
- visualize as line=normal,
- visualize as line=heated,
- visualize as line=critical,
- style sheet=greens]
-data group {lines};
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Reference: Style Sheets for Lines}
-
-The following style sheets can be applied to visualizations that use the
-|visualize as line| and related keys. For the examples, the following style and
-data set are used:
-%
-\begin{codeexample}[code only]
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}
-\end{codeexample}
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}
-
-\begin{codeexample}[code only]
-\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};
-\end{codeexample}
-\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};
-
-\begin{stylesheet}{vary thickness}
- This style varies the thickness of lines. It should be used only when there
- are only two or three lines, and even then it is not particularly pleasing
- visually.
- %
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=vary thickness]
-data group {sin functions};
-\end{codeexample}
- %
-\end{stylesheet}
-
-\begin{stylesheet}{vary dashing}
- This style varies the dashing of lines. Although it is not particularly
- pleasing visually and although visualizations using this style sheet tend
- to look ``excited'' (but not necessarily ``exciting''), this style sheet is
- often the best choice when the visualization is to be printed in black and
- white.
- %
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=vary dashing]
-data group {sin functions};
-\end{codeexample}
- %
- As can be seen, there are only seven distinct dashing patterns. The eighth
- and further lines will use a solid line once more. You will then have to
- specify the dashing ``by hand'' using the |style| option together with the
- visualizer.
-\end{stylesheet}
-
-\begin{stylesheet}{vary thickness and dashing}
- This style alternates between varying the thickness and the dashing of
- lines. The difference to just using both the |vary thickness| and
- |vary dashing| is that too thick lines are avoided. Instead, this style
- creates clearly distinguishable line styles for many lines (up to 14) with
- a minimum of visual clutter. This style is the most useful for
- visualizations when many different lines (ten or more) should be printed in
- black and white.
- %
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=vary thickness
- and dashing]
-data group {sin functions};
-\end{codeexample}
- %
- For comparison, here is the must-less-than-satisfactory result of combining
- the two independent style sheets:
- %
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=vary thickness,
- style sheet=vary dashing]
-data group {sin functions};
-\end{codeexample}
- %
-\end{stylesheet}
-
-
-\subsection{Reference: Style Sheets for Scatter Plots}
-
-The following style sheets can be used both for scatter plots and also with
-lines. In the latter case, the marks are added to the lines.
-
-\begin{stylesheet}{cross marks}
- This style uses different crosses to distinguish between the data points of
- different data sets. The crosses were chosen in such a way that when two
- different cross marks lie at the same coordinate, their overall shape
- allows one to still uniquely determine which marks are on top of each
- other.
-
- This style supports only up to six different data sets and requires the
- |plotmarks| library.
- %
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as scatter/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=cross marks]
-data group {sin functions};
-\end{codeexample}
- %
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=cross marks]
-data group {sin functions};
-\end{codeexample}
- %
-\end{stylesheet}
-
-
-\subsection{Reference: Color Style Sheets}
-
-Color style sheets are very useful for creating visually pleasing data
-visualizations that contain multiple data sets. However, there are two things
-to keep in mind:
-%
-\begin{itemize}
- \item At some point, every data visualization is printed or photo copied in
- black and white by someone. In this case, data sets can often no longer
- be distinguished.
- \item A few people are color blind. They will not be able to distinguish
- between red and green lines (and some people are not even able to
- distinguish colors at all).
-\end{itemize}
-
-For these reasons, if there is any chance that the data visualization will be
-printed in black and white at some point, consider combining color style sheets
-with style sheets like |vary dashing| to make data sets distinguishable in all
-situations.
-
-\begin{stylesheet}{strong colors}
- This style sheets uses pure primary colors that can very easily be
- distinguished. Although not as visually pleasing as the |vary hue| style
- sheet, the visualizations are easier to read when this style sheet is used.
- Up to six different data sets are supported.
- %
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=strong colors]
-data group {sin functions};
-\end{codeexample}
- %
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=strong colors,
- style sheet=vary dashing]
-data group {sin functions};
-\end{codeexample}
- %
-\end{stylesheet}
-
-
-Unlike |strong colors|, the following style sheets support, in principle, an
-unlimited number of data set. In practice, as always, more than four or five
-data sets lead to nearly indistinguishable data sets.
-
-\begin{stylesheet}{vary hue}
- This style uses a different hue for each data set.
- %
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=vary hue]
-data group {sin functions};
-\end{codeexample}
- %
-\end{stylesheet}
-
-\begin{stylesheet}{shades of blue}
- As the name suggests, different shades of blue are used for different data
- sets.
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=shades of blue]
-data group {sin functions};
-\end{codeexample}
- %
-\end{stylesheet}
-
-\begin{stylesheet}{shades of red}
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=shades of red]
-data group {sin functions};
-\end{codeexample}
-\end{stylesheet}
-
-\begin{stylesheet}{gray scale}
- For once, this style sheet can also be used when the visualization is
- printed in black and white.
- %
-\begin{codeexample}[
- width=10cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- example visualization/.style={
- scientific axes=clean,
- y axis={ticks={style={
- /pgf/number format/fixed,
- /pgf/number format/fixed zerofill,
- /pgf/number format/precision=2}}},
- x axis={ticks={tick suffix=${}^\circ$}},
- 1={label in legend={text=$\frac{1}{6}\sin 11x$}},
- 2={label in legend={text=$\frac{1}{7}\sin 12x$}},
- 3={label in legend={text=$\frac{1}{8}\sin 13x$}},
- 4={label in legend={text=$\frac{1}{9}\sin 14x$}},
- 5={label in legend={text=$\frac{1}{10}\sin 15x$}},
- 6={label in legend={text=$\frac{1}{11}\sin 16x$}},
- 7={label in legend={text=$\frac{1}{12}\sin 17x$}},
- 8={label in legend={text=$\frac{1}{13}\sin 18x$}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list=
- {1,2,3,4,5,6,7,8},
- example visualization,
- style sheet=gray scale]
-data group {sin functions};
-\end{codeexample}
- %
-\end{stylesheet}
-
-
-\subsection{Usage: Labeling Data Sets Inside the Visualization}
-
-In a visualization that contains multiple data sets, it is often necessary to
-clearly point out which line or mark type corresponds to which data set. This
-can be done in the main text via a sentence like ``the normal data (black) lies
-clearly below the critical values (red)'', but it often a good idea to indicate
-data sets ideally directly inside the data visualization or directly next to it
-in a so-called legend.
-
-The data visualization engine has direct support both for indicating data sets
-directly inside the visualization and also for indicating them in a legend.
-
-The ``best'' way of indicating where a data set lies or which color is used for
-it is to put a label directly inside the data visualization. The reason this is
-the ``best'' way is that people do not have to match the legend entries against
-the data, let alone having to look up the meaning of line styles somewhere in
-the text. However, adding a label directly inside the visualization is also the
-most tricky way of indicating data sets since it is hard to compute good
-positions for the labels automatically and since there needs to be some empty
-space where the label can be put.
-
-
-\subsubsection{Placing a Label Next to a Data Set}
-
-The following key is used to create a label inside the data visualization for a
-data set:
-
-\begin{key}{/tikz/data visualization/visualizer options/label in data=\meta{options}}
- This key is passed to a visualizer that has previously been created using
- keys starting |visualize as ...|. It will create a label inside the data
- visualization ``next'' to the visualizer (the details are explained in a
- moment). You can use this key multiple times with a visualizer to create
- multiple labels at different points with different texts.
-
- The \meta{options} determine which text is shown and where it is shown.
- They are executed with the following path prefix:
- %
-\begin{codeexample}[code only]
-/tikz/data visualization/visualizer label options
-\end{codeexample}
-
- In order to configure which text is shown and where, use the following keys
- inside the \meta{options}:
-
- \begin{key}{/tikz/data visualization/visualizer label options/text=\meta{text}}
- This is the text that will be displayed next to the data. It will be to
- the ``left'' of the data, see the description below.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/visualizer label options/text'=\meta{text}}
- Like |text|, only the text will be to the ``right'' of the data.
- \end{key}
-
- The following keys are used to configure where the label will be shown.
- They use different strategies to specify one data point where the label
- will be anchored. The coordinate of this data point will be stored in
- |(label| |visualizer| |coordinate)|. Independently of the strategy, once
- the data point has been chosen, the coordinate of the next data point is
- stored in |(label| |visualizer| |coordinate')|. Then, a (conceptual) line
- is created from the first coordinate to the second and a node is placed at
- the beginning of this line to its ``left'' or, for the |text'| option, on
- its ``right''. More precisely, an automatic anchor is computed for a node
- placed implicitly on this line using the |auto| option or, for the |text'|
- option, using |auto,swap|.
-
- The node placed at the position computed in this way will have the
- \meta{text} set by the |text| or |text'| option and its styling is
- determined by the current |node style|.
-
- Let us now have a look at the different ways of determining the data point
- at which the label in anchored:
- %
- \begin{key}{/tikz/data visualization/visualizer label options/when=\meta{attribute}| is|\meta{number}}
- This key causes the value of the \meta{attribute} to be monitored in
- the stream of data points. The chosen is data point is the first data
- point where the \meta{attribute} is at least \meta{number} (if this
- never happens, the last data point is used).
- %
-\begin{codeexample}[
- width=6.3cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- school book axes,
- x axis={label=$x$},
- visualize as smooth line/.list={log, lin, squared, exp},
- log= {label in data={text'=$\log x$, when=y is -1,
- text colored}},
- lin= {label in data={text=$x/2$, when=x is 2}},
- squared={label in data={text=$x^2$, when=x is 1.1}},
- exp= {label in data={text=$e^x$, when=x is -2,
- text colored}},
- style sheet=vary hue]
-data group {function classes};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/data visualization/visualizer label options/index=\meta{number}}
- This key chooses the \meta{number}th data point belonging to the
- visualizer's data set.
- %
-\begin{codeexample}[
- width=6.3cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- school book axes,
- x axis={label=$x$},
- visualize as smooth line/.list={exp},
- exp= {label in data={text=$5$, index=5},
- label in data={text=$10$, index=10},
- label in data={text=$20$, index=20},
- style={mark=x}},
- style sheet=vary hue]
-data group {function classes};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/data visualization/visualizer label options/pos=\meta{fraction}}
- This key chooses the first data point belonging to the data set whose
- index is at least \meta{fraction} times the number of all data points
- in the data set.
- %
-\begin{codeexample}[
- width=6.3cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- school book axes,
- x axis={label=$x$},
- visualize as smooth line=exp,
- exp= {label in data={text=$.2$, pos=0.2},
- label in data={text=$.5$, pos=0.5},
- label in data={text=$.95$, pos=0.95},
- style={mark=x}},
- style sheet=vary hue]
-data group {function classes};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/data visualization/visualizer label options/auto}
- This key is executed automatically by default. It works like the |pos|
- option, where the \meta{fraction} is set to $(\meta{data set's
- index}-1/2)/\meta{number of data sets}$. For instance, when there are
- $10$ data sets, the fraction for the first one will be $5\%$, the
- fraction for the second will be $15\%$, for the third it will be
- $25\%$, ending with $95\%$ for the last one.
-
- The net effect of all this is that when there are several lines, labels
- will be placed at different positions along the lines with hopefully
- only little overlap.
- %
-\begin{codeexample}[
- width=6.3cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization [
- scientific axes=clean,
- visualize as smooth line/.list={linear, squared, cubed},
- linear ={label in data={text=$2x$}},
- squared={label in data={text=$x^2$}},
- cubed ={label in data={text=$x^3$}}]
-data [set=linear, format=function] {
- var x : interval [0:1.5];
- func y = 2*\value x;
-}
-data [set=squared, format=function] {
- var x : interval [0:1.5];
- func y = \value x * \value x;
-}
-data [set=cubed, format=function] {
- var x : interval [0:1.5];
- func y = \value x * \value x * \value x;
-};
-\end{codeexample}
- %
- As can be seen in the example, the result is not always satisfactory.
- In this case, the |pin in data| option might be preferable, see below.
- \end{key}
-
- The following keys allow you to style labels.
-
- \begin{key}{/tikz/data visualization/visualizer label options/node style=\meta{options}}
- Just passes the options to |/tikz/data visualization/node style|.
- \end{key}
- %
- \begin{key}{/tikz/data visualization/visualizer label options/text colored}
- Causes the |node style| to set the text color to |visualizer color|.
- The effect of this is that the label's text will have the same color as
- the data set to which it is attached.
- \end{key}
-
- \begin{stylekey}{/tikz/data visualization/every data set label}
- This style is executed with every label that represents a data set.
- Inside this style, use |node style| to change the appearance of nodes.
- This style has a default definition, usually you should just append
- things to this style.
- %
-\begin{codeexample}[
- width=6.3cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- school book axes,
- x axis={label=$x$},
- visualize as smooth line/.list={log, lin, squared, exp},
- every data set label/.append style={text colored},
- log= {label in data={text'=$\log x$, when=y is -1}},
- lin= {label in data={text=$x/2$,
- node style=sloped, when=x is 2}},
- squared={label in data={text=$x^2$, when=x is 1.1}},
- exp= {label in data={text=$e^x$,
- node style=sloped, when=x is -2}},
- style sheet=vary hue]
-data group {function classes};
-\end{codeexample}
- \end{stylekey}
-
- \begin{stylekey}{/tikz/data visualization/every label in data}
- Like |every data set label|, this key is also executed with labels.
- However, this key is executed after the style sheets have been
- executed, giving you a chance to overrule their styling.
- \end{stylekey}
-\end{key}
-
-
-\subsubsection{Connecting a Label to a Data Set via a Pin}
-
-\begin{key}{/tikz/data visualization/visualizer options/pin in data=\meta{options}}
- This key is a variant of the |label in data| key and takes the same
- options, plus two additional ones. The difference to |label in data| is
- that the label node is shown a bit removed from the data set, but connected
- to it via a small line (this is like the difference between the |label| and
- |pin| options).
- %
-\begin{codeexample}[
- width=6.3cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization [
- scientific axes=clean,
- visualize as smooth line/.list={linear, squared, cubed},
- linear ={pin in data={text=$2x$}},
- squared={pin in data={text=$x^2$}},
- cubed ={pin in data={text=$x^3$}}]
-data [set=linear, format=function] {
- var x : interval [0:1.5];
- func y = \value x;
-}
-data [set=squared, format=function] {
- var x : interval [0:1.5];
- func y = \value x * \value x;
-}
-data [set=cubed, format=function] {
- var x : interval [0:1.5];
- func y = \value x * \value x * \value x;
-};
-\end{codeexample}
- %
- The following keys can be used additionally:
- %
- \begin{key}{/tikz/data visualization/visualizer label options/pin angle=\meta{angle}}
- The position of the label of a |pin in data| is mainly computed in the
- same way as for a |label in data|. However, once the position has been
- computed, the label is shifted as follows:
- %
- \begin{itemize}
- \item When an \meta{angle} is specified using the present key, the
- shift is by the current value of |pin length| in the direction
- of \meta{angle}.
- \item When \meta{angle} is empty (which is the default), then the
- shift is also by the current value of |pin length|, but now in
- the direction that is orthogonal and to the left of the line
- between the coordinate of the data point and the coordinate of
- the next data point. When |text'| is used, the direction is to
- the right instead of the left.
- \end{itemize}
- \end{key}
-
- \begin{key}{/tikz/data visualization/visualizer label options/pin length=\meta{dimension}}
- See the description of |pin angle|.
- \end{key}
- %
-\begin{codeexample}[
- width=6.3cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- school book axes,
- x axis={label=$x$},
- visualize as smooth line/.list={log, lin, squared, exp},
- every data set label/.append style={text colored},
- log= {pin in data={text'=$\log x$, when=y is -1}},
- lin= {pin in data={text=$x/2$, when=x is 2,
- pin length=1ex}},
- squared={pin in data={text=$x^2$, when=x is 1.1,
- pin angle=230}},
- exp= {label in data={text=$e^x$, when=x is -2}},
- style sheet=vary hue]
-data group {function classes};
-\end{codeexample}
- \end{key}
-
-
-\subsection{Usage: Labeling Data Sets Inside a Legend}
-
-The ``classical'' way of indicating the style used for the different data sets
-inside a visualization is a \emph{legend}. It is a description next to or even
-inside the visualization that contains one line for each data set and displays
-an iconographic version of the data set next to some text labeling the data
-set. Note, however, that even though legend are quite common, also consider
-using a |label in data| or a |pin in data| instead.
-
-Creating a high-quality legend is by no means simple. A legend should not
-distract the reader, so aggressive borders should definitively be avoided. A
-legend should make it easy to match the actual styling of a data set (like,
-say, using a red, dashed line) to the ``iconographic'' representation of this
-styling. An example of what can go wrong here is using short lines to represent
-lines dashed in different way where the lines are so short that the differences
-in the dashing cannot be discerned. Another example is showing straight lines
-with plot marks on them where the plot marks are obscured by the horizontal
-line itself, while the plot marks are clearly visible in the actual
-visualization since no horizontal lines occur.
-
-The data visualization engine comes with a large set of options for creating
-and placing high-quality legends next or inside data visualizations.
-
-
-\subsubsection{Creating Legends and Legend Entries}
-
-A data visualization can be accompanied by one or more legends. In order to
-create a legend, the following key can be used (although, in practice, you will
-usually use the |legend| key instead, see below):
-
-\begin{key}{/tikz/data visualization/new legend=\meta{legend name} (default main legend)}
- This key is used to create a new legend named \meta{legend name}. The
- legend is empty by default and further options are needed to add entries to
- it. When the key is called a second time for the same \meta{legend name}
- nothing happens.
-
- When a legend is created, a new key is created that can subsequently be
- used to configure the legend:
- %
- \begin{key}{/tikz/data visualization/\meta{legend name}=\meta{options}}
- When this key is used, the \meta{options} are executed with the path
- prefix
- %
-\begin{codeexample}[code only]
-/tikz/data visualization/legend options
-\end{codeexample}
- %
- The different keys with this path prefix allow you to change the
- position where the legend is shown and how it is organised (for
- instance, whether legend entries are shown in a row or in a column or
- in a square).
-
- The different possible keys will be explained in the course of this
- section.
- \end{key}
-
- In the end, the legend is just a \tikzname\ node, a |matrix| node, to be
- precise. The following key is used to style this node:
-
- \begin{key}{/tikz/data visualization/legend options/matrix node style=\meta{options}}
- Adds the \meta{options} to the list of options that will be executed
- when the legend's node is created.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend={matrix node style={fill=black!25}},
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=vary dashing]
-data group {function classes};
-\end{codeexample}
- \end{key}
-
- The following style allows you to configure the default appearance of every
- newly created legend:
- %
- \begin{stylekey}{/tikz/data visualization/legend options/every new legend}
- This key defaults to |east outside, label style=text right|. This means
- that by default a legend is placed to the right of the data
- visualization and that in the individual legend entries the text is to
- the right of the data set visualization.
- \end{stylekey}
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes, x axis={label=$x$},
- visualize as smooth line/.list={log, lin, squared, exp},
- new legend={upper legend},
- new legend={lower legend},
- upper legend=above,
- lower legend=below,
- log= {label in legend={text=$\log x$, legend=upper legend}},
- lin= {label in legend={text=$x/2$, legend=upper legend}},
- squared={label in legend={text=$x^2$, legend=lower legend}},
- exp= {label in legend={text=$e^x$, legend=lower legend}},
- style sheet=vary dashing]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend=\meta{options}}
- This is a shorthand for
- |new legend=main legend, main legend=|\meta{options}. In other words, this
- key creates a new |main legend| and immediately passes the configuration
- \meta{options} to this legend.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes, x axis={label=$x$},
- visualize as smooth line/.list={log, lin, squared, exp},
- legend=below,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=vary dashing]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-
-As pointed out above, a legend is empty by default. In particular, the
-different data sets are not automatically inserted into the legend. Instead,
-the key |label in legend| must be used together with a data set:
-
-\begin{key}{/tikz/data visualization/visualizer options/label in legend=\meta{options}}
- This key is passed to a data set, similar to options like |pin in data| or
- |smooth line|. The \meta{options} are used to configure the following:
- %
- \begin{itemize}
- \item The legend in which the data set should be visualized.
- \item The text that is to be shown in the legend for the data set.
- \item The appearance of the legend entries.
- \end{itemize}
- %
- In detail, the \meta{options} are executed with the path prefix
- %
-\begin{codeexample}[code only]
-/tikz/data visualization/legend entry options
-\end{codeexample}
- %
- To configure in which legend the label should appear, use the
- following key:
- %
- \begin{key}{/tikz/data visualization/legend entry options/legend=\meta{name} (initially main legend)}
- Set this key to the name of a legend that has previously been created
- using |new legend|. The label will then be shown in this legend.
-
- In most cases, there is only one legend (namely |main legend|) and
- there is no need to set this key since it defaults to the main legend.
-
- Also note that the legend \meta{name} is automatically created if it
- nodes not yet exist.
- \end{key}
-
- \begin{key}{/tikz/data visualization/legend entry options/text=\meta{text}}
- Use this key to setup the \meta{text} that is shown as the label of the
- data set.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes, x axis={label=$x$},
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={pin in data ={text=$x^2$, pos=0.1}},
- exp= {label in data ={text=$e^x$}},
- style sheet=vary dashing]
-data group {function classes};
-\end{codeexample}
- \end{key}
-
- In addition to the two keys described above, there are further keys that
- are described in Section~\ref{section-dv-label-legend-entry-options}.
-\end{key}
-
-
-\subsubsection{Rows and Columns of Legend Entries}
-
-In a legend, the different legend entries are arranged in a matrix, which
-typically has only one row or one column. For the impatient reader: Say
-|rows=1| to get everything in a row, say |columns=1| to get everything in a
-single column, and skip the rest of this section.
-
-The more patient reader will appreciate that when there are very many different
-data sets in a single visualization, it may be necessary to use more than one
-row or column inside the legend. \tikzname\ comes with a rather powerful
-mechanism for distributing the multiple legend entries over the matrix.
-
-The first thing to decide is in which ``direction'' the entries should be
-inserted into the matrix. Suppose we have a $3 \times 3$ matrix and our entries
-are $a$, $b$, $c$, and so on. Then, one might place the $a$ in the upper left
-corner of the matrix, $b$ in the upper middle position, $c$ in the upper right
-position, and $d$ in the middle left position. This is a ``first right, then
-down'' strategy. A different strategy might be to place the $a$ in the upper
-left corner, but $b$ in the middle left position, $c$ in the lower left
-position, and $d$ then in the upper middle position. This is a ``first down,
-then right'' strategy. In certain situations it might even make sense to place
-$a$ in the lower right corner and then go ``first up, then left''.
-
-All of these strategies are supported by the |legend| command. You can
-configure which strategy is used using the following keys:
-
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}
-
-\begin{key}{/tikz/data visualization/legend options/down then right}
- Causes the legend entries to fill the legend matrix first downward and,
- once a column is full, the next column is begun to the right of the
- previous one. This is the default.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={down then right, columns=3}]
-data group {sin functions};
-\end{codeexample}
- %
- In the example, the |legend example| is the following style:
- %
-\begin{codeexample}[code only]
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/down then left}
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={down then left, columns=3}]
-data group {sin functions};
-\end{codeexample}
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/up then right}
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={up then right, columns=3}]
-data group {sin functions};
-\end{codeexample}
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/up then left}
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={up then left, columns=3}]
-data group {sin functions};
-\end{codeexample}
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/left then up}
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={left then up, columns=3}]
-data group {sin functions};
-\end{codeexample}
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/left then down}
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={left then down, columns=3}]
-data group {sin functions};
-\end{codeexample}
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/right then up}
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={right then up, columns=3}]
-data group {sin functions};
-\end{codeexample}
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/right then down}
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={right then down, columns=3}]
-data group {sin functions};
-\end{codeexample}
-\end{key}
-
-Having configured the directions in which the matrix is being filled, you must
-next setup the number of rows or columns that are to be shown. There are
-actually two different ways of doing so. The first way is to specify a maximum
-number of rows or columns. For instance, you might specify that there should be
-at most ten rows to a column and when there are more, a new column should be
-begun. This is achieved using the following keys:
-
-\begin{key}{/tikz/data visualization/legend options/max rows=\meta{number}}
- As the legend matrix is being filled, whenever the number of rows in the
- current column would exceed \meta{number}, a new column is started.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={max rows=3}]
-data group {sin functions};
-\end{codeexample}
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={max rows=4}]
-data group {sin functions};
-\end{codeexample}
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={max rows=5}]
-data group {sin functions};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/max columns=\meta{number}}
- This key works like |max rows|, only now the number of columns is
- monitored. Note that this strategy only really makes sense when the when
- you use this key with a strategy that first goes left or right and then up
- or down.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={right then down, max columns=2}]
-data group {sin functions};
-\end{codeexample}
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={right then down,max columns=3}]
-data group {sin functions};
-\end{codeexample}
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={right then down,max columns=4}]
-data group {sin functions};
-\end{codeexample}
- %
-\end{key}
-
-The second way of specifying the number of entries in a row or column is to
-specify an ``ideal number of rows or columns''. The idea is as follows: Suppose
-that we use the standard strategy and would like to have everything in two
-columns. Then if there are eight entries, the first four should go to the first
-column, while the next four should go to the second column. If we have 20
-entries, the first ten should go the first column and the next ten to the
-second, and so on. So, in general, the objective is to distribute the entries
-evenly so the this ``ideal number of columns'' is reached. Only when there are
-too few entries to achieve this or when the number of entries per column would
-exceed the |max rows| value, will the number of columns deviate from this ideal
-value.
-
-\begin{key}{/tikz/data visualization/legend options/ideal number of columns=\meta{number}}
- Specifies, that the entries should be split into \meta{number} different
- columns, whenever possible. However, when there would be more than the
- |max rows| value of rows per column, more columns than the ideal number are
- created.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={ideal number of columns=2}]
-data group {sin functions};
-\end{codeexample}
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={ideal number of columns=4}]
-data group {sin functions};
-\end{codeexample}
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={max rows=3,ideal number of columns=2}]
-data group {sin functions};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/rows=\meta{number}}
- Shorthand for |ideal number of rows=|\meta{number}.
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/ideal number of rows=\meta{number}}
- Works like |ideal number of columns|.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={ideal number of rows=2}]
-data group {sin functions};
-\end{codeexample}
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={ideal number of rows=4}]
-data group {sin functions};
-\end{codeexample}
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {sin functions} = {
- data [format=function] {
- var set : {1,...,8};
- var x : interval [0:50];
- func y = sin(\value x * (\value{set}+10))/(\value{set}+5);
- }
-};%
-\tikzdatavisualizationset {
- legend example/.style={
- scientific axes, all axes={length=1cm, ticks=none},
- 1={label in legend={text=1}},
- 2={label in legend={text=2}},
- 3={label in legend={text=3}},
- 4={label in legend={text=4}},
- 5={label in legend={text=5}},
- 6={label in legend={text=6}},
- 7={label in legend={text=7}},
- 8={label in legend={text=8}}
- }
-}},
-]
-\tikz \datavisualization [
- visualize as smooth line/.list={1,2,3,4,5,6,7,8},
- legend example, style sheet=vary hue,
- main legend={max columns=3,ideal number of rows=2}]
-data group {sin functions};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/columns=\meta{number}}
- Shorthand for |ideal number of columns=|\meta{number}.
-\end{key}
-
-
-\subsubsection{Legend Placement: The General Mechanism}
-
-A legend can either be placed next to the data visualization or inside the data
-visualization at some place where there are no data entries. Both approached
-have advantages: Placing the legend next to the visualization minimises the
-``cluttering'' by keeping all the extra information apart from the actual data,
-while placing the legend inside the visualization minimises the distance
-between the data sets and their explanations, making it easier for the eye to
-connect them.
-
-For both approaches there are options that make the placement easier, see
-Sections \ref{section-dv-legend-outside} and~\ref{section-dv-legend-inside},
-but these options internally just map to the following two options:
-
-\begin{key}{/tikz/data visualization/legend options/anchor=\meta{anchor}}
- The whole legend is a \tikzname-matrix internally. Thus, in particular, it
- is stored in a node, which has anchors. Like for any other node, when the
- node is shown, the node is shifted in such a way that the \meta{anchor} of
- the node lies at the current |at| position.
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/at=\meta{coordinate}}
- Configures the \meta{coordinate} at which the \meta{anchor} of the legend's
- node should lie.
-
- It may seem hard to predict a good \meta{coordinate} for a legend since,
- depending of the size of the axis, different positions need to the chosen
- for the legend. However, it turns out that one can often use the
- coordinates of the special nodes |data bounding box| and
- |data visualization bounding box|, documented in
- Section~\ref{section-dv-bounding-box}.
-
- As an example, let us put a legend to the right of the visualization, but
- so that the first entry starts at the top of the visualization:
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes, x axis={label=$x$},
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend={anchor=north west, at=
- (data visualization bounding box.north east)},
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=vary dashing]
-data group {function classes};
-\end{codeexample}
- %
- As can be seen, a bit of an additional shift might have been in order, but
- the result is otherwise quite satisfactory.
-\end{key}
-
-
-\subsubsection{Legend Placement: Outside to the Data Visualization}
-\label{section-dv-legend-outside}
-
-The following keys make it easy to place a legend outside the data
-visualization.
-
-\begin{key}{/tikz/data visualization/legend options/east outside}
- Placing the legend to the right of the data visualization is the default:
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend=east outside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
-
- \begin{key}{/tikz/data visualization/legend options/right}
- This is an easier-to-remember alias.
- \end{key}
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/north east outside}
- A variant, where the legend is to the right, but aligned with the northern
- end of the data visualization:
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend=north east outside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/south east outside}
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend=south east outside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/west outside}
- The legend is placed left. Note that the text also swaps its position.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend=west outside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
- \begin{key}{/tikz/data visualization/legend options/left}
- This is an easier-to-remember alias.
- \end{key}
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/north west outside}
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend=north west outside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/south west outside}
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend=south west outside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
-\end{key}
-
-
-\begin{key}{/tikz/data visualization/legend options/north outside}
- The legend is placed above the data. Note that the legend entries now for a
- row rather than a column.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend=north outside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
- \begin{key}{/tikz/data visualization/legend options/above}
- This is an easier-to-remember alias.
- \end{key}
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/south outside}
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend=south outside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
- \begin{key}{/tikz/data visualization/legend options/below}
- This is an easier-to-remember alias.
- \end{key}
-\end{key}
-
-
-\subsubsection{Legend Placement: Inside to the Data Visualization}
-\label{section-dv-legend-inside}
-
-There are two sets of options for placing a legend directly inside a data
-visualization: First, there are options for placing it inside, but next to some
-part of the border. Second, there are options for positioning it relative to a
-coordinate given by a certain data point.
-
-\begin{key}{/tikz/data visualization/legend options/south east inside}
- Puts the legend in the upper right corner of the data.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin},
- legend=south east inside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
-
- Note that the text is now a little smaller since there tends to be much
- less space inside the data visualization than next to it. Also, the
- legend's node is filled in white by default to ensures that the legend is
- clearly legible even in the presence of, say, a grid or data points behind
- it. This behavior is triggered by the following style key:
-
- \begin{stylekey}{/tikz/data visualization/legend options/every legend inside}
- Executed the keys |opaque| by default and sets the text size to the
- size of footnotes.
- \end{stylekey}
-\end{key}
-
-In order to further configure the default appearance of an inner legend, the
-following keys might be useful:
-
-\begin{key}{/tikz/data visualization/legend options/opaque=\meta{color} (default white)}
- When this key is used, the legend's node will be filled with the
- \meta{color} and its corners will be rounded. Additionally, the inner and
- outer separations will be set to sensible values.
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend options/transparent}
- Sets the filling of the legend node to |none|.
-\end{key}
-
-The following keys work much the same way as |south east inside|:
-
-\begin{key}{/tikz/data visualization/legend options/east inside}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend options/north east inside}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend options/south west inside}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend options/west inside}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend options/north west inside}
-\end{key}
-
-The keys |south inside| and |north inside| are a bit different: They use a row
-rather than a column for the legend entries:
-
-\begin{key}{/tikz/data visualization/legend options/south inside}
- Puts the legend in the upper right corner of the data. Note that the text
- is now a little smaller since there tends to be much less space inside the
- data visualization than next to it.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list={log, lin},
- legend=south inside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/north inside}
- As above.
-\end{key}
-
-The above keys do not always give you as fine a control as you may need over
-the placement of the legend. In such cases, the following keys may help (or you
-can revert to directly setting the |at| and the |anchor| keys):
-
-\begin{key}{/tikz/data visualization/legend options/at values=\meta{data point}}
- This key allows you to specify the desired center of the legend in terms of
- a data point. The \meta{data point} should be a list of comma-separated
- key--value pairs that specify a data point. The legend will then be
- centered at this data point.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list={log, lin},
- legend={at values={x=-1, y=2}},
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend options/right of=\meta{data point}}
- Works like |at values|, but the anchor is set to |west|:
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list={log, lin},
- legend={right of={x=-1, y=2}},
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-
-The following keys work similarly:
-%
-\begin{key}{/tikz/data visualization/legend options/above right of=\meta{data point}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend options/above of=\meta{data point}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend options/above left of=\meta{data point}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend options/left of=\meta{data point}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend options/below left of=\meta{data point}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend options/below of=\meta{data point}}
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend options/below right of=\meta{data point}}
-\end{key}
-
-
-\subsubsection{Legend Entries: General Styling}
-\label{section-dv-label-legend-entry-options}
-
-The entries in a legend can be styled in several ways:
-%
-\begin{itemize}
- \item You can configure the styling of the text node.
- \item You can configure the relative placement of the text node and the
- little picture depicting the data set's styling.
- \item You can configure how the data set's styling is depicted.
-\end{itemize}
-
-Before we have look at how each of these are configured, in detail, let us
-first have a look at the keys that allow us to save a set of such styles:
-
-\begin{stylekey}{/tikz/data visualization/every label in legend}
- This key is executed with every label in a legend. However, the options
- stored in this style are executed with the path prefix
- |/tikz/data visualization/legend entry options|. Thus, this key can use
- keys like |node style| to configure the styling of all text nodes:
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- every label in legend/.style={node style=
- {fill=red!30}},
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend=north east outside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$,
- node style={circle, draw=red}}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{key}{/tikz/data visualization/legend options/label style=\meta{options}}
- This key can be used with a legend. It will simply add the \meta{options}
- to the |every label in legend| style for the given legend.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend={label style={node style=draw}},
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$,
- node style={circle, draw=red}}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Legend Entries: Styling the Text Node}
-
-The appearance of the text nodes is easy to configure.
-
-\begin{key}{/tikz/data visualization/legend entry options/node style=\meta{options}}
- This key adds \meta{options} to the styling of the text nodes of the label.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend=north east outside,
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$,
- node style={circle, draw=red}}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend entry options/text colored}
- Causes the |node style| to set the text color to |visualizer color|. The
- effect of this is that the label's text will have the same color as the
- data set to which it is attached.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend={label style=text colored},
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Legend Entries: Text Placement}
-
-Three keys govern where the text will be placed relative to the data set style
-visualization.
-
-\begin{key}{/tikz/data visualization/legend entry options/text right}
- Placed the text node to the right of the data set style visualization. This
- is the default for most, but not all, legends.
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend entry options/text left}
- Placed the text node to the left of the data set style visualization.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend={label style=text left},
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-%
-\begin{key}{/tikz/data visualization/legend entry options/text only}
- Shows only the text nodes and no data set style visualization at all. This
- options only makes sense in conjunction with the |text colored| options,
- which is why this options is also selected implicitly.
- %
-\begin{codeexample}[
- width=8cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
- pre={\tikz \datavisualization data group {function classes} = {
- data [set=log, format=function] {
- var x : interval [0.2:2.5];
- func y = ln(\value x);
- }
- data [set=lin, format=function] {
- var x : interval [-2:2.5];
- func y = 0.5*\value x;
- }
- data [set=squared, format=function] {
- var x : interval [-1.5:1.5];
- func y = \value x*\value x;
- }
- data [set=exp, format=function] {
- var x : interval [-2.5:1];
- func y = exp(\value x);
- }
-};},
-]
-\tikz \datavisualization [
- scientific axes,
- visualize as smooth line/.list=
- {log, lin, squared, exp},
- legend={south east inside, rows=2,
- label style=text only},
- log= {label in legend={text=$\log x$}},
- lin= {label in legend={text=$x/2$}},
- squared={label in legend={text=$x^2$}},
- exp= {label in legend={text=$e^x$}},
- style sheet=strong colors]
-data group {function classes};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Advanced: Labels in Legends and Their Visualizers}
-\label{section-dv-legend-entries}
-
-The following explanations are important only for you if you intend to create a
-new visualizer and an accompanying label in legend visualizer; otherwise you
-can safely proceed with the next section.
-
-A legend entry consists not only of some explaining text, but, even more
-importantly, of a visual representation of the style used for the data points,
-created by a \emph{label in legend visualizer}. For instance, when data points
-are visualized as lines in different colors, the legend entry for the first
-line might consist of the text ``first experiment'' and a short line in black
-and the second entry might consist of ``failed experiment'' and a short line in
-red -- assuming, of course, that the style sheet makes the first line black and
-the second line blue. As another example, when data sets are visualized as
-clouds of plot marks, the texts in the legend would be accompanied by the plot
-marks used to visualize the data sets.
-
-For every visualizer, the \emph{label in legend visualizer} creates an
-appropriate visualization of the data set's styling. There may be more than one
-possible such label in legend visualizer that is appropriate, in which case
-options are used to choose between them.
-
-Let us start with the key for creating a new legend entry. This key gets called
-for instance by |label in legend|:
-
-\begin{key}{/tikz/data visualization/new legend entry=\meta{options}}
- This key will add a new entry to the legend that is identified by the
- \meta{options}. For this, the \meta{options} are executed once with the
- path prefix |/tikz/data visualization/legend entry options| and the
- resulting setting of the |legend| key is used to pick which legend the new
- entry should belong to. Then, the \meta{options} are stored away for the
- time being.
-
- Later, when the legend is created, the \meta{options} get executed once
- more. This time, however, the |legend| key is no longer important. Instead,
- the \meta{options} that setup keys like |text| or |visualizer in legend|
- now play a role.
-
- In detail, the following happens:
- %
- \begin{itemize}
- \item For the legend entry, a little cell picture is created in the
- matrix of the legend (see Section~\ref{section-tikz-cell-pictures}
- for details on cell pictures).
- \item Inside this picture, a node is created whose text is taken from
- the key
- %
-\begin{codeexample}[code only]
-/tikz/data visualization/legend entry options/text
-\end{codeexample}
- %
- \item Also inside the picture, the code stored in the following key
- gets executed:
- %
- \begin{key}{/tikz/data visualization/legend entry options/visualizer in legend}
- Set this key to some code that paints something in the cell
- picture. Typically, this will be a visual representation of the
- data set styling, but it could also be something different.
- %
-\begin{codeexample}[width=6cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- school book axes, visualize as line/.list={a,b},
- style sheet=vary dashing,
- a={label in legend={text=a}},
- new legend entry={
- text=spacer,
- visualizer in legend={\draw[solid] (0,0) circle[radius=2pt];}
- },
- b={label in legend={text=b}}]
-data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
-data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
-\end{codeexample}
- \end{key}
- \end{itemize}
- %
- The following styles are applied in the following order before the cell
- picture is filled:
- %
- \begin{enumerate}
- \item |/tikz/data visualization/every data set label| with path
- |/tikz/data visualization|
- \item |/tikz/data visualization/every label in legend| with path\\
- |/tikz/data visualization/legend entry options|.
- \item The \meta{options}.
- \item The code in the following key:
- %
- \begin{key}{/tikz/data visualization/legend entry options/setup}
- Some code to be executed at this point. Mostly, it is used to
- setup attributes for style sheets.
- \end{key}
- \item A styling signal is emitted.
- \item Only for the node: The current value of |node style|.
- \item Only for the visualizer in legend: The styling that has been
- accumulated by calls to the following key:
- %
- \begin{stylekey}{/tikz/data visualization/legend entry options/visualizer in legend style=\\\marg{options}}
- Calls to this key accumulate \meta{options} that will be
- executed with the path prefix |/tikz| at this point.
- \end{stylekey}
- \end{enumerate}
-\end{key}
-
-As indicated earlier, the |new legend entry| key is called by the
-|label in legend=|\meta{options} key internally. In this case, the following
-extra \meta{extra options} are passed to |new legend entry| key:
-%
-\begin{itemize}
- \item The styling of the visualizer.
- \item The |/tikz/data visualization/every label in legend| style.
- \item The |/tikz/every label| style with path |/tikz|.
- \item Setting |setup| to |/data point/set=|\meta{name of the visualizer}.
- \item The value of the |label legend options| that are stored in the
- visualizer. These options can be changed using the following key:
- %
- \begin{key}{/tikz/data visualization/visualizer options/label in legend options=\meta{options}}
- Use this key with a visualizer to configure the label in legend
- options. Typically, this key is used only internally by a
- visualizer upon its creating to set the \meta{options} to setup the
- |visualizer in legend| key.
- \end{key}
-\end{itemize}
-
-
-\subsubsection{Reference: Label in Legend Visualizers for Lines and Scatter Plots}
-
-Visualizers like |visualize as line| or |visualize as smooth line| use a label
-in legend visualizer that draws a short line to represent the data set inside
-the legend. However, this line needs not be a simple straight line, but can be
-a little curve or a small circle -- indeed, even the default line is not a
-simple straight line but rather a small zig-zag curve. To configure this line,
-the two keys are used, although you will only rarely use them directly, but
-rather use one of the predefined styles mentioned later on.
-
-Before we go into the glorious details of all of these keys, let us first have
-a look at the keys you are most likely to use in practice: The keys for
-globally reconfiguring the default label in legend visualizers:
-%
-\begin{stylekey}{/tikz/data visualization/legend entry options/default label in legend path}
- This style is set, by default, to |zig zag label in legend line|. It is
- installed by the styles |straight line|, |smooth line|, and |gap line|, so
- changing this style will change the appearance of lines in legends. The
- main other sensible option for this key is |straight label in legend line|.
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- school book axes, visualize as line/.list={a,b},
- style sheet=vary dashing,
- a={label in legend={text=a}}, b={label in legend={text=b}}]
-data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
-data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
-\end{codeexample}
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- school book axes, visualize as line/.list={a,b},
- legend entry options/default label in legend path/.style=
- straight label in legend line,
- style sheet=vary dashing,
- a={label in legend={text=a}}, b={label in legend={text=b}}]
-data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
-data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
-\end{codeexample}
- %
-\end{stylekey}
-%
-\begin{stylekey}{/tikz/data visualization/legend entry options/default label in legend closed path}
- This style is executed by |smooth cycle| and |straight cycle|. There are
- (currently) no other predefined sets of coordinates that can be used
- instead of the default value |circular label in legend line|.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/data visualization/legend entry options/default label in legend mark}
- This style is executed by |no lines| and, implicitly, by scatter plots. The
- default is to use |label in legend line one mark|. Another possible value
- is |label in legend line three marks|.
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- visualize as scatter/.list={a,b,c},
- style sheet=cross marks,
- legend entry options/default label in legend mark/.style=
- label in legend three marks,
- a={label in legend={text=example a}},
- b={label in legend={text=example b}},
- c={label in legend={text=example c}}];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{key}{/tikz/data visualization/legend entry options/label in legend line coordinates=\\\marg{list of coordinates}}
- This key takes a \meta{list of coordinates}, which are
- \tikzname-coordinates separated by commas like |(0,0),|\penalty0|(1,1)|.
- The effect of setting the key is the following: The label in legend
- visualizer used by, for instance, |visualize as line| will draw a path
- going through these points. When the line is drawn, the exact same style
- will be used as was used for the data set. For instance, if the
- |smooth line| key was used and also the |style=red| key, the line through
- the \meta{list of coordinates} will also be red and smooth. When the
- |straight cycle| key was used, the coordinates will also be connected by a
- cycle, and so on.
-
- When the line connecting the \meta{list of coordinates} is drawn, the
- coordinate system will have been shifted and transformed in such a way that
- |(0,0)| lies to the left of the text and at half the height of the
- character ``x''. This means that the right-most-point in the list should
- usually be |(0,0)| and all other $x$-coordinates should usually be
- negative. When the |text left| options is used, the coordinate system will
- have been flipped, so the \meta{list of coordinates} is independent of
- whether the text is to the right or to the left of the line.
-
- Let us now have a look at a first, simple example. We create a legend entry
- that is just a straight line, so it should start somewhere to the left of
- the origin at height $0$ and go to the origin:
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- school book axes, visualize as line/.list={a,b},
- style sheet=vary dashing,
- a={label in legend={text=a,
- label in legend line coordinates={(-1em,0), (0,0)}}},
- b={label in legend={text=b,
- label in legend line coordinates={(-2em,0), (0,0)}}}]
-data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
-data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
-\end{codeexample}
-
- Now let us make this a bit more fancy and useful by using shifted lines:
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- school book axes, visualize as line/.list={a,b},
- legend={up then right}, style sheet=vary dashing,
- a={label in legend={text=a,
- label in legend line coordinates={(-2em,-.25ex), (0,0)}}},
- b={label in legend={text=b,
- label in legend line coordinates={(-2em,.25ex), (0,0)}}}]
-data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
-data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
-\end{codeexample}
-
- In the final example, we use a little ``hat'' to represent lines:
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- school book axes, visualize as line/.list={a,b},
- legend={up then right}, style sheet=vary dashing,
- a={label in legend={text=a,
- label in legend line coordinates={
- (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}}},
- b={label in legend={text=b,
- label in legend line coordinates={
- (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)}}}]
-data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
-data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend entry options/label in legend mark coordinates=\\\marg{list of coordinates}}
- This key is similar to |label in legend line coordinates|, but now the
- \meta{list of coordinates} is used as the positions where plot marks are
- shown. Naturally, plot marks are only shown there if they are also shown by
- the visualizer in the actual data -- just like the line through the
- coordinates of the previous key is only shown when there is a line.
-
- The \meta{list of coordinates} may be the same as the one used for lines,
- but usually it is not. In general, it is better to have marks for instance
- not at the ends of the line.
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- school book axes, visualize as line/.list={a,b},
- legend={up then right},
- style sheet=vary dashing,
- style sheet=cross marks,
- a={label in legend={text=a,
- label in legend line coordinates={
- (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)},
- label in legend mark coordinates={
- (-1em,.2ex)}}},
- b={label in legend={text=b,
- label in legend line coordinates={
- (-2em,-.2ex), (-1em,.2ex), (0,-.2ex)},
- label in legend mark coordinates={
- (-2em,-.2ex), (0,-.2ex)}}}]
-data point [x=-1, y=-1, set=a] data point [x=1, y=0, set=a]
-data point [x=-1, y=1, set=b] data point [x=1, y=0.5, set=b];
-\end{codeexample}
- %
-\end{key}
-
-
-Naturally, you typically will not give coordinates explicitly for each label,
-but use one of the following styles:
-
-\begin{key}{/tikz/data visualization/legend entry options/straight label in legend line}
- Just gives a straight line and two plot marks.
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [visualize as line,
- line={style={mark=x}, label in legend={text=example,
- straight label in legend line}}];
-\end{codeexample}
- %
- This style might seem like a good idea to use in general, but it does have
- a huge drawback: Some commonly used plot marks will be impossible to
- distinguish -- even though there is no problem distinguishing them in a
- graph.
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [visualize as line/.list={a,b,c},
- legend entry options/default label in legend path/.style=
- straight label in legend line,
- a={style={mark=+}, label in legend={text=bad example a}},
- b={style={mark=-}, label in legend={text=bad example b}},
- c={style={mark=|}, label in legend={text=bad example c}}];
-\end{codeexample}
- %
- For this reason, this option is not the default, but rather the next one.
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend entry options/zig zag label in legend line}
- Uses a small up-down-up line as the label in legend visualizer. The two
- plot marks are at the extremal points of the line. It works pretty well in
- almost all situations and is the default.
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- visualize as line=a,
- visualize as smooth line/.list={b,c},
- a={style={mark=+}, label in legend={text=better example a}},
- b={style={mark=-}, label in legend={text=better example b}},
- c={style={mark=|}, label in legend={text=better example c}}];
-\end{codeexample}
- %
- Even though the above example shows that the marks are easier to
- distinguish than with a straight line, the chosen marks are still not
- optimal. This is the reason that the |cross marks| style uses different
- crosses:
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- visualize as line/.list={a,b},
- visualize as smooth line=c,
- style sheet=cross marks,
- a={label in legend={text=good example a}},
- b={label in legend={text=good example b}},
- c={gap line, label in legend={text=good example c}}];
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend entry options/circular label in legend line}
- This style is especially tailored to represent lines that are closed. It is
- automatically selected for instance by the |polygon| or the |smooth cycle|
- styles.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization [
- scientific axes={clean}, all axes={length=3cm},
- visualize as line/.list={a,b,c},
- a={polygon}, b={smooth cycle},
- style sheet=cross marks,
- a={label in legend={text=polygon}},
- b={label in legend={text=circle}},
- c={label in legend={text=line}}]
-data [format=function, set=a] {
- var t : {0,72,...,359};
- func x = cos(\value t);
- func y = sin(\value t);
-}
-data [format=function, set=b] {
- var t : [0:2*pi];
- func x = .8*cos(\value t r);
- func y = .8*sin(\value t r);
-}
-data point [x=-1, y=0.5, set=c]
-data point [x=1, y=0.25, set=c];
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend entry options/gap circular label in legend line}
- This style is especially tailored to for the |gap cycle| style and
- automatically selected by it:
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization [
- scientific axes={clean}, all axes={length=3cm},
- visualize as line/.list={a,b,c},
- a={gap cycle}, b={smooth cycle}, c={gap line},
- a={style={mark=*, mark size=0.5pt},
- label in legend={text=polygon}},
- b={label in legend={text=circle}},
- c={style={mark=*, mark size=0.5pt, mark options=red},
- label in legend={text=line}}]
-data [format=function, set=a] {
- var t : {0,72,...,359};
- func x = cos(\value t);
- func y = sin(\value t);
-}
-data [format=function, set=b] {
- var t : [0:352];
- func x = .8*cos(\value t);
- func y = .8*sin(\value t);
-}
-data point [x=-1, y=0.5, set=c]
-data point [x=1, y=0.25, set=c];
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend entry options/label in legend one mark}
- To be used with scatter plots, since no line is drawn. Just displays a
- single mark (this is the default with a scatter plot or when the |no line|
- is selected.
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [visualize as scatter/.list={a,b,c},
- style sheet=cross marks,
- a={label in legend={text=example a}},
- b={label in legend={text=example b}},
- c={label in legend={text=example c}}];
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/legend entry options/label in legend three marks}
- An alternative to the previous style, where several marks are shown.
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [visualize as scatter/.list={a,b,c},
- style sheet=cross marks,
- a={label in legend={text=example a, label in legend three marks}},
- b={label in legend={text=example b, label in legend three marks}},
- c={label in legend={text=example c, label in legend three marks}}];
-\end{codeexample}
- %
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-visualizers.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-visualizers.tex
deleted file mode 100644
index f1e5c06ed8..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-dv-visualizers.tex
+++ /dev/null
@@ -1,818 +0,0 @@
-% 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{Visualizers}
-\label{section-dv-visualizers}
-
-\subsection{Overview}
-
-In a data visualization a long stream of data points is \emph{visualized} using
-\emph{visualizers}. Recall that it is the job of the axis systems as described
-in Section~\ref{section-dv-axes} to determine \emph{where} data points are
-visualized. It is the job of the visualizers to determine \emph{how} they are
-visualized.
-
-The most basic and common visualizer is the \emph{line visualizer}. It simply
-connects subsequent data points by straight lines to indicate either that the
-points on these lines interpolate between the real data points or the straight
-lines are used to indicate the order in which the data points appear. A
-different, more ``conservative'' visualizer is the \emph{scatter visualizer} or
-\emph{mark visualizer}, which just places a small mark at each data point. Such
-a visualizer does not imply any interpolation or ordering between the data
-points.
-
-Visualizers may, however, also be more complicated. For instance, a visualizer
-used for a box plot could visualize a data point as a box with a median value,
-standard deviation, outliers, and other information; a rectangle visualizer
-might visualize data points as larger areas; a projection visualizer might
-visualize the projection of data points onto different axes; and so.
-
-Creating a new visualizer is not quite trivial since a new \pgfname\ class
-needs to be implemented. Fortunately, using visualizers is much simpler: For
-each kind of visualizer there is a key that allows you to create such a
-visualizer. You can then use further keys to configure the visualizer and to
-connect it to the data.
-
-In a data visualization multiple visualizers may exist at the same time. This
-happens in different situations:
-%
-\begin{itemize}
- \item A data visualization may contain several independent data sets that
- are to be visualized. There might be a line plot, for which a line
- visualizer is used, and also a scatter plot, for which a scatter
- visualizer would be used.
-
- In this case, for each data point only one visualizer will do anything.
- To achieve this, each data point has an attribute called |visualizer|
- which tells the visualizer objects whether they should ``react'' to the
- data point or not.
- \item A single data point might be visualized several times. For instance,
- a scatter visualizer might draw a mark at the data point's position on
- the page and a projection visualizer might draw, additionally, a mark
- at the projected position.
-\end{itemize}
-
-
-\subsection{Usage}
-
-\subsubsection{Using a Single Visualizer}
-
-The simplest scenario for using visualizers are data visualizations in which
-there is only a single data set that is visualized in one style. In this case,
-all that needs to be done in order to choose a visualizer is use one of the
-options starting with |visualize as ...| together with the |\datavisualization|
-command:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization}}]
-% Define a data set:
-\tikz \datavisualization data group {example} = {
-data {
- x, y
- 0, 0
- 0.5, 2
- 1, 2
- 1.5, 1.5
- 2, 0.5
-}};
-\tikz \datavisualization [school book axes, visualize as line] data group {example};
-\qquad
-\tikz \datavisualization [school book axes, visualize as smooth line] data group {example};
-\qquad
-\tikz \datavisualization [school book axes, visualize as scatter] data group {example};
-\end{codeexample}
-
-Methods for styling visualizers are discussed in
-Section~\ref{section-dv-visualizer-styling}.
-
-
-\subsubsection{Using Multiple Visualizers}
-
-A data visualization may contain multiple data groups and for each data set we
-might wish to use a different visualizer. In this case, we need some way of
-telling the data visualization engine to which visualizer should be used with
-the different data points.
-
-To solve this problem, you can \emph{name} a visualizer. The visualizer's name
-can then both be used to configure the visualizer and also to indicate that
-data points ``belong'' to the visualizer.
-
-Naming a visualizer is quite simple: The |visualize as ...| keys actually take
-a single parameter, which is the name of the visualizer. For instance, the
-following code creates three visualizers, named |sin|, |cos|, and |tan|:
-%
-\begin{codeexample}[code only]
-visualize as line=sin,
-visualize as line=cos,
-visualize as scatter=tan
-\end{codeexample}
-
-(When you just say |visualize as line| without providing a name, the name
-|line| is chosen as a default, for |visualize as scatter| the name |scatter| is
-the default and so.)
-
-In order to indicate which data points should be visualized by which of these
-visualizers, the following key is important:
-
-\begin{key}{/data point/set}
- A visualizer will only act on a data point when its name matches the value
- of this key. Initially, this key is set to the last visualizer created, so
- if there is only one, there is no need to set or worry about this key.
-\end{key}
-
-Since the |set| key has the path prefix |/data point|, it can be set like any
-other attribute of a data key:
-%
-\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization
- [scientific axes=clean,
- visualize as line=sin,
- visualize as line=cos,
- visualize as scatter=tan]
-data {
- x, y, set
- 0, 0, sin
- 1, 1, sin
- 2, 0, sin
- 3, -1, sin
- 4, 0, sin
- 0, 1, cos
- 1, 0, cos
- 0, 0, tan
- 1, 1, tan
- 2, 2, tan
- 3, 4, tan
- 2, -1, cos
- 3, 0, cos
- 4, 1, cos
-};
-\end{codeexample}
-
-As can be seen, the data points with the same |set| attribute do not need to be
-consecutive.
-
-The above method of specifying the visualizer works nicely, but in most cases
-it would be more natural to keep the |set| attribute out of the table. This is
-easy to achieve by using multiple |data| and using the following key:
-
-\begin{key}{/pgf/data/set=\meta{name}}
- Shorthand for |/data point/set=|\meta{name}.
- %
-\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization
- [scientific axes=clean,
- visualize as line=sin,
- visualize as line=cos]
-data [set=sin] {
- x, y
- 0, 0
- 1, 1
- 2, 0
- 3, -1
- 4, 0
-}
-data [set=cos] {
- x, y
- 0, 1
- 1, 0
- 2, -1
- 3, 0
- 4, 1
-};
-\end{codeexample}
- %
-\end{key}
-
-When you need to visualize several similar things in a single plot (like ten
-lines that all get visualized by |visualize as line|), it is somewhat
-cumbersome having to write this ten times. In this case you can shorten your
-code by making use of the |.list| key handler: When you add it to a key, the
-``value'' passed to the key is parsed as a list of values. The key is then
-executed once for each of these values:
-%
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization
- [scientific axes=clean,
- visualize as line/.list={sin, cos, tan}]
-data [set=sin, format=function] {
- var x : interval[0:3*pi];
- func y = sin(\value x r);
-}
-data [set=cos, format=function] {
- var x : interval[0:3*pi];
- func y = cos(\value x r);
-}
-data [set=tan, format=function] {
- var x : interval[0:pi/2.2];
- func y = tan(\value x r);
-};
-\end{codeexample}
-
-
-\subsubsection{Styling a Visualizer}
-\label{section-dv-visualizer-styling}
-
-In order to style a visualizer that has been created using for instance
-|visualize as line=|\meta{visualizer name}, you can use the following key:
-
-\begin{key}{/tikz/data visualization/\meta{visualizer name}=\meta{options}}
- For each visualizer, a key of the same name is created with the path prefix
- |/tikz/data visualization|. This key takes the \meta{options} and executes
- them with the path prefix
- %
-\begin{codeexample}[code only]
-/tikz/data visualization/visualizer options/
-\end{codeexample}
- %
- These options are then used to configure the appearance of the current
- visualizer. (This is quite similar to the way options are passed to an axis
- in order to configure the axis.) Possible options include |style|, but also
- |label in legend| and |label in data|. The latter two options are discussed
- in Section~\ref{section-dv-labels-in}, the first option below.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization
- [scientific axes=clean,
- visualize as smooth line/.list={sin, cos},
- sin={style=red},
- cos={style=blue}]
-data [set=sin, format=function] {
- var x : interval[0:3*pi];
- func y = sin(\value x r);
-}
-data [set=cos, format=function] {
- var x : interval[0:3*pi];
- func y = cos(\value x r);
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/visualizer options/style=\meta{options}}
- The \meta{options} given to this key should be normal \tikzname\ options.
- They will be executed when the visualizer is used.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization
- [scientific axes=clean,
- visualize as smooth line=sin,
- sin={style={red, densely dotted}},
- visualize as smooth line=cos,
- cos={style={mark=x}},
-]
-data [set=sin, format=function] {
- var x : interval[0:3*pi];
- func y = sin(\value x r);
-}
-data [set=cos, format=function] {
- var x : interval[0:3*pi];
- func y = cos(\value x r);
-};
-\end{codeexample}
-
- When you have multiple visualizers in a single data visualization, you can
- use the |style| option with each visualizer to configure their different
- appearances as in the above example. However, it is usually much better
- (and easier) to use a style sheet, see
- Section~\ref{section-dv-style-sheets}.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization
- [scientific axes={clean, end labels},
- x axis={label=$x$}, y axis={grid={major also at=0}},
- visualize as smooth line/.list={sin,cos,sin 2,cos 2},
- legend={below, rows=2},
- sin={label in legend={text=$\sin x$}},
- cos={label in legend={text=$\cos x$}},
- sin 2={label in legend={text=$\sin 2x$}},
- cos 2={label in legend={text=$\cos 2x$}},
- style sheet=strong colors]
-data [set=sin, format=function] {
- var x : interval[0:3*pi];
- func y = sin(\value x r);
-}
-data [set=cos, format=function] {
- var x : interval[0:3*pi];
- func y = cos(\value x r);
-}
-data [set=sin 2, format=function] {
- var x : interval[0:3*pi];
- func y = sin(2*\value x r);
-}
-data [set=cos 2, format=function] {
- var x : interval[0:3*pi];
- func y = cos(2*\value x r);
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/visualizer options/ignore style sheets}
- This option, which should be passed to a visualizer after its creation
- before another visualizer is created, causes style sheets \emph{not} to
- apply to the visualizer (but the |style| option will still have an effect).
- This allows you to create visualizers that are used for special purposes
- and that do not ``take part'' in the usual styling. For instance, a
- visualizer might be used internally to depict a regression line, even
- though the regression line itself should not participate in the usual
- styling by, say, dashing or different coloring.
-\end{key}
-
-In addition to the options passed to a visualizer via |style|, the following
-also gets executed when a visualizer is used:
-
-\begin{stylekey}{/tikz/data visualization/every visualizer}
- This style is used with every visualizer. Note that it should contain
- normal \tikzname\ keys.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization
- [scientific axes=clean,
- every visualizer/.style={dashed},
- visualize as smooth line]
-data [format=function] {
- var x : interval[0:3*pi];
- func y = sin(\value x r);
-};
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsection{Reference: Basic Visualizers}
-
-\subsubsection{Visualizing Data Points Using Lines}
-
-\begin{key}{/tikz/data visualizers/visualize as line=\meta{visualizer name} (default line)}
- Creates a new visualizer named \meta{visualizer name}. Basically, this
- visualizer connects all data points for which the |/data point/set|
- attribute equals \meta{visualizer name} by a line that is styled by the
- visualizer's style.
-
- In more detail, the following happens:
- %
- \begin{enumerate}
- \item A new object is created (of class |plot handler visualizer|) that
- is configured to collect the canvas positions of all data points
- whose |set| attribute equals \meta{visualizer name}.
- \item During the end of the data visualization, \pgfname's plotting
- mechanism (see Section~\ref{section-plots}) is used to plot the
- stream of recorded data points.
-
- This means that, in principle, all of the plot handlers available
- in \tikzname\ could be used for the visualization (such as the
- |smooth| handler). However, some plot handlers such as, say, the
- |xcomb| are unsuitable as plot handlers since they do not support
- the advanced axis handling done by the data visualization engine.
- Because of this (and also for other reasons), you cannot set the
- plot handler directly, but must use one of the options like
- |straight line|, |smooth line| and others, documented in a moment.
- \item Additionally, plot marks can be drawn at the collected data
- points. Here, all of the options available to \tikzname\ for
- drawing plot marks are available. To configure them, all options
- offered by \tikzname\ for configuring marks are available such as
- |mark repeat|:
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization
- [scientific axes=clean,
- visualize as line=my data,
- my data={style={mark=x, mark repeat=3}}]
-data [format=function] {
- var x : interval [0:pi] samples 10;
- func y = sin(\value x r);
-};
-\end{codeexample}
- \end{enumerate}
-
- The line visualizer also provides a method of dealing with gaps in a line.
- Take for instance the function $f(x) = \tan x$. When this function is
- plotted over the interval $[0,\pi]$, then the function will go to $\pm
- \infty$ at $\pi/2$. When we plot this, we might plot the function in the
- interval $[0,\frac{\pi}{2}-\epsilon]$ and then continue in the interval
- $[\frac{\pi}{2}+\epsilon,\pi]$. However, we do not want the point at
- coordinate $\bigl(\frac{\pi}{2}- \epsilon, \tan(\frac{\pi}{2}-
- \epsilon)\bigr)$ to be connected to the coordinate $\bigl(\frac{\pi}{2}+
- \epsilon, \tan(\frac{\pi}{2}+ \epsilon)\bigr)$ by a line. Rather, there
- should be a ``gap'' or a ``jump'' between these coordinates. To achieve
- this, the following key can be used:
- %
- \begin{key}{/data point/outlier=\meta{value} (default true, initially \normalfont empty)}
- When this key is set to anything non-empty value, a visualizer will
- consider this data point to be an ``outlier''. For a line visualizer
- this means that the point is not shown and that the current line ends
- at the previous data point and a new line starts at the next data
- point.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization
- [scientific axes=clean, x axis={grid={major at=(pi/2)}},
- visualize as smooth line]
-data [format=function] {
- var x : interval[0:pi/2-0.1];
- func y = tan(\value x r);
-}
-data point [outlier]
-data [format=function] {
- var x : interval[pi/2+0.1:pi];
- func y = tan(\value x r);
-};
-\end{codeexample}
- \end{key}
-\end{key}
-
-\begin{key}{/tikz/data visualizers/visualize as smooth line=\meta{visualizer name} (default line)}
- A shorthand |visualize as line=|\meta{visualizer name} followed
- \meta{visualizer name}|=smooth line|.
-\end{key}
-
-\begin{key}{/tikz/data visualization/visualizer options/straight line}
- Causes the data points to be connected by straight lines.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz [scale=.55] \datavisualization
- [scientific axes=clean, all axes={ticks=few},
- visualize as smooth line=my data, my data={straight line}]
-data [format=function] {
- var t : interval [0:4] samples 5;
- func x = cos(\value t r);
- func y = sin(\value t r);
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/visualizer options/straight cycle}
- Causes the data points to be connected by a polygon.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz [scale=.55] \datavisualization
- [scientific axes=clean, all axes={ticks=few},
- visualize as smooth line=my data, my data={straight cycle}]
-data [format=function] {
- var t : interval [0:4] samples 5;
- func x = cos(\value t r);
- func y = sin(\value t r);
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/visualizer options/polygon}
- This is an alias for |straight cycle|.
-\end{key}
-
-\begin{key}{/tikz/data visualization/visualizer options/smooth line}
- Causes the data points to be connected by a line that is smoothed at the
- joins:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz [scale=.55] \datavisualization
- [scientific axes=clean, all axes={ticks=few},
- visualize as smooth line=my data, my data={smooth line}]
-data [format=function] {
- var t : interval [0:4] samples 5;
- func x = cos(\value t r);
- func y = sin(\value t r);
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/visualizer options/smooth cycle}
- Causes the data points to be connected by a circular line that is smoothed
- at the joins:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz [scale=.55] \datavisualization
- [scientific axes=clean, all axes={ticks=few},
- visualize as smooth line=my data, my data={smooth cycle}]
-data [format=function] {
- var t : interval [0:4] samples 5;
- func x = cos(\value t r);
- func y = sin(\value t r);
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/visualizer options/gap line}
- This key causes the data points to be connected by lines that ``do not
- quite touch'' the data points. This is implemented by using the
- |\pgfplothandlergaplineto|, see Section~\ref{section-plot-gapped}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz [scale=.55] \datavisualization
- [scientific axes=clean, all axes={ticks=few},
- visualize as smooth line=my data, my data={gap line}]
-data [format=function] {
- var t : interval [0:4] samples 5;
- func x = cos(\value t r);
- func y = sin(\value t r);
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/visualizer options/gap cycle}
- Like |gapped line|, only with a cycle:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz [scale=.55] \datavisualization
- [scientific axes=clean, all axes={ticks=few},
- visualize as smooth line=my data, my data={gap cycle}]
-data [format=function] {
- var t : interval [0:4] samples 5;
- func x = cos(\value t r);
- func y = sin(\value t r);
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/data visualization/visualizer options/no lines}
- Suppresses the line. This option only makes sense when the |mark| option is
- used.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz [scale=.55] \datavisualization
- [scientific axes=clean, all axes={ticks=few},
- visualize as smooth line=my data, my data={no lines, style={mark=x}}]
-data [format=function] {
- var t : interval [0:4] samples 5;
- func x = cos(\value t r);
- func y = sin(\value t r);
-};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Visualizing Data Points Using Marks}
-
-\begin{key}{/tikz/data visualizers/visualize as scatter=\meta{visualizer name} (default scatter)}
- A shorthand |visualize as line=|\meta{visualizer name} followed
- \meta{visualizer name}|=no lines| and setting the |style| of the visualizer
- so that is will use |mark=x| (plus some size adjustments) to draw marks at
- the data points.
- %
-\begin{codeexample}[
- width=7cm,
- preamble={\usetikzlibrary{datavisualization.formats.functions}},
-]
-\tikz \datavisualization
- [scientific axes=clean,
- visualize as scatter]
-data [format=function] {
- var x : interval [0:pi] samples 10;
- func y = sin(\value x r);
-};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Advanced: Creating New Visualizers}
-
-Creating a new visualizer is a two-stage process that does, unfortunately,
-require in-depth knowledge of the data visualization backend:
-%
-\begin{enumerate}
- \item First, you need to create a new class using |\pgfooclass| whose
- instances react to the signal |visualize datapoint signal|. This
- requires detailed knowledge of the data visualization engine, see
- Section~\ref{section-dv-backend}.
- \item Second, you should provide keys on the \tikzname\ level for creating
- the necessary objects. These keys invoke the key |new visualizer|
- internally.
-\end{enumerate}
-
-\begin{key}{/tikz/data visualization/new visualizer=\marg{name}\marg{options}\marg{legend entry options}}
- This key configures a new visualizer named \meta{name}. This entails the
- following actions:
- %
- \begin{itemize}
- \item The key |/tikz/data visualization/|\meta{name} is created. As
- described earlier, this key can be used to pass for instance
- |style| options to the visualizer.
- \item The style key
- |/tikz/data visualization/visualizers/|\meta{name}|/styling| is
- created and made empty. This is the key in which the |style| key
- will store the options passed to the visualizer.
- \item The style key
- |/tikz/data visualization/visualizers/|\meta{name}|/label in legend options|
- is set to \meta{legend entry options}. These options are used to
- configure how the visualizer should be rendered in a legend, see
- Section~\ref{section-dv-legend-entries} for details.
- \item The key |/data point/set/|\meta{name} is set to a number that is
- increased for each visualizer in the current data visualization.
- This number is important for style sheets, see
- Section~\ref{section-dv-style-sheets}.
- \item The key |/data point/|\meta{name}|/execute at begin| is set to
- code that creates a |{scope}| that executes the following styles as
- options:
- %
- \begin{enumerate}
- \item The \meta{options} passed to the |new visualizer| key.
- \item The |every visualizer| style.
- \item The styling from the currently active style sheets, see
- Section~\ref{section-dv-style-sheets}.
- \item The styling stored in the |styling| key mentioned above.
- \end{enumerate}
- %
- \item The key |/data point/|\meta{name}|/execute at end| is set to code
- that will finish all paths that may have been created by the
- visualizer and closes the scope.
- \end{itemize}
-
- All of the above mean the following in practice:
- %
- \begin{itemize}
- \item Inside a new |visualize as ...| key, you pass the name of the
- to-be-created to |new visualizer| as the first parameter and any
- special default styling setup of the visualizer as the second
- parameter.
- \item The new |visualize as ...| key should also create a visualizer
- object using |new object|.
- \item When this object finally is about to create the actual
- visualization, it should surround the code by invoking the code
- stored in the |execute at begin| and the |execute at end| keys of
- the visualizer.
- \end{itemize}
-
- Everything else is usually taken care of by the |new visualizer| key
- automatically.
-\end{key}
-
-As an example, let us create a simple visualizer that creates a circle whose
-radius is dictated by the |radius| attribute. To keep things simple in this
-example, this attribute cannot be configured.
-
-First, we need the visualizer class. For this example I have boiled it down to
-a minimum:
-%
-\begin{codeexample}[code only]
-\pgfooclass{circle visualizer}
-{
- % Stores the name of the visualizer. This is needed for filtering and configuration
- \attribute name;
-
- % The constructor. Just setup the attribute.
- \method circle visualizer(#1) { \pgfooset{name}{#1} }
-
- % Connect to visualize signal.
- \method default connects() {
- \pgfoothis.get handle(\me)
- \pgfkeysvalueof{/pgf/data visualization/obj}.connect(\me,visualize,visualize datapoint signal)
- }
-
- % This method is invoked for each data point. It checks whether the data point belongs to the correct
- % visualizer and, if so, calls the macro \dovisualization to do the actual visualization.
- \method visualize() {
- \pgfdvfilterpassedtrue
- \pgfdvnamedvisualizerfilter
- \ifpgfdvfilterpassed
- \dovisualization
- \fi
- }
-}
-\end{codeexample}
-
-The |\dovisualization| method must now do the correct visualization.
-%
-\begin{codeexample}[code only]
-\def\dovisualization{
- \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at begin}
- \pgfpathcircle{\pgfpointdvdatapoint}{\pgfkeysvalueof{/data point/radius}}
- % \pgfusepath is done by |execute at end|
- \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at end}
-}
-\end{codeexample}
-
-Finally, we create a |visualize as| key:
-%
-\begin{codeexample}[code only]
-\tikzdatavisualizationset{
- visualize as circle/.style={
- new object={
- when=after survey,
- store=/tikz/data visualization/visualizers/#1,
- class=circle visualizer,
- arg1=#1
- },
- new visualizer={#1}{%
- color=visualizer color, % a color setup by the style sheet
- every path/.style={fill,draw}, % fill and draw the circle by default,
- }{}, % let's ignore legends in this example
- /data point/set=#1
- },
- visualize as circle/.default=circle
-}
-\end{codeexample}
-
-Now, let's see how this works:
-
-% TODOsp: codeexamples: This stuff is all needed for the next `codeexample`
-% but cannot be stored (simply) in `setup code`, `preample` or `pre`
-\pgfooclass{circle visualizer} {
- % Stores the name of the visualizer. This is needed for filtering
- % and configuration
- \attribute name;
-
- % The constructor. Just setup the attribute.
- \method circle visualizer(#1) { \pgfooset{name}{#1} }
-
- % Connect to visualize signal.
- \method default connects() {
- \pgfoothis.get handle(\me)
- \pgfkeysvalueof{/pgf/data visualization/obj}.connect(\me,visualize,visualize datapoint signal)
- }
-
- % This method is invoked for each data point. It checks whether the
- % data point belongs to the correct visualizer and, if so, calls the
- % macro \dovisualization to do the actual visualization.
- \method visualize() {
- \pgfdvfilterpassedtrue
- \pgfdvnamedvisualizerfilter
- \ifpgfdvfilterpassed
- \dovisualization
- \fi
- }
-}
-
-\def\dovisualization{
- \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at begin}
- \pgfpathcircle{\pgfpointdvdatapoint}{\pgfkeysvalueof{/data point/radius}}
- % \pgfusepath is done by |execute at end|
- \pgfkeysvalueof{/data point/\pgfoovalueof{name}/execute at end}
-}
-
-\tikzdatavisualizationset{
- visualize as circle/.style={
- new object={
- when=after survey,
- store=/tikz/data visualization/visualizers/#1,
- class=circle visualizer,
- arg1=#1
- },
- new visualizer={#1}{%
- color=visualizer color, % a color setup by the style sheet
- every path/.style={fill,draw}, % fill and draw the circle by default,
- }{},
- /data point/set=#1
- },
- visualize as circle/.default=circle
-}
-
-\begin{codeexample}[width=7cm,preamble={\usetikzlibrary{datavisualization}}]
-\tikz \datavisualization [
- scientific axes=clean,
- visualize as circle/.list={a, b, c},
- style sheet=strong colors]
-data [set=a] {
- x, y, radius
- 0, 0, 2pt
- 1, 1, 3pt
- 1, 2, 3pt
- 2, 0, 1pt
-}
-data [set=b] {
- x, y, radius
- 0.5, 0.5, 5pt
- 1, 1.5, 2pt
- 1, 2.5, 3pt
- 0, 2, 4pt
-}
-data [set=c] {
- x, y, radius
- 3, 2, 3pt
- 2.5, 0.5, 4pt
-};
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-algorithm-layer.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-algorithm-layer.tex
deleted file mode 100644
index c4f8c4ed6d..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-algorithm-layer.tex
+++ /dev/null
@@ -1,832 +0,0 @@
-% Copyright 2019 by Renée Ahrens, Olof Frahm, Jens Kluttig, Matthias Schulz, Stephan Schuster
-% Copyright 2019 by Till Tantau
-% Copyright 2019 by Jannis Pohlmann
-%
-% 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{The Algorithm Layer}
-\label{section-gd-algorithm-layer}
-
-\noindent{\emph{by Till Tantau}}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-
-\subsection{Overview}
-
-The present section is addressed at readers interested in implementing new
-graph drawing algorithms for the graph drawing system. Obviously, in order to
-do so, you need to have an algorithm in mind and also some programming skills;
-but fortunately only in the Lua programming language: Even though the graph
-drawing system was originally developed as an extension of \tikzname, is has
-been restructured so that the ``algorithm layer'' where you define algorithms
-is scrupulously separated from \tikzname. In particular, an algorithm declared
-and implemented on this layer can be used in with every ``display layers'', see
-Section~\ref{section-gd-display-layer}, without change. Nevertheless, in the
-following we will use the \tikzname\ display layer and syntax in our examples.
-
-Normally, new graph drawing algorithms can and must be implemented in the Lua
-programming language, which is a small, easy-to-learn (and quite beautiful)
-language integrated into current versions of \TeX. However, as explained in
-Section~\ref{section-algorithms-in-c}, you can also implement algorithms in C
-or C++ (and, possibly, in the future also in other languages), but this comes
-at a great cost concerning portability. In the present section, I assume that
-you are only interested in writing an algorithm using Lua.
-
-In the following, after a small ``hello world'' example of graph drawing and a
-discussion of technical details like how to name files so that \TeX\ will find
-them, we have a look at the main parts of the algorithm layer:
-%
-\begin{itemize}
- \item Section~\ref{section-gd-namespaces} gives and overview of the
- available namespaces and also of naming conventions used in the graph
- drawing system.
- \item Section~\ref{section-gd-gd-scope} explores what graph drawing scopes
- ``look like on the algorithm layer''. As the graph of a graph drawing
- scope is being parsed on the display layer, a lot of information is
- gathered: The nodes and edges of the graph are identified and the
- object-oriented model is built, but other information is also
- collected. For instance, a sequence of \emph{events} is created during
- the parsing process. As another example, numerous kinds of
- \emph{collections} may be identified by the parser. The parsed graph
- together with the event sequence and the collections are all gathered
- in a single table, called the \emph{scope table} of the current graph
- drawing scope. Algorithms can access this table to retrieve information
- that goes beyond the ``pure'' graph model.
-
- One entry in this table is of particular importance: The
- \emph{syntactic digraph.} While most graph drawing algorithms are not
- really interested in the ``details'' of how a graph was specified, for
- some algorithms it makes a big difference whether you write |a -> b| or
- |b <- a| in your specification of the graph. These algorithms can
- access the ``fine details'' of how the input graph was specified
- through the syntactic digraph; all other algorithms can access their
- |digraph| or |ugraph| fields and do not have to worry about the
- difference between |a -> b| and |b <- a|.
- \item Section~\ref{section-gd-models} explains the object-oriented model of
- graphs used throughout the graph drawing system. Graph drawing
- algorithms do not get the ``raw'' specification used by the user to
- specify a graph (like |{a -> {b,c}}| in the |graph| syntax). Instead,
- what a graph drawing algorithm sees is ``just'' a graph object that
- provides methods for accessing the vertices and arcs.
- \item Section~\ref{section-gd-transformations} explains how the information
- in the graph drawing scope is processed. One might expect that we
- simply run the algorithm selected by the user; however, things are more
- involved in practice. When the layout of a graph needs to be computed,
- only very few algorithms will actually be able to compute positions for
- the nodes of \emph{every} graph. For instance, most algorithms
- implicitly assume that the input graph is connected; algorithms for
- computing layouts for trees assume that the input is, well, a tree; and
- so on. For this reason, graph drawing algorithms will not actually need
- the original input graph as their input, but some \emph{transformed}
- version of it. Indeed, \emph{all} graph drawing algorithms are treated
- as graph transformations by the graph drawing engine.
-
- This section explains how transformations are chosen and which
- transformations are applied by default.
- \item Section~\ref{section-gd-interface-to-algorithms} documents the
- interface-to-algorithm class. This interface encapsulates all that an
- algorithm ``sees'' of the graph drawing system (apart from the classes
- in |model| and |lib|).
- \item Section~\ref{section-gd-examples} provides a number of complete
- examples that show how graph drawing algorithms can, actually, be
- implemented.
- \item Section~\ref{section-gd-libs} documents the different libraries
- functions that come with the graph drawing engine. For instance, there
- are library functions for computing the (path) distance of nodes in a
- graph; a parameter that is needed by some algorithms.
-\end{itemize}
-
-
-\subsection{Getting Started}
-
-In this section, a ``hello world'' example of a graph drawing algorithm is
-given, followed by an overview of the organization of the whole engine.
-
-
-\subsubsection{The Hello World of Graph Drawing}
-
-Let us start our tour of the algorithm layer with a ``hello world'' version of
-graph drawing: An algorithm that simply places all nodes of a graph in a circle
-of a fixed radius. Naturally, this is not a particularly impressive or
-intelligent graph drawing algorithm; but neither is the classical ``hello
-world''$\dots$\ Here is a minimal version of the needed code (this is not the
-typical way of formulating the code, but it is the shortest; we will have a
-look at the more standard and verbose way in a moment):
-%
-\begin{codeexample}[code only, tikz syntax=false]
-pgf.gd.interface.InterfaceToAlgorithms.declare {
- key = "very simple demo layout",
- algorithm = {
- run =
- function (self)
- local alpha = (2 * math.pi) / #self.ugraph.vertices
- for i,vertex in ipairs(self.ugraph.vertices) do
- vertex.pos.x = math.cos(i * alpha) * 25
- vertex.pos.y = math.sin(i * alpha) * 25
- end
- end
- }
-}
-\end{codeexample}
-\directlua{
-pgf.gd.interface.InterfaceToAlgorithms.declare {
- key = "very simple demo layout",
- algorithm = {
- run =
- function (self)
- local alpha = (2 * math.pi) / \luaescapestring{#}self.ugraph.vertices
- for i,vertex in ipairs(self.ugraph.vertices) do
- vertex.pos.x = math.cos(i * alpha) * 25
- vertex.pos.y = math.sin(i * alpha) * 25
- end
- end
- }
-}
-}
-
-This code \emph {declares} a new algorithm (|very simple demo layout|) and
-includes an implementation of the algorithm (through the |run| field of the
-|algorithm| field). When the |run| method is called, the |self| parameter will
-contain the to-be-drawn graph in its |ugraph| field. It is now the job of the
-code to modify the positions of the vertices in this graph (in the example,
-this is done by assigning values to |vertex.pos.x| and |vertex.pos.y|).
-
-In order to actually \emph{use} the algorithm, the above code first needs to be
-executed somehow. For \tikzname, one can just call |\directlua| on it or put it
-in a file and then use |\directlua| plus |require| (a better alternative) or
-you put it in a file like |simpledemo.lua| and use |\usegdlibrary{simpledemo}|
-(undoubtedly the ``best'' way). For another display layer, like a graphical
-editor, the code could also be executed through the use of |require|.
-
-Executing the code ``just'' declares the algorithm, this is what the |declare|
-function does. Inside some internal tables, the algorithm layer will store the
-fact that a |very simple demo layout| is now available. The algorithm layer
-will also communicate with the display layer through the binding layer to
-advertise this fact to the ``user''. In the case of \tikzname, this means that
-the option key |very simple demo layout| becomes available at this point and we
-can use it like this:
-%
-\begin{codeexample}[]
-\tikz [very simple demo layout]
- \graph { f -> c -> e -> a -> {b -> {c, d, f}, e -> b}};
-\end{codeexample}
-
-It turns out, that our little algorithm is already more powerful than one might
-expect. Consider the following example:
-%
-\begin{codeexample}[]
-\tikz [very simple demo layout, componentwise]
- \graph {
- 1 -> 2 ->[orient=right] 3 -> 1;
- a -- b --[orient=45] c -- d -- a;
- };
-\end{codeexample}
-
-Note that, in our algorithm, we ``just'' put all nodes on a circle around the
-origin. Nevertheless, the graph gets decomposed into two connected components,
-the components are rotated so that the edge from node |2| to node |3| goes from
-left to right and the edge from |b| to |c| goes up at an angle of $45^\circ$,
-and the components are placed next to each other so that some spacing is
-achieved.
-
-The ``magic'' that achieves all this behind the scenes is called ``graph
-transformations''. They will heavily pre- and postprocess the input and output
-of graph drawing algorithms to achieve the above results.
-
-Naturally, some algorithms may not wish their inputs and/or outputs to be
-``tampered'' with. An algorithm can easily configure which transformations
-should be applied, by passing appropriate options to |declare|.
-
-
-\subsubsection{Declaring an Algorithm}
-
-Let us now have a look at how one would ``really'' implement the example
-algorithm. First of all, we place our algorithm in a separate file called, say,
-|ExampleLayout.lua|. This way, by putting it in a separate file, all display
-layers can easily install the algorithm at runtime by saying
-|require "ExampleLayout"|.
-
-Next, the |declare| function is needed quite often, so it makes sense to create
-a short local name for it:
-%
-\begin{codeexample}[code only, tikz syntax=false]
--- This is the file ExampleLayout.lua
-local declare = require "pgf.gd.interface.InterfaceToAlgorithms".declare
-\end{codeexample}
-
-The |declare| function is the work-horse of the algorithm layer. It takes a
-table that contains at least a |key| field, which must be a unique string, and
-some other fields that specify in more detail what kind of key is declared.
-Once declared through a call of |declare|, the ``key'' can be used on the
-display layer.
-
-For declaring an algorithm, the table passed to |declare| must contain a field
-|algorithm|. This field, in turn, must (normally) be set to a table that will
-become the algorithm class. In the above example, our algorithm was so simple
-that we could place the whole definition of the class inside the call of
-|declare|, but normally the class is defined in more detail after the call to
-|declare|:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-local ExampleClass = {} -- A local variable holding the class table
-
-declare {
- key = "very simple demo layout",
- algorithm = ExampleClass
-}
-
-function ExampleClass:run ()
- local alpha = (2 * math.pi) / #self.ugraph.vertices
- ...
-end
-\end{codeexample}
-
-The effect of the |declare| will be that the table stored in |ExampleClass| is
-setup to form a class in the sense of object-oriented programming. In
-particular, a static |new| function is installed.
-
-Now, whenever the user uses the key |very simple demo layout| on a graph, at
-some point the graph drawing engine will create a new instance of the
-|ExampleClass| using |new| and will then call the |run| method of this class.
-The class can have any number of other methods, but |new| and |run| are the
-only ones directly called by the graph drawing system.
-
-
-\subsubsection{The Run Method}
-
-The |run| method of an algorithm classes lies at the heart of any graph drawing
-algorithm. This method will be called whenever a graph needs to be laid out.
-Upon this call, the |self| object will have some important fields set:
-%
-\begin{itemize}
- \item |ugraph| This stands for ``undirected graph'' and is the
- ``undirected'' version of the to-be-laid out graph. In this graph,
- whenever there is an arc between $u$ and $v$, there is also an arc
- between $v$ and $u$. It is obtained by considering the syntactic
- digraph and then ``forgetting'' about the actual direction of the
- edges.
-
- When you have set certain |preconditions| in your algorithm class, like
- |connected=true|, the |ugraph| will satisfy these conditions. In
- particular, the |ugraph| typically will not be the underlying
- undirected graph of the complete syntactic digraph, but rather of some
- part of it. The use of (sub)layouts will also modify the syntactic
- digraph is fancy ways.
-
- Refer to this graph whenever your algorithm is ``most comfortable''
- with an undirected graph, as is the case for instance for most
- force-base algorithms.
- \item |digraph| This stands for ``directed graph'' and is the
- ``semantically directed'' version of the to-be-laid out graph.
- Basically, when happens is that reverse edges in the syntactic digraph
- (an edge like |b <- a|) will yield an |Arc| from |a| to |b| in the
- |digraph| while they yield a |b| to |a| arc and edge in the syntactic
- digraph. Also, undirected edges like |a -- b| are replaced by directed
- edges in both directions between the vertices.
- \item |scope| The graph drawing scope.
- \item |layout| The layout object for this graph. This is a collection of
- kind |layout|.
-\end{itemize}
-
-
-\subsubsection{Loading Algorithms on Demand}
-
-In order to use the |very simple demo layout| on the display layer, |declare|
-must have been called for this key. However, we just saw that the |declare|
-function takes the actual class table as parameter and, thus, whenever an
-algorithm is declared, it is also completely loaded and compiled at this point.
-
-This is not always desirable. A user may wish to include a number of libraries
-in order to declare a large number of potentially useful algorithms, but will
-not actually use all of them. Indeed, at least for large, complex algorithms,
-it is preferable that the algorithm's code is loaded only when the algorithm is
-used for the first time.
-
-Such a ``loading of algorithms on demand'' is supported through the option of
-setting the |algorithm| field in a |declare| to a string. This string must now
-be the file name of a Lua file that contains the code of the actual algorithm.
-When the key is actually used for the first time, this file will be loaded. It
-must return a table that will be plugged into the |algorithm| field; so
-subsequent usages of the key will not load the file again.
-
-The net effect of all this is that you can place implementations of algorithms
-in files separate from interface files that just contain the |declare| commands
-for these algorithms. You will typically do this only for rather large
-algorithms.
-
-For our example, the code would look like this:
-%
-\begin{codeexample}[code only, tikz syntax=false]
--- File ExampleLayout.lua
-local declare = require "pgf.gd.interface.InterfaceToAlgorithms".declare
-declare {
- key = "very simple demo layout",
- algorithm = "ExampleLayoutImplementation"
-}
-\end{codeexample}
-
-\begin{codeexample}[code only, tikz syntax=false]
--- File ExampleLayoutImplementation.lua
-local ExampleClass = {}
-function ExampleClass:run ()
- local alpha = (2 * math.pi) / #self.ugraph.vertices
- ...
-end
-return ExampleClass
-\end{codeexample}
-
-
-\subsubsection{Declaring Options}
-
-Let us now make our example algorithm a bit more ``configurable''. For this, we
-use |declare| once more, but instead of the |algorithm| field, we use a |type|
-field. This tells the display layer that the key is not used to select an
-algorithm, but to configure ``something'' about the graph or about nodes or
-edges.
-
-In our example, we may wish to configure the radius of the graph. So, we
-introduce a |radius| key (actually, this key already exists, so we would not
-need to declare it, but let us do so anyway for example purposes):
-%
-\begin{codeexample}[code only, tikz syntax=false]
-declare {
- key = "radius",
- type = "length",
- initial = "25pt"
-}
-\end{codeexample}
-
-This tells the display layer that there is now an option called |radius|, that
-users set it to some ``length'', and that if it is not set at all, then the
-25pt should be used.
-
-To access what the user has specified for this key, an algorithm can access the
-|options| field of a graph, vertex, or arc at the key's name:
-%
-\begin{codeexample}[code only, tikz syntax=false]
- vertex.pos.x = math.cos(i * alpha) * vertex.options.radius
- vertex.pos.y = math.sin(i * alpha) * vertex.options.radius
-\end{codeexample}
-
-
-\subsubsection{Adding Inline Documentation}
-
-You should always document the keys you |declare|. For this, the |declare|
-function allows you to add three fields to its argument table:
-%
-\begin{itemize}
- \item |summary| This should be a string that succinctly summarizes the
- effect this key has. The idea is that this text will be shown as a
- ``tooltip'' in a graphical editor or will be printed out by a command
- line tool when a user requests help about the key. You can profit from
- using Lua's |[[| and |]]| syntax for specifying multi-line strings.
-
- Also, when the file containing the key is parsed for this manual, this
- text will be shown.
- \item |documentation| When present, this field contains a more extensive
- documentation of the key. It will also be shown in this manual, but
- typically not as a tool tip.
- \item |examples| This should either be a single string or an array of
- strings. Each string should be an example demonstrating how the key is
- used in \tikzname. They will all be included in the manual, each
- surrounded by a |codeexample| environment.
-\end{itemize}
-
-Let us augment our |radius| key with some documentation. The three dashes
-before the |declare| are only needed when the declaration is part of this
-manual and they will trigger an inclusion of the key in the manual.
-%
-\begin{codeexample}[code only, tikz syntax=false]
----
-declare {
- key = "radius",
- type = "length",
- initial = "25pt",
- summary = [[
- Specifies the radius of a circle on which the nodes are placed when
- the |very simple example layout| is used. Each vertex can have a
- different radius.
- ]],
- examples = [[
- \tikz \graph [very simple example layout, radius=2cm] {
- a -- b -- c -- d -- e;
- };
- ]]
-}
-\end{codeexample}
-
-As a courtesy, all of the strings given in the documentation can start and end
-with quotation marks, which will be removed. (This helps syntax highlighting
-with editors that do not recognize the |[[| to |]]| syntax.) Also, the
-indentation of the strings is removed (we compute the minimum number of leading
-spaces on any line and remove this many spaces from all lines).
-
-
-\subsubsection{Adding External Documentation}
-\label{section-gd-documentation-in}
-
-As an alternative to inlining documentation, you can also store the
-documentation of keys in a separate file that is loaded only when the
-documentation is actually accessed. Since this happens only rarely (for
-instance, not at all, when \tikzname\ is run, except for this manual), this
-will save time and space. Also, for C code, it is impractical to store
-multi-line documentation strings directly in the C file.
-
-In order to store documentation externally, instead of the |summary|,
-|documentation|, and |examples| keys, you provide the key |documentation_in|.
-The |documentation_in| key must be set to a string that is input using
-|require|.
-
-In detail, when someone tries to access the |summary|, |documentation|, or
-|examples| field of a key and these keys are not (yet) defined, the system
-checks whether the |documentation_in| key is set. If so, we apply |require| to
-the string stored in this field. The file loaded in this way can now setup the
-missing fields of the current key and, typically, also of all other keys
-defined in the same file as the current key. For this purpose, it is advisable
-to use the |pgf.gd.doc| class:
-
-\includeluadocumentationof{pgf.gd.doc}
-
-As a longer example, consider the following declarations:
-%
-\begin{codeexample}[code only, tikz syntax=false]
----
-declare {
- key = "very simple demo layout",
- algorithm = ExampleClass,
- documentation_in = "documentation_file"
-}
-
----
-declare {
- key = "radius",
- type = "length",
- initial = "25",
- documentation_in = "documentation_file"
-}
-\end{codeexample}
-
-The file |documentation_file.lua| would look like this:
-%
-\begin{codeexample}[code only, tikz syntax=false]
--- File documentation_file.lua
-local key = require 'pgf.gd.doc'.key
-local documentation = require 'pgf.gd.doc'.documentation
-local summary = require 'pgf.gd.doc'.summary
-local example = require 'pgf.gd.doc'.example
-
-key "very simple demo layout"
-documentation "This layout is a very simple layout that, ..."
-
-key "radius"
-summary "Specifies the radius of a circle on which the nodes are placed."
-documentation
-[[
-This key can be used together with |very simple example layout|. An
-important feature ist that...
-]]
-example
-[[
-\tikz \graph [very simple example layout, radius=2cm]
-{ a -- b -- c -- d -- e; };
-]]
-\end{codeexample}
-
-
-\subsection{Namespaces and File Names}
-\label{section-gd-namespaces}
-
-\subsubsection{Namespaces}
-
-All parts of the |graphdrawing| library reside in the Lua ``namespace''
-|pgf.gd|, which is itself a ``sub-namespace'' of |pgf|. For your own
-algorithms, you are free to place them in whatever namespace you like; only for
-the official distribution of \pgfname\ everything has been put into the correct
-namespace.
-
-Let us now have a more detailed look at these namespaces. A namespace is just a
-Lua table, and sub-namespaces are just subtables of namespace tables. Following
-the Java convention, namespaces are in lowercase letters. The following
-namespaces are part of the core of the graph drawing engine:
-%
-\begin{itemize}
- \item |pgf| This namespace is the main namespace of \pgfname. Other parts
- of \pgfname\ and \tikzname\ that also employ Lua should put an entry
- into this table. Since, currently, only the graph drawing engine
- adheres to this rule, this namespace is declared inside the graph
- drawing directory, but this will change.
-
- The |pgf| table is the \emph{only} entry into the global table of Lua
- generated by the graph drawing engine (or, \pgfname, for that matter).
- If you intend to extend the graph drawing engine, do not even
- \emph{think} of polluting the global namespace. You will be fined.
- \item |pgf.gd| This namespace is the main namespace of the graph drawing
- engine, including the object-oriented models of graphs and the layout
- pipeline. Algorithms that are part of the distribution are also inside
- this namespace, but if you write your own algorithms you do not need
- place them inside this namespace. (Indeed, you probably should not
- before they are made part of the official distribution.)
- \item |pgf.gd.interface| This namespace handles, on the one hand, the
- communication between the algorithm layer and the binding layer and, on
- the other hand, the communication between the display layer (\tikzname)
- and the binding layer.
- \item |pgf.gd.binding| So-called ``bindings'' between display layers and
- the graph drawing system reside in this namespace.
- \item |pgf.gd.lib| Numerous useful classes that ``make an algorithm's your
- life easier'' are collected in this namespace. Examples are a class for
- decomposing a graph into connected components or a class for computing
- the ideal distance between two sibling nodes in a tree, taking all
- sorts of rotations and separation parameters into account.
- \item |pgf.gd.model| This namespace contains all Lua classes that are part
- of the object-oriented model of graphs employed throughout the graph
- drawing engine. For readers familiar with the model--view--controller
- pattern: This is the namespace containing the model-part of this
- pattern.
- \item |pgf.gd.control| This namespace contains the ``control logic'' of the
- graph drawing system. It will transform graphs according to rules,
- disassemble layouts and sublayouts and will call the appropriate
- algorithms. For readers still familiar with the model--view--controller
- pattern: This is the namespace containing the control-part of this
- pattern.
- \item |pgf.gd.trees| This namespace contains classes that are useful for
- dealing with graphs that are trees. In particular, it contains a class
- for computing a spanning tree of an arbitrary connected graph; an
- operation that is an important preprocessing step for many algorithms.
-
- In addition to providing ``utility functions for trees'', the namespace
- \emph{also} includes actual algorithms for computing graph layouts like
- |pgf.gd.trees.ReingoldTilford1981|. It may seem to be a bit of an
- ``impurity'' that a namespace mixes utility classes and ``real''
- algorithms, but experience has shown that it is better to keep things
- together in this way.
-
- Concluding the analogy to the model--view--controller pattern, a graph
- drawing algorithm is, in a loose sense, the ``view'' part of the
- pattern.
- \item |pgf.gd.layered| This namespace provides classes and functions for
- ``layered'' layouts; the Sugiyama layout method being the most
- well-known one. Again, the namespace contains both algorithms to be
- used by a user and utility functions.
- \item |pgf.gd.force| Collects force-based algorithms and, again, also
- utility functions and classes.
- \item |pgf.gd.examples| Contains some example algorithms. They are
- \emph{not} intended to be used directly, rather they should serve as
- inspirations for readers wishing to implement their own algorithms.
-\end{itemize}
-
-There are further namespaces that also reside in the |pgf.gd| namespace, these
-namespaces are used to organize different graph drawing algorithms into
-categories.
-
-In Lua, similarly to Java, when a class |SomeClass| is part of, say, the
-namespace |pgf.gd.example|, it is customary to put the class's code in a file
-|SomeClass.lua| and then put this class in a directory |example|, that is a
-subdirectory of a directory |gd|, which is in turn a subdirectory of a
-directory |pgf|. When you write \texttt{require "pgf.gd.example.SomeClass"} the
-so-called \emph{loader} will turn this into a request for the file
-\texttt{pgf/gd/example/SomeClass.lua} (for Unix systems).
-
-
-\subsubsection{Defining and Using Namespaces and Classes}
-
-There are a number of rules concerning the structure and naming of namespaces
-as well as the naming of files. Let us start with the rules for naming
-namespaces, classes, and functions. They follow the ``Java convention'':
-%
-\begin{enumerate}
- \item A namespace is a short lowercase |word|.
- \item A function in a namespace is in
- |lowercase_with_underscores_between_words|.
- \item A class name is in |CamelCaseWithAnUppercaseFirstLetter|.
- \item A class method name is in |camelCaseWithALowercaseFirstLetter|.
-\end{enumerate}
-
-From Lua's point of view, every namespace and every class is just a table.
-However, since these tables will be loaded using Lua's |require| function, each
-namespace and each class must be placed inside a separate file (unless you
-modify the |package.loaded| table, but, then, you know what you are doing
-anyway). Inside such a file, you should first declare a local variable whose
-name is the name of the namespace or class that you intend to define and then
-assign a (possibly empty) table to this variable:
-%
-\begin{codeexample}[code only, tikz syntax=false]
--- File pgf.gd.example.SomeClass.lua:
-local SomeClass = {}
-\end{codeexample}
-%
-Next, you should add your class to the encompassing namespace. This is achieved
-as follows:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-require("pgf.gd.example").SomeClass = SomeClass
-\end{codeexample}
-%
-The reason this works is that the |require| will return the table that is the
-namespace |pgf.gd.example|. So, inside this namespace, the |SomeClass| field
-will be filled with the table stored in the local variable of the same name --
-which happens to be the table representing the class.
-
-At the end of the file, you must write
-%
-\begin{codeexample}[code only, tikz syntax=false]
-return SomeClass
-\end{codeexample}
-%
-This ensures that the table that is defined in this file gets stored by Lua in
-the right places. Note that you need and should not use Lua's |module| command.
-The reason is that this command has disappeared in the new version of Lua and
-that it is not really needed.
-
-Users of your class can import and use your class by writing:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-...
-local SomeClass = require "pgf.gd.examples.SomeClass"
-...
-\end{codeexample}
-
-
-\subsection{The Graph Drawing Scope}
-\label{section-gd-gd-scope}
-
-\includeluadocumentationof{pgf.gd.interface.Scope}
-
-
-\subsection{The Model Classes}
-\label{section-gd-models}
-
-All that a graph drawing algorithm will ``see'' of the graph specified by the
-user is a ``graph object''. Such an object is an object-oriented model of the
-user's graph that no longer encodes the specific way in which the user
-specified the graph; it only encodes which nodes and edges are present. For
-instance, the \tikzname\ graph specification
-%
-\begin{codeexample}[code only]
-graph { a -- {b, c} }
-\end{codeexample}
-%
-\noindent and the graph specification
-%
-\begin{codeexample}[code only]
-node (a) { a }
-child { node (b) {b} }
-child { node (c) {c} }
-\end{codeexample}
-%
-will generate exactly the same graph object.
-
-\begin{luanamespace}{pgf.gd.}{model}
- This namespace contains the classes modeling graphs, nodes, and edges.
- Also, the |Coordinate| class is found here, since coordinates are also part
- of the modeling.
-\end{luanamespace}
-
-
-\subsubsection{Directed Graphs (Digraphs)}
-
-Inside the graph drawing engine, the only model of a graph that is available
-treats graphs as
-%
-\begin{enumerate}
- \item directed (all edges have a designated head and a designated tail) and
- \item simple (there can be at most one edge between any pair of nodes).
-\end{enumerate}
-%
-These two properties may appear to be somewhat at odds with what users can
-specify as graphs and with what some graph drawing algorithms might expect as
-input. For instance, suppose a user writes
-%
-\begin{codeexample}[code only]
-graph { a -- b --[red] c, b --[green, bend right] c }
-\end{codeexample}
-%
-In this case, it seems that the input graph for a graph drawing algorithm
-should actually be an \emph{undirected} graph in which there are
-\emph{multiple} edges (namely $2$) between |b| and~|c|. Nevertheless, the graph
-drawing engine will turn the user's input a directed simple graph in ways
-described later. You do not need to worry that information gets lost during
-this process: The \emph{syntactic digraph,} which is available to graph drawing
-algorithms on request, stores all the information about which edges are present
-in the original input graph.
-
-The main reasons for only considering directed, simple graphs are speed and
-simplicity: The implementation of these graphs has been optimized so that all
-operations on these graphs have a guaranteed running time that is small in
-practice.
-
-\includeluadocumentationof{pgf.gd.model.Digraph}
-
-
-\subsubsection{Vertices}
-
-\includeluadocumentationof{pgf.gd.model.Vertex}
-
-
-\subsubsection{Arcs}
-\label{section-gd-arc-model}
-
-\includeluadocumentationof{pgf.gd.model.Arc}
-
-
-\subsubsection{Edges}
-
-\includeluadocumentationof{pgf.gd.model.Edge}
-
-
-\subsubsection{Collections}
-
-\includeluadocumentationof{pgf.gd.model.Collection}
-
-
-\subsubsection{Coordinates, Paths, and Transformations}
-
-\includeluadocumentationof{pgf.gd.model.Coordinate}
-\includeluadocumentationof{pgf.gd.model.Path}
-\includeluadocumentationof{pgf.gd.lib.Transform}
-
-
-\subsubsection{Options and Data Storages for Vertices, Arcs, and Digraphs}
-
-Many objects in the graph drawing system have an |options| table attached to
-them. These tables will contain the different kinds options specified by the
-user for the object. For efficiency reasons, many objects may share the same
-options table (since, more often than not, almost all objects have exactly the
-same |options| table). For this reason, you cannot store anything in an options
-table, indeed, you should never attempt to write anything into an options
-table. Instead, you should use a |Storage|.
-
-\includeluadocumentationof{pgf.gd.lib.Storage}
-
-
-\subsubsection{Events}
-
-\includeluadocumentationof{pgf.gd.lib.Event}
-
-
-\subsection{Graph Transformations}
-\label{section-gd-transformations}
-
-\subsubsection{The Layout Pipeline}
-
-\includeluadocumentationof{pgf.gd.control.LayoutPipeline}
-
-
-\subsubsection{Hints For Edge Routing}
-
-\includeluadocumentationof{pgf.gd.routing.Hints}
-
-
-\subsection{The Interface To Algorithms}
-\label{section-gd-interface-to-algorithms}
-
-\includeluadocumentationof{pgf.gd.interface.InterfaceToAlgorithms}
-
-
-\subsection{Examples of Implementations of Graph Drawing Algorithms}
-\label{section-gd-examples}
-
-\includeluadocumentationof{pgf.gd.examples.library}
-\includeluadocumentationof{pgf.gd.examples.SimpleDemo}
-\includeluadocumentationof{pgf.gd.examples.SimpleEdgeDemo}
-\includeluadocumentationof{pgf.gd.examples.SimpleHuffman}
-
-
-\subsection{Support Libraries}
-\label{section-gd-libs}
-
-The present section lists a number of general-purpose libraries that are used
-by different algorithms.
-
-\subsubsection{Basic Functions}
-
-\includeluadocumentationof{pgf}
-
-\includeluadocumentationof{pgf.gd.lib}
-
-
-\subsubsection{Lookup Tables}
-
-\includeluadocumentationof{pgf.gd.lib.LookupTable}
-
-
-\subsubsection{Computing Distances in Graphs}
-
-\emph{Still needs to be ported to digraph classes!}
-
-%\includeluadocumentationof{pgf.gd.lib.PathLengths}
-
-
-\subsubsection{Priority Queues}
-
-\includeluadocumentationof{pgf.gd.lib.PriorityQueue}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-algorithms-in-c.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-algorithms-in-c.tex
deleted file mode 100644
index 305752fc44..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-algorithms-in-c.tex
+++ /dev/null
@@ -1,864 +0,0 @@
-% Copyright 2018 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{Writing Graph Drawing Algorithms in C}
-\label{section-algorithms-in-c}
-
-\noindent{\emph{by Till Tantau}}
-\bigskip
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-In the present section we have a look at how graph drawing
-algorithms written in the C programming language (or in C++) can be
-used in the graph drawing framework.
-
-\begin{quote}
- \emph{Warning:} Graph drawing algorithms written in C can be incredibly
- fast if you use the facilities of C correctly. \emph{However,} C code is
- much less portable than Lua code in the sense that it has to be compiled
- for the specific platform used by the user and that it has to be linked
- dynamically during a run of the \TeX\ program. All of this in possible (and
- works, as demonstrated by the linking of the \textsc{ogdf} framework), but
- it is \emph{much} harder to get right than writing Lua code.
-
- Bottom line, \emph{you really should be using this method only if it is
- really necessary (namely, when Lua code is simply not fast enough).}
-\end{quote}
-
-In the following, I first explain how the link between \TeX\ and C code works,
-in general. Then, in the subsequent sections, we go over the different kinds of
-programming languages and frameworks for which there is direct support for such
-a link.
-
-
-\subsection{How C and \TeX\ Communicate}
-
-In order to use C code for graph drawing algorithms during a run of the \TeX\
-program, there is no need to build a new version of \TeX. Rather, it is
-possible that C code is linked into the \TeX\ executable at runtime. This is
-made possible by the fact that Lua (which part of Lua\TeX$\dots$) is able to
-link C libraries at runtime -- provided a strict regime of rules is adhered to:
-%
-\begin{enumerate}
- \item When you say |require| in Lua, it will normally look for a |.lua|
- file; but it will also try to find a |.so| file (a shared C library) as
- a fallback.
- \item If it finds such a shared library, Lua(\TeX) will try to link this
- library dynamically at runtime.
- \item Inside the library, there must be a function (called an entry point)
- with a special name (it must start with |luaopen_| and it must
- otherwise be the path and name of the library with slashes replaced by
- underscores).
- \item This function gets called by Lua, once. Its job is to setup the
- library so that it can be used by Lua. Mainly, this means that certain
- C functions get registered in such a way that Lua can call them.
- \item At this point, control returns to Lua and, now, certain functions
- have become available on the Lua layer that, when called, actually
- invoke the C code of our linked library.
-\end{enumerate}
-
-For each of the above points, there are some bells and whistles:
-%
-\begin{enumerate}
- \item Lua\TeX\ looks at slightly inconvenient places for shared libraries:
- By default, (currently, 2013) it looks in a |lib| subdirectory of the
- directory containing the Lua\TeX\ executable. The logic behind is that
- the shared libraries depend on the specific architecture of the
- executable. Thus, unlike normal Lua files, the library needs to be
- installed ``far away'' from the actual package of which it is part.
- \item Certain versions of Lua\TeX\ have a broken handling of filenames of
- libraries written in C. The TL2013 version of Lua\TeX, for instance,
- crashes when the filename of a shared library does not contain the
- complete path (while this works for normal file). Hopefully, this, too,
- will be fixed in future versions.
- \item On certain platforms, the support for dynamic linking against
- Lua\TeX\ is broken since the symbol table of the Lua library has been
- stripped away. Hopefully, this will be fixed soon; in the meantime, a
- highly fragile workaround is to link in another copy of the Lua
- library.
- \item The entry point that is called by Lua requires a certain signature
- (it takes a Lua state as its only parameter) and must return the number
- of objects it returns on the Lua stack.
- \item The registration process of C functions is somewhat tricky and
- changes from Lua version to Lua version.
- \item C functions that get called by Lua must follow all sorts of tricky
- rules in order to communicate with Lua correctly.
-\end{enumerate}
-
-Despite the above obstacles, one can use graph drawing algorithms written in C
-inside Lua, in principle, as follows: One loads an appropriately prepared and
-located C library using |require| and this library uses commands like |declare|
-to register its own functions into the graph drawing system so that when the
-|run| method is called, a C functions gets called instead.
-
-Unfortunately, the above approach is extremely tedious and error-prone and it
-is ``no fun'' to access Lua data structures (such as the syntactic digraph)
-from C. For this reason, I have written some libraries that encapsulate (as
-much as possible) of this communication between C and Lua. Indeed, when you use
-these libraries, you can focus entirely on the graph drawing issues and you
-will not even notice that your code ``is talking to Lua''. (Except for the name
-of the entry point, which is fixed to start with |luaopen_| and it is
-impossible to change this without disrupting a lot inside Lua's module system).
-
-There are libraries available for simplifying the communication between the
-graph drawing system and graph drawing algorithms written in
-%
-\begin{itemize}
- \item C, see Section~\ref{section-gd-c},
- \item C++, see Section~\ref{section-gd-c++},
- \item Open Graph Drawing Framework, see
- Section~\ref{section-gd-ogdf-interface}.
-\end{itemize}
-
-
-\subsection{Writing Graph Drawing Algorithms in C}
-\label{section-gd-c}
-
-\subsubsection{The Hello World of Graph Drawing in C}
-
-As our first example, as always, the ``hello world'' of graph drawing simply
-places nodes on a circle. For this, we implement a function |fast_hello_world|
-in a file |SimpleDemoC.c|. It starts as follows:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-#include <pgf/gd/interface/c/InterfaceFromC.h>
-#include <math.h>
-
-static void fast_hello_world (pgfgd_SyntacticDigraph* graph) {
- ...
-}
-\end{codeexample}
-
-As we can see, we first include a special header file of a rather small library
-that does all the hard work of translating between Lua and C for us
-(|InterfaceFromC|). These header files reside in the |c| subdirectory of the
-|pgf| package. Note that we do \emph{not} have to include the headers of the
-Lua library; indeed, you do not need access to the source of Lua to use the
-interface headers. As a side effect, we will, however, have to write
-|struct lua_State| instead of the more common |lua_State| once in our code,
-namely in the declaration of the entry point; but that is the only downside.
-
-The library |InterfaceFromC| declares the type |pgfgd_SyntacticDigraph|. In a
-moment, we will see that we can setup a key |fast simple demo layout| such that
-when this key is used on the display layer, the function |fast_hello_world|
-gets called. When it is called, the |graph| parameter will be a full
-representation of the to-be-laid-out graph. We can access the fields of the
-graph and even directly modify some of its fields (in particular, we can modify
-the |pos| fields of the vertices). Here is the complete code of the algorithm:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-static void fast_hello_world (pgfgd_SyntacticDigraph* graph) {
- double angle = 6.28318530718 / graph->vertices.length;
- double radius = pgfgd_tonumber(graph->options, "fast simple demo radius");
-
- int i;
- for (i = 0; i < graph->vertices.length; i++) {
- pgfgd_Vertex* v = graph->vertices.array[i];
- v->pos.x = cos(angle*i) * radius;
- v->pos.y = sin(angle*i) * radius;
- }
-}
-\end{codeexample}
-
-That is all that is needed; the C library will take care of both creating the
-|graph| object as all well as of deleting it and of copying back the computed
-values of the |pos| fields of the vertices.
-
-Our next task is to setup the key |fast simple demo layout|. We can (and must)
-also do this from C, using the following code:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-int luaopen_pgf_gd_examples_c_SimpleDemoC (struct lua_State *state) {
-
- pgfgd_Declaration* d = pgfgd_new_key ("fast simple demo layout");
- pgfgd_key_summary (d, "The C version of the hello world of graph drawing");
- pgfgd_key_algorithm (d, fast_hello_world);
- pgfgd_key_add_precondition (d, "connected");
- pgfgd_key_add_precondition (d, "tree");
- pgfgd_declare (state, d)
- pgfgd_free_key (d);
-\end{codeexample}
-
-The function |luaopen_pgf_gd_examples_c_SimpleDemoC| is the function that will
-be called by Lua (we will come to that). More important for us, at the moment,
-is the declaration of the key: We use |pgfgd_new_key| to create a declaration
-record and then fill the different fields using appropriate function calls. In
-particular, the call |pgfgd_key_algorithm| allows us to link the key with a
-particular C function. The |pgfgd_declare| will then pass the whole declaration
-back to Lua, so the effect of the above is essentially the same as if you had
-written in Lua:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-declare {
- key = "fast simple demo layout",
- summary = "The C version of the hello world of graph drawing",
- preconditions = {
- connected = true,
- tree = true,
- },
- algorithm = {
- run = -- something magic we cannot express in Lua
- }
-}
-\end{codeexample}
-
-In our algorithm, in addition to the above key, we also use the
-|fast simple demo radius| key, which is a simple length key. This key, too, can
-be declared on the C layer:
-%
-\begin{codeexample}[code only, tikz syntax=false]
- d = pgfgd_new_key ("fast simple demo radius");
- pgfgd_key_summary (d, "A radius value for the hello world of graph drawing");
- pgfgd_key_type (d, "length");
- pgfgd_key_initial (d, "1cm");
- pgfgd_declare (state, d);
- pgfgd_free_key (d);
-
- return 0;
-}
-\end{codeexample}
-
-We simply add this code to the startup function above.
-
-Now it is time to compile and link the code. For this, you must, well, compile
-it, link it against the library |InterfaceFromC|, and build a shared library
-out of it. Also, you must place it somewhere where Lua\TeX\ will find it. You
-will find a Makefile that should be able to achieve all of this in the
-directory |pgf/c/graphdrawing/pgf/gd/examples/c|, where you will also find the
-code of the above example.
-
-Now, all you need to do to use it is to write in Lua (after you have loaded the
-|pgf.gd| library, of course), would normally be the call
-%
-\begin{codeexample}[code only, tikz syntax=false]
-require 'pgf.gd.examples.c.SimpleDemoC'
-\end{codeexample}
-%
-or in \tikzname
-%
-\begin{codeexample}[code only]
-\usegdlibrary {examples.c.SimpleDemoC}
-\end{codeexample}
-
-This should cause Lua\TeX\ to find the shared library, load it, and then call
-the function in that library with the lengthy name (the name is always
-|luaopen_| followed by the path and filename with slashes replaced by
-underscores).
-
-\emph{Remark:} Unfortunately, the above does not work with the \TeX Live 2013
-versions of Lua\TeX\ due to a bugs that causes the ``replace dots by slashes''
-to fail. For this reason, we currently need to rename our shared library file
-to
-%
-\begin{codeexample}[code only, tikz syntax=false]
-pgf_gd_examples_c_SimpleDemoC.so
-\end{codeexample}
-%
-and then say
-%
-\begin{codeexample}[code only, tikz syntax=false]
-require 'pgf_gd_examples_c_SimpleDemoC'
-\end{codeexample}
-%
-or in \tikzname
-%
-\begin{codeexample}[code only]
-\usegdlibrary {pgf_gd_examples_c_SimpleDemoC}
-\end{codeexample}
-
-In future versions of Lua\TeX, things should be ``back to normal'' in this
-regard. Also, the bug only concerns shared libraries; you can still create a
-normal Lua file with a nice name and place at a nice location and the only
-contents of this file is then the above |require| command.
-
-Anyway, once we have loaded the shared library we can say:
-%
-\begin{codeexample}[code only]
-\tikz \graph [fast simple demo layout, fast simple demo radius=1.25cm]
-{ a -> b -> c -> d -> e -> a };
-\end{codeexample}
-
-
-\subsubsection{Documenting Algorithms Written in C}
-\label{section-gd-documenting-c-algos}
-
-In our above example, we included a summary with the keys in the C code. It
-would be even better if we added a longer documentation and some examples that
-show how the key works; but this is a bit impracticable in C since multi-line
-strings are hard to write down in~C. The trick is to use the |documentation_in|
-field of a key: It allows us to specify the name of a Lua file that should be
-loaded (using |require|) to install the missing documentation fields. As
-explained in Section~\ref{section-gd-documentation-in}, this Lua file may make
-good use the |pgf.gd.doc| package. Note, also, that for keys documented in this
-way the documentation can easily be included in this manual through the use of
-the |\includedocumentationof| command.
-
-In our example, we would first add the following line twice in the C code (once
-for each key), assuming that the documentation resides in the file
-|pgf/gd/doc/examples/SimpleDemoC.lua|:
-%
-\begin{codeexample}[code only, tikz syntax=false]
- pgfgd_key_documentation_in (d, "pgf.gd.doc.examples.SimpleDemoC");
-\end{codeexample}
-
-Note that since the documentation is a normal Lua file, it will be searched in
-the usual places Lua files are located (in the texmf trees) and not, like the C
-shared library, in the special |lib| subdirectory of the Lua\TeX\ binary.
-
-Here are typical contents of the documentation file:
-%
-\begin{codeexample}[code only, tikz syntax=false]
--- File pgf/gd/doc/examples/SimpleDemoC.lua
-local key = require 'pgf.gd.doc'.key
-local documentation = require 'pgf.gd.doc'.documentation
-local summary = require 'pgf.gd.doc'.summary
-local example = require 'pgf.gd.doc'.example
-
-key "fast simple demo layout"
-documentation
-[[
-This layout is used...
-]]
-example
-[[
-\tikz \graph [fast simple example layout]
-{ a -- b -- c -- d -- e; };
-]]
-
-key "fast simple demo radius"
-documentation
-[[
-The radius parameter is used to ...
-]]
-example
-[[
-\tikz \graph [fast simple demo layout, fast simple demo radius=1.25cm]
-{ a -> b -> c -> d -> e -> a };
-]]
-\end{codeexample}
-
-
-\subsubsection{The Interface From C}
-
-In the above example, we already saw some of the functions from the library
-|InterfaceFromC| that translated from Lua to C for us. For a complete list of
-all functions available, currently please see
-|graphdrawing/c/pgf/gd/interface/c/InterfaceFromC.h| directly.
-
-Currently, the library provides C functions to directly access all aspects of
-the syntactic digraph and also of the graphs computed by the preprocessing of
-the layout pipeline. What is missing, however, is access to the tree of
-(sub)layouts and to collections. Hopefully, these will be added in the future.
-
-
-\subsection{Writing Graph Drawing Algorithms in C++}
-\label{section-gd-c++}
-
-Built on top of the C interface presented in the previous section, there is
-also a C++ interface available. It encapsulates as much of the C functions as
-possible in C++ classes. Thus, this interface is mostly there for convenience,
-it does not offer fundamentally new functionality.
-
-
-\subsubsection{The Hello World of Graph Drawing in C++}
-
-Let us have a look at how our beloved hello world of graph drawing looks in
-C++. Although it is still possible to put graph drawing algorithms inside
-functions, it is more natural in C++ to turn them into methods of a class.
-Thus, we start the code of |SimpleDemoCPlusPlus.c++| as follows:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-#include <pgf/gd/interface/c/InterfaceFromC++.h>
-#include <pgf/gd/interface/c/InterfaceFromC.h>
-
-#include <math.h>
-
-struct FastLayout : scripting::declarations, scripting::runner {
- ...
-}
-\end{codeexample}
-
-As can be seen, we do not only include the interface from C++, but also that
-from C (since, currently, not all functionality of the C library is
-encapsulated in C++).
-
-The interesting part is the |struct FastLayout|, which will contain our
-algorithm (you could just as well have used a |class| instead of a |struct|).
-It is derived from two classes: First, from a |declarations| class and,
-secondly, from a |runner| class. Both of them, just like everything else from
-the interface, reside in the namespace |scripting|. This name was chosen since
-the main purpose of the interface is to provide ``scripting facilities'' to C
-code through the use of Lua.
-
-We are currently interested in the class |runner|. This class has a virtual
-function |run| that gets called when, on the Lua side, someone has selected the
-algorithm represented by the class. Thus, we place our algorithm in this
-method:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-void run () {
- pgfgd_SyntacticDigraph* graph = parameters->syntactic_digraph;
-
- double angle = 6.28318530718 / graph->vertices.length;
- double radius = parameters->option<double>("fast simple demo radius c++");
-
- for (int i = 0; i < graph->vertices.length; i++) {
- pgfgd_Vertex* v = graph->vertices.array[i];
- v->pos.x = cos(angle*i) * radius;
- v->pos.y = sin(angle*i) * radius;
- }
-}
-\end{codeexample}
-
-The |run| method has access to the member variable |parameters|, which contains
-all sorts of information concerning the to-be-drawn graph. In particular, the
-|syntactic_digraph| field gives us access to the syntactic digraph structure
-that was already available in the interface from plain~C. However, we can also
-see that a template function like |option| allows us to access the graph's
-option table in a simple way.
-
-As for C code, our next task is to setup a key that, when used on the
-\tikzname\ layer, will run our algorithm. For this, we can use an object
-derived from a |declarations|. In our example, the |FastLayout| is both derived
-from a |runner| (since it contains an algorithm) and also from |declarations|
-(since it also contains the code necessary for declaring this algorithm). If
-you prefer, you can split this into two classes. A |declarations| object must
-override the |declare| method. This method gets a |script| object as input,
-which is the ``representation'' of Lua inside the C++ code:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-void declare(scripting::script s) {
- using namespace scripting;
-
- s.declare(key ("fast simple demo layout c++")
- .summary ("The C++ version of the hello world of graph drawing")
- .precondition ("connected")
- .precondition ("tree")
- .algorithm (this));
-
- s.declare(key ("fast simple demo radius c++")
- .summary ("A radius value for the hello world of graph drawing")
- .type ("length")
- .initial ("1cm"));
-}
-\end{codeexample}
-
-For each key that we wish to declare, we call the script's |declare| method
-once. This method takes a |key| object as input, which can be configured
-through a sequence of calls to different member functions (like |summary| or
-|algorithm|). Most of these member functions are rather self-explaining; only
-|algorithm| is a bit trickier: It does not take a function as input, but rather
-an object of type |runner| and it will call the |run| method of this object
-whenever the algorithm is run.
-
-Lastly, we also need to write the entry point:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-extern "C" int luaopen_pgf_gd_examples_c_SimpleDemoCPlusPlus (struct lua_State *state) {
- scripting::script s (state);
- s.declare (new FastLayout);
- return 0;
-}
-\end{codeexample}
-
-Note that it is the job of the interface classes to free the passed
-|declarations| object. For this reason, you really need to call |new| and
-cannot pass the address of a temporary object.
-
-As before, because of the bug in some Lua\TeX\ versions, to actually load the
-library at runtime, we need to rename it to
-%
-\begin{codeexample}[code only, tikz syntax=false]
-pgf_gd_examples_c_SimpleDemoCPlusPlus.so
-\end{codeexample}
-%
-and then say
-%
-\begin{codeexample}[code only, tikz syntax=false]
-require 'pgf_gd_examples_c_SimpleDemoCPlusPlus'
-\end{codeexample}
-%
-or in \tikzname
-%
-\begin{codeexample}[code only]
-\usegdlibrary {pgf_gd_examples_c_SimpleDemoCPlusPlus}
-\end{codeexample}
-
-We can now use it:
-%
-\begin{codeexample}[code only]
-\tikz \graph [fast simple demo layout c++, fast simple demo radius c++=1.25cm]
-{ a -> b -> c -> d -> e -> a };
-\end{codeexample}
-
-
-\subsubsection{The Interface From C++}
-
-The header |graphdrawing/c/pgf/gd/interface/c/InterfaceFromC++.h| contains, as
-the name suggest, the interface from C++. A complete documentation is still
-missing, but let us go over the main ideas:
-
-
-\medskip
-\noindent\textbf{Runners.}
-Algorithms are represented by objects of type |runner|. An algorithm will
-overwrite the |run| method, as we saw in the example, and it should modify the
-|parameters| of the runner object.
-
-In addition to the |run| method, there are also two more virtual methods,
-called |bridge| and |unbrigde|. The first is called before the |run| method is
-called and the second afterwards. The idea is that another framework, such as
-\textsc{ogdf}, can implement a new class |ogdf_runner| that overrides these two
-methods in order to transform the Lua/C representation of the input graph into
-an \textsc{ogdf} representation prior to the |run| method being called. The
-|run| method can then access additional member variables that store the graph
-representations in \textsc{ogdf} form (or another form, depending on the
-framework). The |unbridge| method allows the framework to translate back.
-
-Although a |runner| object must be created for every algorithm, an algorithm
-can also reside in a function. The class |function_runner| is a simple wrapper
-that turns a function into such an object.
-
-
-\medskip
-\noindent\textbf{Keys.}
-A key object is a temporary object that is passed to the |declare| method of a
-script. It represents the table that is passed to the Lua function |declare|.
-In order to make setting its field easy, for each field name there is a
-corresponding function (like |summary|) that takes the string that should be
-set to this field and returns the key object once more, so that we can chain
-calls.
-
-The |algorithm| method gets a runner object as parameter and will store a
-pointer to this object inside Lua. Each time the algorithm is used, this object
-will be used to ``run'' the algorithm, that is, the methods |prepare|,
-|bridge|, |run|, and |unbridge| will be called in that order. Since the object
-is reused each time, only one object is needed; but this object may not be
-freed prematurely. Indeed, you will normally create the object using |new| once
-and will then never delete it.
-
-A typical idiom you may find in the code is
-%
-\begin{codeexample}[code only, tikz syntax=false]
-s.declare (key (...)
- .algorithm(this)
- ...);
-\end{codeexample}
-%
-This code is seen inside the |declare| method of objects that are both
-declarations and runners. They register ``themselves'' via the above code.
-Note, however, that this requires that the |this| pointer is not a temporary
-object. (The typing rules of C++ make it hard for this situation to happen, but
-it can be achieved.)
-
-
-\medskip
-\noindent\textbf{Reading options.} Once options have been declared, your C++
-algorithms will wish to read them back. For this, the |parameters| field of a
-runner object provides a number of templated methods:
-%
-\begin{itemize}
- \item The |option_is_set| method returns |true| if the passed option has
- been set \emph{and} can be cast to the type of the template. So,
- |option_is_set<double>("node distance")| will return true if the
- |node distance| key has been set for the graph as a whole (currently,
- there is no way to read the options of a vertex or an edge from C++,
- use the C methods instead).
- \item The |option| function comes in two flavours: First, it takes a single
- option name and just returns the option's value. If, however, the
- option has not been set or has another type, some sort of null value is
- returned. So, |option<double>("node distance")| will return the
- configured node distance as a double. When an option has an initial
- value, this call will always return a sensible value.
-
- The second flavour of |option| allows you to pass a reference to an
- object in which the option's value should be stored and the function
- will return true if the option is set (and, thus, something was written
- into the reference). This is the ``safest'' way to access an option:
- %
-\begin{codeexample}[code only, tikz syntax=false]
-double dist;
-if (parameters->option ("node distance", dist))
- ...
-\end{codeexample}
-
- Caution must be taken for |char*| options: The returned string must be
- explicitly freed; it will be a copy of the string stored in the Lua
- table.
- \item The |configure_option| method is used to set a member of an object
- based on the value of a certain option. For this, you must pass a
- pointer to a member function that sets the member. Here is an example:
- %
-\begin{codeexample}[code only, tikz syntax=false]
-class MyClass {
-public:
- void setMyDistance (double distance);
-...
-};
-...
-
-MyClass m;
-parameters->configure_option("node distance", &MyClass::setMyDistance, m);
-\end{codeexample}
- %
- If the option has not been set or does not have the correct type, the
- member function is not called.
-\end{itemize}
-
-
-\medskip
-\noindent\textbf{Factories and modules.}
-A Lua key is normally either a Boolean, a double, or a string. However, in C++,
-we may also sometimes wish Lua users to configure which C function is used to
-achieve something. One could do this using strings or numbers and then use
-search algorithms or a long |switch|, but this would neither be flexible nor
-elegant.
-
-Instead, it is possible to store \emph{factories} in Lua keys. A factory is a
-class derived from |factory| that implements the virtual function |make|. This
-function will return a new object of a template type. You can store such a
-factory in a key.
-
-The |make| method of a parameters object allows you to invoke the factory
-stored in a key. (If no factory is stored in it, |null| is returned).
-
-The |configure_module| method is akin to |configure_option|, only the result of
-applying the factory is passed to the member function of the class.
-
-
-\medskip
-\noindent\textbf{Scripts.}
-A ``script'' is the abstraction of the communication between Lua and C++. From
-C++'s point of view, the script object offers different |declare| methods that
-allow us to ``make objects and function scriptable'' in the sense that they can
-then be called and configured from Lua. The script must be initialized with a
-Lua state and will be bound to that state (basically, the script only stores
-this single pointer).
-
-When you call |declare|, you either pass a single key object (which is then
-declared on the Lua layer) or you pass a |declarations| object, whose virtual
-|declare| method is then called. The |declarations| objects are used to bundle
-several declarations into a single one.
-
-
-\subsection{Writing Graph Drawing Algorithms Using OGDF}
-\label{section-gd-ogdf-interface}
-
-Built on top of the C++ interface, a small interface allows you to easily link
-algorithms written for the \textsc{ogdf} (Open Graph Drawing Framework) with
-graph drawing in Lua.
-
-
-\subsubsection{The Hello World of Graph Drawing in OGDF -- From Scratch}
-
-We start with some startup code:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-#include <pgf/gd/ogdf/c/InterfaceFromOGDF.h>
-#include <math.h>
-
-using namespace ogdf;
-using namespace scripting;
-\end{codeexample}
-
-Note that the interface from \textsc{ogdf} resides in the |ogdf| folder, not in
-the |interface| folder.
-
-Like in the plain C++ interface, we must now subclass the |runner| class and
-the |declarations| class. Also like the plain C++ interface, we can use
-multiple inheritance. The difference lies in the fact that we do not directly
-subclass form |runner|, but rather from |ogdf_runner|. This class implements
-the complicated ``bridging'' or ``translation'' process between the world of
-|InterfaceFromC++| and \textsc{ogdf}:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-struct FastLayoutOGDF : declarations, ogdf_runner {
-
- void run () {
- double angle = 6.28318530718 / graph.numberOfNodes();
- double radius = parameters->option<double>("my radius ogdf");
-
- int i = 0;
- for (node v = graph.firstNode(); v; v=v->succ(), i++) {
- graph_attributes.x(v) = cos(angle*i) * radius;
- graph_attributes.y(v) = sin(angle*i) * radius;
- }
- }
-\end{codeexample}
-
-As can be seen, in a subclass of |ogdf_runner|, the |run| method will have
-access to a member called |graph| and to another member called
-|graph_attributes|. These will have been setup with the graph from the Lua
-layer and, after the algorithm has run, the information stored in the |x| and
-|y| fields of the graph attributes and also the bend information of the edges
-will be written back automatically.
-
-Next, we need to declare the algorithm. This is done as in the plain
-C++ interface:
-%
-\begin{codeexample}[code only, tikz syntax=false]
- void declare(script s) {
- using namespace scripting;
-
- s.declare(key ("fast simple demo layout ogdf")
- .summary ("The OGDF version of the hello world of graph drawing")
- .precondition ("connected")
- .algorithm (this));
-
- s.declare(key ("my radius ogdf")
- .summary ("A radius value for the hello world of graph drawing")
- .type ("length")
- .initial ("1cm"));
- }
-};
-\end{codeexample}
-
-Finally, we need the entry point, which is also ``as usual'':
-%
-\begin{codeexample}[code only, tikz syntax=false]
-extern "C" int luaopen_pgf_gd_examples_c_SimpleDemoOGDF (struct lua_State *state) {
- script (state).declare (new FastLayoutOGDF);
- return 0;
-}
-\end{codeexample}
-
-Yet again, we need to rename the resulting shared library and then say
-|require| on it. We can now use it:
-%
-\begin{codeexample}[code only]
-\tikz \graph [fast simple demo layout ogdf, my radius ogdf=1cm]
-{ a -> b -> c -> d -> e -> a };
-\end{codeexample}
-
-
-\subsubsection{The Hello World of Graph Drawing in OGDF -- Adapting Existing Classes}
-
-In the previous example we implemented a graph drawing algorithm using
-\textsc{ogdf} for use with Lua ``from scratch''. In particular, the whole
-algorithm was contained in the |run| method of our main class. In practice,
-however, graph drawing algorithms are typically placed in classes that ``know
-nothing about scripting''. For instance, our hello world of graph drawing might
-actually be implemented like this:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-// File HelloWorldLayout.h
-#include <ogdf/module/LayoutModule.h>
-
-class HelloWorldLayout : puplic ogdf::LayoutModule {
-public:
-
- virtual void call(ogdf::GraphAttributes &GA)
- {
- using namespace ogdf;
-
- const Graph &graph = GA.constGraph();
- double angle = 6.28318530718 / graph.numberOfNodes();
- int i = 0;
- for (node v = graph.firstNode(); v; v=v->succ(), i++) {
- GA.x(v) = cos(angle*i) * radius;
- GA.y(v) = sin(angle*i) * radius;
- }
- }
-
- void setRadius (double r) { radius = r; }
-
-private:
-
- double radius;
-};
-\end{codeexample}
-
-Now, what we actually want to do is to ``make this class scriptable''. For
-this, we setup a new class whose |run| method will produce a new
-|HelloWorldLayout|, configure it, and then run it. Here is this run method:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-void run ()
-{
- HelloWorldLayout layout;
- parameters->configure_option("HelloWorldLayout.radius", &HelloWorldLayout::setRadius, layout);
- layout.call(graph_attributes);
-}
-\end{codeexample}
-
-Next, we need to write the declarations code. This is very similar to the
-``from scratch'' version:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-void declare(script s) {
- using namespace scripting;
-
- s.declare(key ("HelloWorldLayout")
- .summary ("The OGDF version of the hello world of graph drawing")
- .precondition ("connected")
- .algorithm (this));
-
- s.declare(key ("HelloWorldLayout.radius")
- .summary ("A radius value for the hello world of graph drawing")
- .type ("length")
- .alias ("radius"));
-}
-\end{codeexample}
-
-Two remarks are in order: First, it is customary to name the keys for the
-display system the same way as the classes. Second, the different configuration
-options of the algorithm are named with the class name followed by the option
-name. This makes it clear who, exactly, is being configured. However, these
-keys should then also get an |alias| field set, which will cause an automatic
-forwarding of the key to something more ``user friendly'' like just |radius|.
-
-It remains to put the above methods in a ``script'' file. It is this file that,
-when compiled, must be linked at runtime against Lua\TeX.
-%
-\begin{codeexample}[code only, tikz syntax=false]
-// File HelloWorldLayout_script.c++
-
-#include <pgf/gd/ogdf/c/InterfaceFromOGDF.h>
-#include <HelloWorldLayout.h>
-
-using namespace ogdf;
-using namespace scripting;
-
-struct HelloWorldLayout_script : declarations, ogdf_runner {
- void run () { ... see above ... }
- void declare (script s) { ... see above ... }
-};
-
-extern "C" int luaopen_my_path_HelloWorldLayout_script (struct lua_State *state) {
- script (state).declare (new HelloWorldLayout_script);
- return 0;
-}
-\end{codeexample}
-
-
-\subsubsection{Documenting OGDF Algorithms}
-
-As explained in Section~\ref{section-gd-documenting-c-algos}, we can add
-external documentation to algorithms written in C and, using the
-|documentation_in| method of the |key| class, we can use the exact same method
-to document \textsc{ogdf} algorithms.
-
-I strongly recommend making use of this feature since, currently, the
-documentation of many \textsc{ogdf} classes is sketchy at best and using
-\tikzname\ examples seems to be a good way of explaining the effect of the
-different parameters algorithms offer.
-
-
-\subsubsection{The Interface From OGDF}
-
-The support for \textsc{ogdf} offered inside |InterfaceFromOGDF.h| is just the
-class |ogdf_runner| we saw already in the example. In addition, there is also a
-wrapper class |ogdf_function_runner| that allows you to wrap an algorithm
-implemented in a function that uses \textsc{ogdf}, but I expect this to be the
-case only rarely.
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-binding-layer.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-binding-layer.tex
deleted file mode 100644
index 229e1bc1eb..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-binding-layer.tex
+++ /dev/null
@@ -1,281 +0,0 @@
-% Copyright 2010-2019 by Renée Ahrens
-% Copyright 2010-2019 by Olof Frahm
-% Copyright 2010-2019 by Jens Kluttig
-% Copyright 2010-2019 by Matthias Schulz
-% Copyright 2010-2019 by Stephan Schuster
-% Copyright 2019 by Jannis Pohlmann
-% 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{The Binding Layer}
-\label{section-gd-binding-layer}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-
-\subsection{Overview}
-
-This section explains how the \emph{binding} of the graph drawing system to a
-particular display layer works. Let me stress that all of this is important
-only for readers who
-%
-\begin{itemize}
- \item either wish to write new display system (see
- Section~\ref{section-gd-display-layer})
- \item or wish to know more about how the graph drawing system works on the
- pure \pgfname\ layer (this is were the binding occurs).
-\end{itemize}
-
-\emph{Bindings} are used to encapsulate the details of the communication
-between the graph drawing system and a display system (see
-Section~\ref{section-gd-display-layer} for an introduction to display systems).
-
-Consider a display system that communicates with the graph drawing system. At
-some point, the display system would like to run an algorithm to lay out a
-graph. To achieve this, it will call different functions from the class
-|InterfaceToDisplay| and the effect of this is that a representation of the
-to-be-drawn graph is constructed internally and that the appropriate algorithms
-are run. All of this is in some sense independent of the actual display system,
-the class |InterfaceToDisplay| offers the same standard interface to all
-display systems.
-
-At some point, however, the graph drawing system may need to ``talk back'' to
-the display system. For instance, once the graph has been laid out, to trigger
-the actual rendering of the graph, the graph drawing system must ``tell'' the
-display layer where the vertices lie. For some display systems this is easy: if
-the display system itself is written in Lua, it could just access the syntactic
-digraph directly. However, for systems like \tikzname\ or systems written in
-another language, the graph drawing system needs a set of functions that it can
-call that will tell the display system what is going on. This is were bindings
-come in.
-
-The class |Binding| is an interface that defines numerous methods that will be
-called by the graph drawing system in different situations (see the
-documentation below for details). For instance, there is a function
-|renderVertex| that is called by the graph drawing system whenever a vertex
-should be rendered by the display system. The class is really just an interface
-in the sense of object-oriented programming. For each display system you need
-to create a subclass of |Binding| like |BindingToPGF| or |BindingToASCII| that
-implement the methods declared by |Binding|. The number of methods that need to
-be implemented depends on the display system.
-
-In the following, you will find the documentation of the |Binding| class in
-Section~\ref{section-gd-binding-doc}. Following this, we first have a quick
-look at how the |BindingToPGF| works and then go over a simple example of a
-binding to a more or less imaginary display system. This example should help
-readers interested in implementing their own bindings.
-
-
-\subsection{The Binding Class and the Interface Core}
-\label{section-gd-binding-doc}
-
-\includeluadocumentationof{pgf.gd.bindings.Binding}
-\includeluadocumentationof{pgf.gd.interface.InterfaceCore}
-
-
-\subsection{The Binding To PGF}
-
-\includeluadocumentationof{pgf.gd.bindings.BindingToPGF}
-
-
-\subsection{An Example Binding Class}
-
-\label{section-gd-binding-layer-example}
-
-In the present section a complete binding is presented to an imaginary
-``\textsc{ascii} art display system'' is presented. The idea is that this
-display system will depict graphs using just normal letters and spaces so that,
-when the text is typeset in a monospace font, a visualization of the graph
-results. For instance:
-
-\bigskip
-\noindent
-\begin{minipage}[t]{.5\textwidth}
-\emph{Graph rendered by |BindingToPGF|:}
-\medskip
-
-\tikz [anchor=base]\graph [layered layout,level distance=2.35cm,sibling
-distance=1.2cm,edges={rounded corners,>={Stealth[round,sep]}}] {
- Alice;
- Bob;
- Charly;
- Dave;
- Eve;
- Fritz;
- George;
- Alice -> Bob;
- Alice -> Charly;
- Charly -> Dave;
- Bob -> Dave;
- Dave -> Eve;
- Eve -> Fritz;
- Fritz -> Alice;
- George -> Eve;
- George -> Fritz;
- Alice -> George;
-};
-\end{minipage}%
-\begin{minipage}[t]{.49\textwidth}
-\emph{Graph rendered by |BindingToASCII|:}
-
-\begin{verbatim}
- Alice
- .......
- .. . . .
- ... . . .
- ... .. . ..
- .. . . .
- Charly Bob . .
- .. . . .
- . . . .
- . . . .
- .. . . .
- .. . .
- Dave George .
- .. . ... .
- . . .. .
- . . ...
- .. . . ...
- .. . ..
- Eve . ..
- .. . ..
- . . .
- . . .
- .. . ..
- ...
- Fritz
-\end{verbatim}
-\end{minipage}
-\bigskip
-
-The binding will reside in a file |BindingToASCII.lua|, whose contents is
-detailed below, and which is used by calling the |bind| function of
-|InterfaceToDisplay|, see its documentation for details.
-
-The binding's code starts with some initializations:
-%
-\begin{codeexample}[code only]
--- File BindingToASCII.lua
-
--- Imports
-local lib = require "pgf.gd.lib"
-
--- Subclass the Binding class:
-local BindingToASCII = lib.class { base_class = require "pgf.gd.bindings.Binding" }
-\end{codeexample}
-
-The interesting code is the code for ``rendering'' a graph. The graph drawing
-system will invoke the binding's methods |renderStart| and |renderStop| to
-signal that the graph drawing algorithms have finished and that the vertices
-and edges can now be drawn.
-
-In our \textsc{ascii} renderer, we use a two-dimensional field holding
-characters that severs as the ``drawing canvas''. At the beginning of the
-rendering, we initialize it with blanks:
-%
-\begin{codeexample}[code only]
-local canvas
-
-function BindingToASCII:renderStart()
- canvas = {}
- -- Clear the canvas
- for x=-30,30 do
- canvas [x] = {}
- for y=-30,30 do
- canvas[x][y] = ' '
- end
- end
-end
-\end{codeexample}
-
-In order to ``render'' a vertex, the graph drawing system will call the
-|renderVertex| method. The binding of \tikzname\ does a lot of complicated
-things in this method to retrieve the underlying node's box from internal table
-and to somehow reinstall the box in \TeX's output stream; for our
-\textsc{ascii} binding things are much simpler: We simply put the vertex's name
-at the canvas position corresponding to the vertex's |pos| coordinate. Note
-that this simple version of an \textsc{ascii} renderer does not try to scale
-things; thus, array out of bounds might occur here.
-%
-\begin{codeexample}[code only]
-function BindingToASCII:renderVertex(v)
- canvas [math.floor(v.pos.x)][math.floor(v.pos.y)] = v.name
-end
-\end{codeexample}
-
-The rendering of edges is a more complicated process. Given two vertices, we
-put dots at the canvas positions between them; provided there are no vertices
-(so edges are behind the nodes). Here is the essential part of the code (for
-the complete code, have a look at |pgf/gd/examples/BindingToASCII.lua|):
-%
-\begin{codeexample}[code only]
-function BindingToASCII:renderEdge(e)
- local function connect (p,q)
- -- Connect the points p and q
- local x1, y1, x2, y2 = math.floor(p.x+0.5), math.floor(p.y+0.5), math.floor(q.x+0.5), math.floor(q.y+0.5)
- ...
- local delta_x = x2-x1
- local delta_y = y2-y1
- ...
- local slope = delta_y/delta_x
- for i=x1,x2 do
- local x,y = i, math.floor(y1 + (i-x1)*slope + 0.5)
-
- if canvas[x][y] == " " then
- canvas[x][y] = '.'
- end
- end
- ...
- end
-
- -- Iterate over all points on the path from tail to head:
- local p = e.tail.pos
- for i=1,#e.path do
- connect(p, e.tail.pos + e.path[i])
- p = e.tail.pos + e.path[i]
- end
- connect(p, e.head.pos)
-end
-\end{codeexample}
-
-The methods |renderVertex| and |renderEdge| will be called once for each vertex
-and edge of the to-be-rendered graph. At the end, the |renderStop| method is
-called. In our case, this method will output the canvas using |print|. A slight
-complication arises when node names are longer than just one character. In this
-case, the following code ``centers'' them on their coordinate and makes sure
-that they do not get overwritten by the dots forming edges:
-%
-\begin{codeexample}[code only]
-function BindingToASCII:renderStop()
- for y=10,-30,-1 do
- local t = {}
- for x=-30,30 do
- local s = canvas[x][y]
- for i=1,#s do
- pos = x+30+i-math.floor(#s/2)
- if not t[pos] or t[pos] == " " or t[pos] == "." then
- t[pos] = string.sub(s,i,i)
- end
- end
- end
- print(table.concat(t))
- end
-end
-\end{codeexample}
-
-At the end, we need to return the created object:
-%
-\begin{codeexample}[code only]
-return BindingToASCII
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-circular.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-circular.tex
deleted file mode 100644
index 5d82f556ee..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-circular.tex
+++ /dev/null
@@ -1,29 +0,0 @@
-% Copyright 2018 by Jannis Pohlmann
-%
-% 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{Graph Drawing Algorithms: Circular Layouts}
-
-{\noindent {\emph{by Till Tantau}}}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-
-\includeluadocumentationof{pgf.gd.circular.library}
-\includeluadocumentationof{pgf.gd.circular.Tantau2012}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-display-layer.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-display-layer.tex
deleted file mode 100644
index c265b7f4af..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-display-layer.tex
+++ /dev/null
@@ -1,285 +0,0 @@
-% Copyright 2010-2018 by Renée Ahrens
-% Copyright 2010-2018 by Olof Frahm
-% Copyright 2010-2018 by Jens Kluttig
-% Copyright 2010-2018 by Matthias Schulz
-% Copyright 2010-2018 by Stephan Schuster
-% Copyright 2018 by Jannis Pohlmann
-% Copyright 2018 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{The Display Layer}
-\label{section-gd-display-layer}
-
-{\noindent {\itshape{by Till Tantau}}}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-
-\begin{quote}
- \itshape You do not need to read this section in order to write new graph
- drawing algorithms. It is of interest only to those wishing to write
- programs that wish to ``use'' the graph drawing system in a similar way
- that \tikzname\ does for laying out graphs that are generated and then
- passed down from the program to the graph drawing system.
-\end{quote}
-
-
-\subsection{Introduction: The Interplay of the Different Layers}
-
-The job of the graph drawing system is to run graph drawing algorithms on
-graphs. Since graph drawing is useful in many different contexts, not only in
-the context of \tikzname\ for which the present system was originally
-developed, the graph drawing system was designed in such a way that it can be
-used independently of \tikzname. To achieve this, the \emph{display layer}
-provides an interface via which an arbitrary program (\tikzname, a graph
-editor, a command line interface, etc.) ``talk'' to the graph drawing system.
-
-To better understand how this works, let us consider the following setup:
-%
-\begin{itemize}
- \item A program would like to communicate with the graph drawing system. It
- is written in Java and its job is to analyse social networks. This
- software would like to use graph drawing to produce drawings of some
- ``social graphs'' arising from its analyses. This software will be
- called ``the display system'' in the following.
- \item There are two algorithms that the display system would like to apply
- to the graphs its produces. Let us call these algorithms ``A'' and
- ``B''. However, the display system would also, ideally, wish to make it
- possible that its user chooses other algorithms ``C'' that are not
- necessarily part of its binary.
- \item The display system has internally generated a ``social graph'' that
- it would now like to draw.
-\end{itemize}
-
-For this setup, the communication between the different layers of the graph
-drawing system is as follows:
-%
-\begin{enumerate}
- \item The display system, being written in Java, must embed Lua to use the
- graph drawing system.
- \item The display system must initialize the graph drawing system. For
- this, it must use |require| on the file |InterfaceToDisplay|, which, as
- the name suggests, contains the interface between the display system
- and the graph drawing system.
-
- It must also create a so-called ``binding'' between the graph drawing
- system and the display layer. See
- Section~\ref{section-gd-binding-layer} for more information on
- bindings.
- \item The display system now needs to load the declarations of the
- algorithms A and B. For this, it just needs to apply |require| to the
- files in which the algorithms reside. This will cause the |declare|
- function to be called. This function is declared by
- |InterfaceToAlgorithms| and allows files to declare that certain
- algorithms and options are now available.
-
- Once this is done, the graph drawing system is fully initialized and
- can be used.
- \item Later on, the display system wishes to lay out a social graph. Note
- that this is known as ``drawing the graph'' in the graph drawing
- community, even though this only means the coordinates are computed for
- the nodes of the graph. The actual ``rendering'' of the graph on the
- display is the job of the display system (hence the name ``display
- layer'').
- \item To start the layout process, the display system calls the function
- |beginGraphDrawingScope| of the class |InterfaceToDisplay|.
- \item Next, for each vertex the function |createVertex| of the interface
- class must be called and similarly for each edge. These calls will
- cause an internal model of the graph to be created on the algorithm
- layer. Options that are attached to nodes and edges are also
- communicated to the graph drawing system through function calls like
- |pushOption|.
- \item When the graph is fully specified, the method
- |runGraphDrawingAlgorithm| must be called, which is once more a method
- of the interface class. This function will internally discern which
- algorithms have been chosen (via options) and invoke the code of the
- appropriate algorithms.
- \item Next, the function |renderGraph| must be called. Its job is to
- ``communicate back'' which coordinates have been computed. It will use
- the binding for this communication, see
- Section~\ref{section-gd-binding-layer}.
- \item Finally, by calling |endGraphDrawingScope|, the resources needed for
- the layout process for the social graph are freed once more.
-\end{enumerate}
-
-A few points may be noteworthy:
-%
-\begin{itemize}
- \item The whole communication between the display system and the graph
- drawing system goes through the interface class via function calls.
- This makes it easy to communicate with display system whose internal
- model of graphs is quite different from the one used in Lua (as is
- certainly the case for \TeX, but also the ``social graph'' mentioned
- above need not even exist as a separate entity inside the display
- system).
-
- \emph{The display system should only rely on the interface class. All
- communication has to go through this class, the display system may not
- access the internals of the internally constructed graphs directly.}
- \item New algorithms can be loaded at runtime, as long as the |require|
- method is supported.
- \item The display system can also use the interface class to query which
- algorithms and which options are available in principle (and display
- this information to the user). The display system can even get access
- the documentation of the options at runtime since the documentation is
- stored in fields of the declared options.
-\end{itemize}
-
-In the following, we first present a simple display system other than
-\tikzname. The remainder of the section then encompasses a documentation of the
-different functions of the class |InterfaceToDisplay|.
-
-
-\subsection{An Example Display System}
-
-In the following, we present the code of a very simple display system written
-in Lua (another such display system is \tikzname\ itself, but the minimal
-system will allow us to focus on what is really needed). You will also find it
-in |pgf.gd.examples.ASCIIDisplayer|.
-
-The job of this display system is to parse a string that encodes a graph and to
-call the appropriate functions of |InterfaceToDisplay| to lay out the graph.
-The actual calls for rendering the graph are part of the binding, which is
-documented in Section~\ref{section-gd-binding-layer-example}.
-
-The syntax of the to-be-laid-out graph is a reduced version of \tikzname's
-|graph| syntax: The string must start with |graph[|\meta{algorithm's name}|]{|
-and end with |}|. Between the braces, all lines must either be of the form
-\meta{node name}|;| or \meta{name 1}|->|\meta{name 2}|;| with optional spaces
-around the node names.
-
-Let us now have a look at what we must do to use the graph drawing system.
-First, we load some libraries and initialize the binding (see
-Section~\ref{section-gd-binding-layer-example} for details on the binding; we
-can ignore it for now).
-%
-\begin{codeexample}[code only]
-local InterfaceToDisplay = require "pgf.gd.interface.InterfaceToDisplay"
-InterfaceToDisplay.bind(require "pgf.gd.examples.BindingToASCII")
-
--- Load two libraries that define graph drawing algorithms. We can do this only *after* the binding
--- has been created since they call the declare function internally.
-require "pgf.gd.layered.library"
-require "pgf.gd.force.library"
-\end{codeexample}
-
-Now comes some preparation code that starts a graph drawing scope and sets up
-the algorithm to the string provided between the square \todosp{should
-\texttt{.pushPhase} be \texttt{.pushOption}? (bug \#396)} brackets:
-
-%
-\begin{codeexample}[code only]
-local algorithm = io.read():match("%s*graph%s*%[(.-)%]")
-
-InterfaceToDisplay.pushPhase(algorithm, "main", 1)
-InterfaceToDisplay.pushOption("level distance", 6, 2)
-InterfaceToDisplay.pushOption("sibling distance", 8, 3)
-InterfaceToDisplay.beginGraphDrawingScope(3)
-InterfaceToDisplay.pushLayout(4)
-\end{codeexample}
-
-The numbers |1| to |4| are the positions on the options stack at which the
-options should be placed. See the description of |pushOption| for more details.
-
-We are now ready to create the vertices and edges via a very simple parser:
-%
-\begin{codeexample}[code only]
-for line in io.lines() do
- if line:match("}") then
- break
- elseif line:find("-") then
- local n1, dir, n2 = string.match(line, "^%s*(.-)%s*(-.)%s*(.-)%s*;")
- InterfaceToDisplay.createEdge(n1, n2, dir, 4)
- else
- local n1 = string.match(line, "^%s*(.-)%s*;")
- InterfaceToDisplay.createVertex(n1, "rectangle", nil, 4)
- end
-end
-\end{codeexample}
-
-The graph is now completely constructed inside the graph drawing system. We can
-now invoke the algorithms:
-%
-\begin{codeexample}[code only]
-InterfaceToDisplay.runGraphDrawingAlgorithm()
-InterfaceToDisplay.renderGraph()
-InterfaceToDisplay.endGraphDrawingScope()
-\end{codeexample}
-
-We can now run the resulting file using the Lua interpreter. If we provide the
-input shown on the left, we get the output shown on the right:
-
-\bigskip
-\noindent
-\begin{minipage}[t]{.5\textwidth}
-\emph{Input given to ASCIIDisplayer:}
-
-\begin{verbatim}
-graph [layered layout] {
- Alice;
- Bob;
- Charly;
- Dave;
- Eve;
- Fritz;
- George;
- Alice -> Bob;
- Alice -> Charly;
- Charly -> Dave;
- Bob -> Dave;
- Dave -> Eve;
- Eve -> Fritz;
- Fritz -> Alice;
- George -> Eve;
- George -> Fritz;
- Alice -> George;
-}
-\end{verbatim}
-\end{minipage}%
-\begin{minipage}[t]{.49\textwidth}
-\emph{Output produced by ASCIIDisplayer:}
-
-\begin{verbatim}
- Alice
- .......
- .. . . .
- ... . . .
- ... .. . ..
- .. . . .
- Charly Bob . .
- .. . . .
- . . . .
- . . . .
- .. . . .
- .. . .
- Dave George .
- .. . ... .
- . . .. .
- . . ...
- .. . . ...
- .. . ..
- Eve . ..
- .. . ..
- . . .
- . . .
- .. . ..
- ...
- Fritz
-\end{verbatim}
-\end{minipage}
-
-
-\subsection{The Interface to Display Systems}
-
-\includeluadocumentationof{pgf.gd.interface.InterfaceToDisplay}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-edge-routing.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-edge-routing.tex
deleted file mode 100644
index 6eb09f5f84..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-edge-routing.tex
+++ /dev/null
@@ -1,33 +0,0 @@
-% Copyright 2018 by Jannis Pohlmann
-%
-% 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{Graph Drawing Algorithms: Edge Routing}
-\label{section-last-graphdrawing-library-in-manual}
-
-{\noindent{\emph{by Till Tantau}}\todosp{Why is a second label here? The second
-doesn't seem to be used.}}
-
-\label{section-gd-edge-routing}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-
-\includeluadocumentationof{pgf.gd.routing.library}
-\includeluadocumentationof{pgf.gd.routing.NecklaceRouting}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-examples.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-examples.tex
deleted file mode 100644
index 830880d917..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-examples.tex
+++ /dev/null
@@ -1,14 +0,0 @@
-% Copyright 2012 by Jannis Pohlmann
-%
-% 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.
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-force.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-force.tex
deleted file mode 100644
index 80402970f0..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-force.tex
+++ /dev/null
@@ -1,43 +0,0 @@
-% Copyright 2018 by Jannis Pohlmann
-%
-% 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{Graph Drawing Algorithms: Force-Based Methods}
-\label{section-library-graphdrawing-force-based}
-
-{\emph{by Till Tantau and Jannis Pohlmann}}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-
-\includeluadocumentationof{pgf.gd.force.library}
-
-\includeluadocumentationof{pgf.gd.force.ControlDeclare}
-\includeluadocumentationof{pgf.gd.force.ControlStart}
-\includeluadocumentationof{pgf.gd.force.ControlIteration}
-\includeluadocumentationof{pgf.gd.force.ControlSprings}
-\includeluadocumentationof{pgf.gd.force.ControlElectric}
-\includeluadocumentationof{pgf.gd.force.ControlCoarsening}
-
-\includeluadocumentationof{pgf.gd.force.SpringLayouts}
-\includeluadocumentationof{pgf.gd.force.SpringHu2006}
-
-\includeluadocumentationof{pgf.gd.force.SpringElectricalLayouts}
-\includeluadocumentationof{pgf.gd.force.SpringElectricalHu2006}
-\includeluadocumentationof{pgf.gd.force.SpringElectricalWalshaw2000}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-layered.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-layered.tex
deleted file mode 100644
index c934a465a4..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-layered.tex
+++ /dev/null
@@ -1,33 +0,0 @@
-% Copyright 2018 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{Graph Drawing Algorithms: Layered Layouts}
-
-{\emph{by Till Tantau and Jannis Pohlmann}}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-\includeluadocumentationof{pgf.gd.layered.library}
-\includeluadocumentationof{pgf.gd.layered.Sugiyama}
-\includeluadocumentationof{pgf.gd.layered.cycle_removal}
-\includeluadocumentationof{pgf.gd.layered.node_ranking}
-\includeluadocumentationof{pgf.gd.layered.crossing_minimization}
-\includeluadocumentationof{pgf.gd.layered.node_positioning}
-\includeluadocumentationof{pgf.gd.layered.edge_routing}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-misc.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-misc.tex
deleted file mode 100644
index e6a72771d8..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-misc.tex
+++ /dev/null
@@ -1,30 +0,0 @@
-% Copyright 2012 by Jannis Pohlmann
-%
-% 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{Graph Drawing Layouts: Miscellaneous}
-
-
-\begin{tikzlibrary}{graphdrawing.misc}
- Load this package when you wish to use the graph drawing algorithms
- defined in this library. You should load the |graphdrawing| library first.
-\end{tikzlibrary}
-
-
-\begin{gdalgorithm}{simple demo layout}{Simple Demo}
- The algorithm used in the examples of this manual for demonstrating
- how a trivial graph drawing can be implemented.
-\end{gdalgorithm}
-
-
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-ogdf.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-ogdf.tex
deleted file mode 100644
index b90e664bf1..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-ogdf.tex
+++ /dev/null
@@ -1,115 +0,0 @@
-% Copyright 2018 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[Graph Drawing Algorithms: The Open Graph Drawing Framework]{Graph Drawing Algorithms:\\ The Open Graph Drawing Framework}
-
-% TODO:{
-% ATTENTION: this label is ALSO present in the previous algorithm.
-% Please update the labels once this section is back in the manual
-% }
-\label{section-last-graphdrawing-library-in-manual}
-
-{\emph{by Till Tantau (who copied much of the text from
- the source documentation of \textsc{ogdf})}}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-\ifgdccodeogdf
-\else
- In order to typeset this section, LuaTeX\ must be able to link C code at
- runtime and the \textsc{ogdf} graph drawing C libraries must be installed
- on your system. You will find the sources in the |c| subdirectory of the
- installation, where you will also find example Makefiles.
- \expandafter\endinput
-\fi
-
-\emph{Remark:} The integration of the \textsc{ogdf} library is still under
-construction and the examples in this section are more a proof-of-concept. So,
-use at your own risk.
-
-\includeluadocumentationof{pgf.gd.ogdf.library}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.SugiyamaLayout}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.module.RankingModule}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.CoffmanGrahamRanking}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.LongestPathRanking}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.OptimalRanking}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.module.TwoLayerCrossMin}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.BarycenterHeuristic}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.GreedyInsertHeuristic}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.MedianHeuristic}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.SiftingHeuristic}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.SplitHeuristic}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.module.AcyclicSubgraphModule}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.DfsAcyclicSubgraph}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.GreedyCycleRemoval}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.module.HierarchyLayoutModule}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.FastHierarchyLayout}
-\includeluadocumentationof{pgf.gd.doc.ogdf.layered.FastSimpleHierarchyLayout}
-
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.SpringEmbedderFR}
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.SpringEmbedderFRExact}
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.SpringEmbedderKK}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.FMMMLayout}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.MultilevelLayout}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.GEMLayout}
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.FastMultipoleEmbedder}
-
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.module.InitialPlacer}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.BarycenterPlacer}
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.CirclePlacer}
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.MedianPlacer}
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.RandomPlacer}
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.SolarPlacer}
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.ZeroPlacer}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.module.MultilevelBuilder}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.EdgeCoverMerger}
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.IndependentSetMerger}
-\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.LocalBiconnectedMerger}
-%\includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.MatchingMerger}
-% \includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.RandomMerger}
-% \includeluadocumentationof{pgf.gd.doc.ogdf.energybased.multilevelmixer.SolarMerger}
-
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.planarity}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.planarity.PlanarizationLayout}
-%\includeluadocumentationof{pgf.gd.ogdf.planarity.LayoutPlanRepModule}
-
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.misclayout}
-
-\includeluadocumentationof{pgf.gd.doc.ogdf.misclayout.BalloonLayout}
-\includeluadocumentationof{pgf.gd.doc.ogdf.misclayout.CircularLayout}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-overview.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-overview.tex
deleted file mode 100644
index 190451b149..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-overview.tex
+++ /dev/null
@@ -1,310 +0,0 @@
-% Copyright 2019 by Renée Ahrens, Olof Frahm, Jens Kluttig, Matthias Schulz, Stephan Schuster
-% Copyright 2019 by Till Tantau
-% Copyright 2019 by Jannis Pohlmann
-%
-% 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{Introduction to Algorithmic Graph Drawing}
-\label{section-intro-gd}
-
-\emph{by Till Tantau}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-
-\subsection{What Is Algorithmic Graph Drawing?}
-
-\emph{Algorithmic graph drawing} (or just \emph{graph drawing} in the
-following) is the process of computing algorithmically where the nodes of a
-graph are positioned on a page so that the graph ``looks nice''. The idea is
-that you, as human (or you, as a machine, if you happen to be a machine and
-happen to be reading this document) just specify which nodes are present in a
-graph and which edges are present. Additionally, you may add some ``hints''
-like ``this node should be near the center'' or ``this edge is pretty
-important''. You do \emph{not} specify where, exactly, the nodes and edges
-should be. This is something you leave to a \emph{graph drawing algorithm}. The
-algorithm gets your description of the graph as an input and then decides where
-the nodes should go on the page.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{trees}}]
-\tikz \graph [binary tree layout, level distance=5mm] {
- 4 -- {
- 3 -- 0 -- 1[second],
- 10 -- {
- 8 -- {
- 6 -- {5,7},
- 9
- } } }
-};
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing,quotes}
-\usegdlibrary{force}}]
-\tikz \graph [spring layout,
- edge quotes mid,
- edges={nodes={font=\scriptsize, fill=white, sloped, inner sep=1pt}}]
-{
- 1 ->["Das"] 2 ->["ist"] 3 ->["das"] 4 ->["Haus"]
- 2 ->["vom" near start] 5 ->["Ni"] 4 ->["ko" near start]
- 1 ->["laus", orient=right] 5;
-};
-\end{codeexample}
-
-Naturally, graph drawing is a bit of a (black?) art. There is no ``perfect''
-way of drawing a graph, rather, depending on the circumstances there are
-several different ways of drawing the same graph and often it will just depend
-on the aesthetic sense of the reader which layout he or she would prefer. For
-this reason, there are a huge number of graph drawing algorithms ``out there''
-and there are scientific conference devoted to such algorithms, where each year
-dozens of new algorithms are proposed.
-
-Unlike the rest of \pgfname\ and \tikzname, which is implemented purely in
-\TeX, the graph drawing algorithms are simply too complex to be implemented
-directly in \TeX. Instead, the programming language Lua is used by the
-|graphdrawing| library -- a programming language that has been integrated into
-recent versions of \TeX. This means that (a) as a user of the graph drawing
-engine you run \TeX\ on your documents in the usual way, no external programs
-are called since Lua is already integrated into \TeX, and (b) it is pretty easy
-to implement new graph drawing algorithms for \tikzname\ since Lua can be used
-and no \TeX\ programming knowledge is needed.
-
-
-\subsection{Using the Graph Drawing System}
-
-``Users'' of the graph drawing engine can invoke the graph drawing algorithms
-often by just adding a single option to their picture. Here is a typical
-example, where the |layered layout| option tells \tikzname\ that the graph
-should be drawn (``should be laid out'') using a so-called ``layered graph
-drawing algorithm'' (what these are will be explained later):
-%
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,graphs,graphdrawing}
-\usegdlibrary{layered}}]
-\tikz [>={Stealth[round,sep]}]
- \graph [layered layout, components go right top aligned, nodes=draw, edges=rounded corners]
- {
- first root -> {1 -> {2, 3, 7} -> {4, 5}, 6 }, 4 -- 5;
- second root -> x -> {a -> {u,v}, b, c -> d -> {w,z} };
- third root -> child -> grandchild -> youngster -> third root;
- };
-\end{codeexample}
-%
-Here is another example, where a different layout method is used that is more
-appropriate for trees:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphdrawing}
-\usegdlibrary{trees}}]
-\tikz [grow'=up, binary tree layout, nodes={circle,draw}]
- \node {1}
- child { node {2}
- child { node {3} }
- child { node {4}
- child { node {5} }
- child { node {6} }
- }
- }
- child { node {7}
- child { node {8}
- child[missing]
- child { node {9} }
- }
- };
-\end{codeexample}
-%
-A final example, this time using a ``spring electrical layout'' (whatever that
-might be\dots):
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{decorations.pathmorphing,graphdrawing}
-\usegdlibrary{force}}]
-\tikz [spring electrical layout, node distance=1.3cm,
- every edge/.style={
- decoration={coil, aspect=-.5, post length=1mm,
- segment length=1mm, pre length=2mm},
- decorate, draw}]
-{
- \foreach \i in {1,...,6}
- \node (node \i) [fill=blue!50, text=white, circle] {\i};
-
- \draw (node 1) edge (node 2)
- (node 2) edge (node 3)
- edge (node 4)
- (node 3) edge (node 4)
- edge (node 5)
- edge (node 6);
-}
-\end{codeexample}
-%
-In all of the example, the positions of the nodes have only been computed
-\emph{after} all nodes have been created and the edges have been specified. For
-instance, in the last example, without the option |spring electrical layout|,
-all of the nodes would have been placed on top of each other.
-
-
-\subsection{Extending the Graph Drawing System}
-
-The graph drawing engine is also intended to make is (relatively) easy to
-implement new graph drawing algorithms. These algorithms can either be
-implemented in the Lua programming language (which is \emph{much} easier to
-program than \TeX\ itself) or in C/C++ (but at a great cost regarding
-portability). The Lua code for a graph drawing algorithm gets an
-object-oriented model of the input graph as an input and must just compute the
-desired new positions of the nodes. The complete handling of passing options
-and configurations back-and-forth between the different \tikzname\ and
-\pgfname\ layers is handled by the graph drawing engine.
-
-As a caveat, the graph drawing engine comes with a library of functions and
-methods that simplify the writing of new graph drawing algorithms. As a typical
-example, when you implement a graph drawing algorithm for trees, you typically
-require that your input is a tree; but you can bet that users will feed all
-sorts of graphs to your algorithm, including disjoint unions of cliques. The
-graph drawing engine offers you to say that a precondition to running your
-algorithm is that the graph is a |tree| and instead of the original graph your
-algorithm will be provided with a spanning tree of the graph on which it can
-work. There are numerous further automatic pre- and postprocessing steps that
-include orienting, anchoring, and packing of components, to name a few.
-
-The bottom line is that the graph drawing engine makes it easy
-to try out new graph drawing algorithms for medium sized graphs (up
-to a few hundred nodes) in Lua. For larger graphs, C/C++ code must be
-used.
-
-
-\subsection{The Layers of the Graph Drawing System}
-\label{section-gd-layers}
-
-Even though the graph drawing system presented in the following sections was
-developed as part of \pgfname, it can be used independently of \pgfname\ and
-\tikzname: It was (re)designed so that it can be used by arbitrary programs as
-long as they are able to run Lua. To achieve this, the graph drawing system
-consists of three layers:
-%
-\begin{enumerate}
- \item At the ``bottom'' we have the \emph{algorithmic layer}. This layer,
- written in Lua, contains all graph drawing algorithms. Interestingly,
- options must also be declared on this layer, so an algorithm together
- with all options it uses can and must be specified entirely on this
- layer. If you intend to implement a new graph drawing algorithm, you
- will only be interested in the functionality of this layer.
-
- Algorithm ``communicate'' with the graph drawing system through a
- well-defined interface, encapsulated in the class
- |InterfaceToAlgorithms|.
- \item At the ``top'' we have the \emph{display layer}. This layer is not
- actually part of the graph drawing system. Rather, it is a piece of
- software that ``displays'' graphs and \tikzname\ is just one example of
- such a software. Another example might be a graph editor that uses the
- graph drawing system to lay out the graph it displays. Yet another
- example might be a command line tool for drawing graphs described in a
- file. Finally, you may also wish to use the graph drawing system as a
- simple subroutine for rendering graphs produced in a larger program.
-
- Since the different possible instantiations of the display layer are
- quite heterogeneous, all display layers must communicate with the graph
- drawing system through a special interface, encapsulated in the class
- |InterfaceToDisplay|.
-
- The main job of this class is to provide a set of methods for
- specifying that a graph has certain nodes and edges and that certain
- options have been set for them. However, this interface also allows you
- to query all options that have been declared by algorithms, including
- their documentation. This way, an editor or a command line tool can
- display a list of all graph drawing algorithms and how they can be
- configured.
- \item The algorithm layer and the display layer are ``bound together''
- through the \emph{binding layer}. Most of the bookkeeping concerning
- the to-be-drawn graphs is done by the graph drawing system
- independently of which algorithm is used and also independently of
- which display layer is used, but some things are still specific to each
- display layer. For instance, some algorithms may create new nodes and
- the algorithms may then need to know how large these nodes will be. For
- this, the display layer must be ``queried'' during a run of the
- algorithm -- and it is the job of the binding layer to achieve this
- callback.
-
- As a rule, the binding layer implements the ``backward'' communication
- from the graph drawing system back to the display layer, while the
- display layer's interface class provides only functions that are called
- from the display layer but which will not ``talk back''.
-\end{enumerate}
-
-All of the files concerned with graph drawing reside in the |graphdrawing|
-subdirectory of |generic/pgf|.
-
-
-\subsection{Organisation of the Graph Drawing Documentation}
-
-The documentation of the graph drawing engine is structured as follows:
-%
-\begin{enumerate}
- \item Following this overview section, the next section documents the graph
- drawing engine from ``the \tikzname\ user's point of view''. No
- knowledge of Lua or algorithmic graph drawing is needed for this
- section, everyone who intends to use algorithmic graph drawing in
- \tikzname\ may be interested in reading it.
- \item You will normally only use \tikzname's keys and commands in order to
- use the graph drawing system, but, internally, these keys call more
- basic \pgfname\ commands that do the ``hard work'' of binding the world
- of \TeX\ boxes and macros to the object-oriented world of Lua.
- Section~\ref{section-gd-pgf} explains how this works and which commands
- are available for authors of packages that directly need to use the
- graph drawing system inside \pgfname, avoiding the overhead incurred by
- \tikzname.
-
- Most readers can safely skip this section.
- \item The next sections detail which graph drawing algorithms are currently
- implemented as part of the \tikzname\ distribution, see
- Sections~\ref{section-first-graphdrawing-library-in-manual}
- to~\ref{section-last-graphdrawing-library-in-manual}.
- \item Section~\ref{section-gd-algorithm-layer} is addressed at readers who
- wish to implement their own graph drawing algorithms. For this,
- \emph{no knowledge at all} of \TeX\ programming is needed. The section
- explains the graph model used in Lua, the available libraries, the
- graph drawing pipeline, and everything else that is part of the Lua
- side of the engine.
- \item Section~\ref{section-gd-display-layer} details the display layer of
- the graph drawing system. You should read this section if you wish to
- implement a new display system (that is, a non-\TeX-based program) that
- intends to use the graph drawing system.
- \item Section~\ref{section-gd-binding-layer} explains how binding layers
- can be implemented. This section, too, is of interest only to readers
- who wish to write new display systems.
-\end{enumerate}
-
-
-\subsection{Acknowledgements}
-
-Graph drawing in \tikzname\ began as a student's project under my supervision.
-Ren\'ee Ahrens, Olof-Joachim Frahm, Jens Kluttig, Matthias Schulz, and Stephan
-Schuster wrote the first prototype of a graph drawing system inside \tikzname\
-that uses Lua\TeX\ for the implementation of graph drawing algorithms.
-
-This first, early version was greatly extended on the algorithmic side by
-Jannis Pohlmann who wrote his Diploma thesis on graph drawing under my
-supervision. He implemented, in particular, the Sugiyama method
-(|layered layout|) and force based algorithms. Also, he rewrote some of the
-code of the prototype.
-
-At some point it became apparent that the first implementation had a number of
-deficiencies, both concerning the structure, the interfaces, and (in
-particular) the performance. Because of this, I rewrote the code of the graph
-drawing system, both on the \TeX\ side and on the Lua side in its current form.
-However, I would like to stress that without the work of the people mentioned
-above graph drawing in \tikzname\ would not exist.
-
-The documentation was written almost entirely by myself, though I did copy some
-paragraphs from Jannis's Diploma thesis, which I can highly recommend everyone
-to read.
-
-In the future, I hope that other people will contribute algorithms, which will
-be available as libraries.
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-phylogenetics.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-phylogenetics.tex
deleted file mode 100644
index d6ce489fc5..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-phylogenetics.tex
+++ /dev/null
@@ -1,83 +0,0 @@
-% Copyright 2018 by Sarah Mäusle and 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{Graph Drawing Layouts: Phylogenetic Trees}
-\label{section-library-graphdrawing-phylogenetics}
-
-{\noindent {\emph{by Sarah Mäusle and Till Tantau}}}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-\tikzset{/graph drawing/phylogenetic inner node/.style={
- /tikz/.cd,
- draw, circle, inner sep=0pt, minimum size=5pt}
-}
-\tikzset{/graph drawing/phylogenetic edge/.style={
- /tikz/.cd,
- thick, rounded corners,edge node={node[auto,font=\tiny, inner sep=2pt]{}}}
-}
-
-\includeluadocumentationof{pgf.gd.phylogenetics.library}
-\includeluadocumentationof{pgf.gd.phylogenetics.PhylogeneticTree}
-
-
-\subsection{Generating a Phylogenetic Tree}
-
-... \todosp{I guess something should be added here, right?}
-
-When a phylogenetic tree is generated, new nodes and edges get created. In
-order to give you a chance at styling them, the following styles are executed:
-
-\begin{stylekey}{/graph drawing/phylogenetic inner node}
- The style is added every newly created inner node. In this manual, this key
- is set to:
- %
-\begin{codeexample}[code only]
-\pgfgdset{phylogenetic inner node/.style={
- /tikz/.cd, draw, circle, inner sep=0pt, minimum size=5pt
- }
-}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/graph drawing/phylogenetic edge=\meta{length}}
- The style is added every newly created phylogenetic edge. The \meta{length}
- will be set to the computed evolutionary length of the edge. In this
- manual, this key is set to:
- %
-\begin{codeexample}[code only]
-\pgfgdset{phylogenetic edge/.style={
- /tikz/.cd, thick, rounded corners
- }
-}
-\end{codeexample}
- %
-\end{stylekey}
-
-\includeluadocumentationof{pgf.gd.phylogenetics.AuthorDefinedPhylogeny}
-\includeluadocumentationof{pgf.gd.phylogenetics.SokalMichener1958}
-\includeluadocumentationof{pgf.gd.phylogenetics.BalancedMinimumEvolution}
-\includeluadocumentationof{pgf.gd.phylogenetics.BalancedNearestNeighbourInterchange}
-
-
-\subsection{Laying out the Phylogram}
-
-\includeluadocumentationof{pgf.gd.phylogenetics.Maeusle2012}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-trees.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-trees.tex
deleted file mode 100644
index ea18363172..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-trees.tex
+++ /dev/null
@@ -1,39 +0,0 @@
-% Copyright 2018 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{Graph Drawing Layouts: Trees}
-\label{section-first-graphdrawing-library-in-manual}
-\label{section-library-graphdrawing-trees}
-
-{\noindent {\emph{by Till Tantau}} \todosp{why 2 labels? The second doesn't
-seem to be used.}}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-\includeluadocumentationof{pgf.gd.trees.library}
-
-
-\subsection{The Tree Layouts}
-
-\includeluadocumentationof{pgf.gd.trees.ReingoldTilford1981}
-
-% Other subsections:
-\includeluadocumentationof{pgf.gd.trees.ChildSpec}
-\includeluadocumentationof{pgf.gd.trees.SpanningTreeComputation}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-usage-pgf.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-usage-pgf.tex
deleted file mode 100644
index be04bb93d4..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-usage-pgf.tex
+++ /dev/null
@@ -1,688 +0,0 @@
-% Copyright 2010-2019 by Renée Ahrens
-% Copyright 2010-2019 by Olof Frahm
-% Copyright 2010-2019 by Jens Kluttig
-% Copyright 2010-2019 by Matthias Schulz
-% Copyright 2010-2019 by Stephan Schuster
-% Copyright 2019 by Jannis Pohlmann
-% 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{Using Graph Drawing in PGF}
-\label{section-gd-pgf}
-
-{\noindent {\emph{by Till Tantau}}}
-
-\begin{purepgflibrary}{graphdrawing}
- This package provides the core support for graph drawing inside \pgfname.
- It does so by providing \pgfname\ macros for controlling the graph drawing
- system, but also implements the binding to the graph drawing system (see
- Section~\ref{section-gd-binding-layer} for details on bindings).
-\end{purepgflibrary}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-
-\subsection{Overview}
-
-Just like everywhere else in \pgfname, \tikzname\ is ``just a convenient
-syntax'' in the context of graph drawing. The ``hard work'' of binding the
-internal representations of nodes and edges with the graph drawing system
-written in Lua is not done by \tikzname, but rather by a set of macros that are
-part of the basic \pgfname\ layer.
-
-The documentation of the \pgfname\ part of the graph drawing system that is
-presented in the following includes only those macros that other \TeX\ packages
-could conceivably call in order to use the graph drawing system without using
-\tikzname; for instance, for efficiency reasons. (The internal callback
-functions defined in the |graphdrawing| library that are part of the binding
-between \pgfname\ and the graph drawing system are not documented, should not
-be called, and may change in the future.)
-
-
-\subsection{How Graph Drawing in PGF Works}
-
-The core idea behind graph drawing in \pgfname\ is that inside special
-\emph{graph drawing scopes} whenever \pgfname\ creates a node, we intercept
-this node creation and \emph{do not} immediately place the node. Rather, we
-pass it down to Lua part of the graph drawing system via calls to appropriate
-methods of the (Lua) class |InterfaceToDisplay|. The effect will be that the
-nodes are ``tucked away'' in some internal tables. For edges, we introduce a
-special command called |\pgfgdedge| that tells the graph drawing system that
-there is an edge between two tucked-away nodes. Then, at the end of the graph
-drawing scope, a graph drawing algorithm written in Lua starts to work on the
-graph by computing new positions for the nodes. Once the algorithm has
-finished, the graph drawing system starts sending back the nodes and edges to
-\pgfname\ via the methods of the class |BindingToPGF|. These methods reinsert
-some code into the \TeX\ output stream that finally places the nodes at their
-final positions. Note that graph drawing algorithms are perfectly oblivious to
-all of this; indeed, the graph drawing algorithms can even be used
-independently of \TeX.
-
-Let us have a look at a simple example to see what happens when a graph is
-specified:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{trees}}]
-\tikz[tree layout]
- \graph {root [as=Hello] -> World[fill=blue!20]};
-\end{codeexample}
-
-The key |tree layout| internally calls the key |request scope and layout|,
-which in turn calls the macro |\pgfgdbeginscope|, which starts a graph drawing
-scope inside the graph drawing system. Once this macro has been called, until
-the next call of |\pgfgdendscope|, all nodes that are created actually get
-passed down to the graph drawing engine. This is implemented on the lowest
-layer, namely by directly intercepting nodes freshly created using |\pgfnode|.
-In our example, this happens in two places: For the |root| node and for the
-|World| node. The |graphs| library and \tikzname\ internally call the
-|\pgfnode| macro for these two nodes (after a large number of internal syntax
-translations, but the graph drawing system does not care about them).
-
-Note that the node boxes will have been fully created before they are passed
-down to the graph drawing engine -- only their final position is not yet fixed.
-It is not possible to modify the size of nodes inside the graph drawing engine,
-but you can create new nodes in certain situations.
-
-In contrast, the single edge of the graph that is created by the |->| command
-is not fully created before it is passed down to the graph drawing system. This
-would not really make sense since before the final positions of the nodes are
-fixed, we cannot even begin to compute the length of this edge, let alone where
-it should start or end. For this reason, on the upper \tikzname\ layer, the
-normal edge creation that would be caused by |->| via |new ->| is suppressed.
-Instead, the command |\pgfgdedge| is called. Similarly, inside a graph drawing
-scope, \tikzname\ will suppress both the |edge| and the |edge from parent|
-command and cause |\pgfgdedge| to be called instead.
-
-An overview of what happens is illustrated by the following call graph:
-
-\bigskip
-
-\begin{tikzpicture}[
- class name/.style={draw,minimum size=20pt, fill=blue!20},
- object node/.style={draw,minimum size=15pt, fill=yellow!20},
- p/.style={->,>={Stealth[round,sep]}},
- livespan/.style={very thick},
- xscale=0.8,
-]
- % class names above
- \node (tikz) at (0,4) [class name] {\tikzname\ layer (\TeX)};
- \node (tex) at (6,4) [class name] {\pgfname\ layer (\TeX)};
- \node (interface) at (13,4) [class name] {Display layer (Lua)};
- % lines from the class names to the bottom of the picture
- \draw[livespan] (tikz) -- (0,-6.5);
- \draw[livespan] (tex) -- (6,-6.5);
- \draw[livespan] (interface) -- (13,-6.5);
- % first command: \graph{ -- generates new graph in lua interface
- \node (tikz-begin-graph) at (0,3) [object node] {|\graph[... layout]{|}; %}
- \node (tex-begin-graph) at (6,3) [object node] {|\pgfgdbeginscope|};
- \node (interface-new-graph) at (13,3) [object node] {|beginGraphDrawingScope(|...|)|};
- \draw [p] (tikz-begin-graph.east) -- (tex-begin-graph.west);
- \draw [p] (tex-begin-graph.east) -- (interface-new-graph.west);
- % second command: a -> b -- generates two nodes in lua
- % and one edge
- \node (tikz-node) at (0,2) [object node] {|a -> b;|};
- \node (tex-node) at (6,2) [object node, double copy shadow] {|\pgfnode|};
- \draw[p] (tikz-node.east) -- (tex-node.west);
-
- \node (interface-add-node) at (13,2) [object node, double copy shadow] {|createVertex(|...|)|};
- \draw[p] (tex-node.east) -- (interface-add-node.west);
-
- \node (tex-add-edge) at (6,1) [object node, double copy shadow] {|\pgfgdedge|};
- \node (interface-add-edge) at (13,1) [object node, double copy shadow] {|createEdge(|...|)|};
- \draw[p] (tikz-node.east) -- (1.5,2) -- (1.5,1) -- (tex-add-edge.west);
- \draw[p] (tex-add-edge.east) -- (interface-add-edge.west);
-
- % scope ends -- cloes graph, layouts it and draws it
- \node (tikz-end) at (0,0) [object node] {|};|};
- \node (tex-end) at (6,0) [object node] {|\pgfgdendscope|};
- \node (interface-draw-graph) at (13,0) [object node] {|runGraphDrawingAlgorithm()|};
- \node (interface-finish-graph) at (13,-2) [object node] {|endGraphDrawingScope()|};
-
- \node (invoke-algorithm) at (15.5,-1) [object node] {invoke algorithm};
- \draw[p] (tikz-end.east) -- (tex-end.west);
- \draw[p] (tex-end.east) -- (interface-draw-graph.west);
- \draw[p] (interface-draw-graph.east) -| (invoke-algorithm.20);
- \draw[p] (tex-end.east) -- (9.5,0) -- (9.5,-2) -- (interface-finish-graph.west);
-
- % begin shipout
- \node (tex-begin-shipout) at (6,-3) [object node] {|\pgfgdcallbackbeginshipout|};
-
- \node (tex-puttexbox) at (6,-4) [object node, double copy shadow] {|\pgfgdcallbackrendernode|};
- \node (tex-putedge) at (6,-5) [object node, double copy shadow] {|\pgfgddefaultedgecallback|};
-
- \node (tex-end-shipout) at (6,-6) [object node] {|\pgfgdcallbackendshipout|};
-
- \draw [p] (interface-finish-graph.-170) |- (tex-begin-shipout.east);
- \draw [p] (interface-finish-graph.-170) |- (tex-puttexbox.east);
- \draw [p] (interface-finish-graph.-170) |- (tex-putedge.east);
- \draw [p] (interface-finish-graph.-170) |- (tex-end-shipout.east);
- %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-4) -- (sys-puttexbox.west);
-
- % put edge
- %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-5) -- (sys-put-edge.west);
- % end shipout
- %(interface-finish-graph.east) -- (12.5,-2) -- (12.5,-6) -- (sys-end-shipout.west);
-\end{tikzpicture}
-\medskip
-
-The above diagram glosses over the fact that the display layer does not
-actually call any of the macros of \TeX\ directly, but uses a so called
-\emph{binding} (see the class |BindingToPGF|). However, this will not be
-important for the present section since you cannot access the binding directly.
-
-
-\subsubsection{Graph Drawing Scopes}
-\label{section-gd-scopes}
-
-When the graph drawing system is active, some pretty basic things inside
-\pgfname\ change -- such as the fact that nodes are no longer created in the
-normal manner. For this reason, the graph drawing system must be switched on
-and of explicitly through opening and closing a so called \emph{graph drawing
-scope}. These scopes can, in principle, be nested, namely a graph contains a
-node that contains some text that in turn contains a subpicture that contains a
-drawing of a graph. However, this is \emph{not} the same as subgraphs nodes and
-sublayouts, which are all part of the same graph drawing scope. Normally, graph
-drawing scopes are not nested.
-
-Graph drawing scopes are created using the following commands:
-
-\begin{command}{\pgfgdbeginscope}
- This macro starts a \TeX\ scope inside which the following things happen:
- %
- \begin{enumerate}
- \item The display layer method |beginGraphDrawingScope| is called,
- which created a new graph drawing scope inside the graph drawing
- system and places it on top of an internal stack. From now on, all
- subsequent interface calls will refer to this scope until
- |\pgfgdendscope| is called, which will pop the scope once more.
- \item Inside the \TeX\ scope, nodes are not placed immediately. Rather,
- |\pgfpositionnodelater|, see
- Section~\ref{section-shapes-deferred-node-positioning}, is used to
- call |InterfaceToDisplay.createVertex| for all nodes created inside
- the scope. This will cause them to be put inside some internal
- table.
- \item Some additional \meta{code} is executed, which has been set using
- the following command:
- %
- \begin{command}{\pgfgdaddspecificationhook\marg{code}}
- This command adds the \meta{code} to the code that is executed
- whenever a graph drawing scope starts. For instance, the
- \tikzname\ library |graphdrawing| uses this macro to add some
- \meta{code} that will redirect the |edge| and
- |edge from parent| path commands to |\pgfgdedge|.
- \end{command}
- \item |\pgftransformreset| is called.
- \item The following \TeX-if is set to true:
- {
- \let\ifpgfgdgraphdrawingscopeactive=\relax
- \begin{textoken}{\ifpgfgdgraphdrawingscopeactive}
- Will be true inside a graph drawing scope.
- \end{textoken}
- }
- \end{enumerate}
- %
- The above has a number of consequences for what can happen inside a graph
- drawing scope:
- %
- \begin{itemize}
- \item Since nodes are not actually created before the end of the scope,
- you cannot reference these nodes. Thus, you cannot write
- %
-\begin{codeexample}[code only]
-\tikz [spring layout] {
- \node (a) {a};
- \node (b) {b};
- \draw (a) -- (b);
-}
-\end{codeexample}
- %
- The problem is that we cannot connect |(a)| and |(b)| via a
- straight line since these nodes do not exist at that point (they
- are available only deeply inside the Lua).
- \item In order to create edges between nodes inside a graph drawing
- scope, you need to call the |\pgfgdedge| command, described below.
- \end{itemize}
-
- Additionally, when \tikzname\ is used, the following things also happen:
- %
- \begin{itemize}
- \item If the |graphs| library has been loaded, the default positioning
- mechanisms of this library are switched off, leaving the
- positioning to the graph drawing engine. Also, when an edge is
- created by the |graphs| library, this is signalled to the
- |graphdrawing| library. (To be more precise: The keys |new ->| and
- so on are redefined so that they call |\pgfgdedge| instead of
- creating an edge.
- \item The |edge| path command is modified so that it also calls
- |\pgfgdedge| instead of immediately creating any edges.
- \item The |edge from parent| path command is modified so that is also
- calls |\pgfgdedge|.
- \item The keys |append after command| and |prefix after command| keys
- are modified so that they are executed only via |late options| when
- the node has ``reached its final parking position''.
- \end{itemize}
-
- Note that inside a graph drawing scope you first have to open a (main)
- layout scope (using the |\pgfgdbeginlayout| command described later on)
- before you can add nodes and edges to the scope.
-\end{command}
-
-\begin{command}{\pgfgdendscope}
- This macro is used to end a graph drawing scope. It must be given on the
- same \TeX\ grouping level as the corresponding |\pgfgdbeginscope|. When the
- macro is called, it triggers a lot of new calls:
- %
- \begin{enumerate}
- \item The special treatment of newly created boxes is ended. Nodes are
- once more created normally.
- \item The effects of the \meta{code} that was inserted via the
- specification hook command also ends (provided it had no global
- effects).
- \item We call |InterfaceToDisplay.runGraphDrawingAlgorithm|. This will
- cause the algorithm(s) for the graph to be executed (since a graph
- can have sublayouts, several algorithms may be run). See
- Section~\ref{section-gd-layout-scopes} below.
- \item Next, we call |InterfaceToDisplay.endGraphDrawingScope|. This
- causes all nodes that were intercepted during the graph drawing
- scope to be reinserted into the output stream at the positions that
- were computed for them. Also, for each edge that was requested via
- |\pgfgdedge|, the callback macro is called (see below).
- \end{enumerate}
-\end{command}
-
-Inside a graph drawing scope, nodes are automatically passed down to the graph
-drawing engine, while for edges a command has to be called explicitly:
-
-\begin{command}{\pgfgdedge\marg{first node}\marg{second node}\marg{edge direction}\marg{edge options}\marg{edge nodes}}
- This command is used to tell the graph drawing engine that there is an edge
- between \meta{first node} and \meta{second node} in your graph. The
- ``kind'' of connection is indicated by \meta{direction}, which may be one
- of the following:
- %
- \begin{itemize}
- \item |->| indicates a directed edge (also known as an arc) from
- \meta{first node} to \meta{second node}.
- \item |--| indicates an undirected edge between \meta{first node} and
- \meta{second node},
- \item |<-| indicates a directed edge from \meta{second node} to
- \meta{first node}, but with the ``additional hint'' that this is a
- ``backward'' edge. A graph drawing algorithm may or may not take
- this hint into account.
- \item |<->| indicates a bi-directed edge between \meta{first node} and
- \meta{second node}.
- \item |-!-| indicates that the edge from \meta{first node} to
- \meta{second node} is ``missing''.
- \end{itemize}
- %
- Note that in all cases, the syntactic digraph will contain an arc from
- \meta{first node} to \meta{second node}, regardless of the value of
- \meta{direction}. The \meta{direction} is ``just'' a ``semantic
- annotation''.
-
- The parameters \meta{edge options} and \meta{edge nodes} are a bit more
- tricky. When an edge between two vertices of a graph is created via
- |\pgfgdedge|, nothing is actually done immediately. After all, without
- knowing the final positions of the nodes \meta{first node} and \meta{second
- node}, there is no way of creating the actual drawing commands for the
- edge. Thus, the actual drawing of the edge is done only when the graph
- drawing algorithm is done (namely in the macro |\pgfgdedgecallback|, see
- later).
-
- Because of this ``delayed'' drawing of edges, options that influence the
- edge must be retained until the moment when the edge is actually drawn.
- Parameters \meta{edge options} and \meta{edge nodes} store such options.
-
- Let us start with \meta{edge options}. This parameter should be set to a
- list of key--value pairs like
- %
-\begin{codeexample}[code only]
-/tikz/.cd, color=red, very thick, orient=down
-\end{codeexample}
- %
- Some of these options may be of interest to the graph drawing algorithm
- (like the last option) while others will only be important during the
- drawing of edge (like the first option). The options that are important for
- the graph drawing algorithm must be pushed onto the graph drawing system's
- option stack.
-
- The tricky part is that options that are of interest to the graph drawing
- algorithm must be executed \emph{before} the algorithm starts, but the
- options as a whole are usually only executed during the drawing of the
- edges, which is \emph{after} the algorithm has finished. To overcome this
- problem, the following happens:
-
- The options in \meta{edge options} are executed ``tentatively'' inside
- |\pgfgdedge|. However, this execution is done in a ``heavily guarded
- sandbox'' where all effects of the options (like changing the color or the
- line width) do not propagate beyond the sandbox. Only the changes of the
- graph drawing edge parameters leave the sandbox. These parameters are then
- passed down to the graph drawing system.
-
- Later, when the edge is drawn using |\pgfgdedgecallback|, the options
- \meta{edge options} are available once more and then they are executed
- normally.
-
- Note that when the options in \meta{edge options} are executed, no path is
- preset. Thus, you typically need to start it with, say, |/tikz/.cd|. Also
- note that the sandbox is not perfect and changing global values will have
- an effect outside the sandbox. Indeed, ``putting things in a sandbox'' just
- means that the options are executed inside a \TeX\ scope inside an
- interrupted path inside a \TeX\ box that is thrown away immediately.
-
- The text in \meta{edge nodes} is some ``auxiliary'' text that is simply
- stored away and later directed to |\pgfgdedgecallback|. This is used for
- instance by \tikzname\ to store its node labels.
-\end{command}
-
-\begin{command}{\pgfgdsetedgecallback\marg{macro}}
- This command allows you to change the \meta{macro} that gets called form
- inside the graph drawing system at the end of the creation of a graph, when
- the nodes have been positioned. The \meta{macro} will be called once for
- each edge with the following parameters:
- %
- \begin{quote}
- \meta{macro}\marg{first node}\marg{second node}\marg{direction}\marg{edge options}\marg{edge nodes}\\
- \marg{algorithm-generated options}\marg{bend information}\marg{animations}
- \end{quote}
-
- The first five parameters are the original values that were passed down to
- the |\pgfgdedge| command.
-
- The \meta{algorithm-generated options} have been ``computed by the
- algorithm''. For instance, an algorithm might have determined, say, flow
- capacities for edges and it might now wish to communicate this information
- back to the upper layers. These options should be executed with the path
- |/graph drawing|.
-
- The parameter \meta{bend information} contains algorithmically-computed
- information concerning how the edge should bend. This will be a text like
- |(10pt,20pt)--(30pt,40pt)| in \tikzname-syntax and may include the path
- commands |--|, |..| (followed by Bézier coordinates), and |--cycle|.
-
- The parameter \meta{animations} contains algorithmically-generated
- animation commands (calls to |\pgfanimateattribute|. The |whom| will be set
- to |pgf@gd|.
-
- The default \meta{macro} simply draws a line between the nodes. When the
- |graphdrawing| library of the \tikzname\ layer is loaded, a more fancy
- \meta{macro} is used that takes all of the parameters into account.
-\end{command}
-
-
-\subsection{Layout Scopes}
-\label{section-gd-layout-scopes}
-
-As described in Section~\ref{section-gd-sublayouts}, the graph drawing engine
-does not always apply only a single algorithm. Rather, several different
-algorithm may be applied to different parts of the graph. How this happens,
-exactly, is governed by a hierarchy of layouts, which are setup using the
-commands |\pgfgdbeginlayout| and |\pgfgdendlayout|.
-
-\begin{command}{\pgfgdbeginlayout}
- This command first starts a new \TeX\ scope and then informs the display
- layer that a new (sub)layout should be started. For each graph there may be
- a hierarchy of layouts, each of which contains a certain number of vertices
- and edges. This hierarchy is created through calls to this macros and the
- corresponding calls of |\pgfgdendlayout|. For each graph drawing scope
- there has to be exactly one main layout that encompasses all nodes and
- edges and also all sublayouts. Thus, after a graph drawing scope has been
- opened, a layout scope also needs to be opened almost immediately.
-
- For each layout created via this macro, a graph drawing algorithm will be
- run later on the subgraph of all nodes that make up the layout. Which
- algorithm is run for the layout is dictated by which layout key (one of the
- |... layout| keys) is ``in force'' when the macro is called. Thus, using a
- layout key for selecting an algorithm must always be done \emph{before} the
- layout is started. (However, see the discussion of layout keys in the next
- subsection for more details on what really happens.)
-
- A vertex can be part of several layouts, either because they are nested or
- because they overlap (this happens when a node is later on added to another
- layout by calling |\pgfgdsetlatenodeoption|). This means that it is not
- immediately obvious how conflicts arising from the different ways different
- algorithms ``would like to place nodes'' should be resolved. The method for
- this resolving is detailed in Section~\ref{section-gd-layout-resolve}.
-\end{command}
-
-\begin{command}{\pgfgdendlayout}
- This command ends the \TeX\ scope of the current layout. Once closed, no
- nodes or edges can be added to a layout.
-\end{command}
-
-\begin{command}{\pgfgdsetlatenodeoption\marg{node name}}
- This command can only be called when the node named \meta{node name} has
- already been created inside the current graph drawing scope. The effect of
- calling this macro will be that all options currently on the graph drawing
- system's option stack will be added to the node's option, possibly
- overwriting the original option settings. Furthermore, the node will become
- part of all layouts currently on the option stack. This means that you can
- use this command to add a node to several layouts that are not included in
- one another.
-\end{command}
-
-
-\subsection{Layout Keys}
-
-\emph{Layout keys} are keys like |tree layout| or |layered layout| that are
-used to select a specific graph drawing algorithm. From the graph drawing
-system's point of view, these keys ``just'' select an algorithm and when
-several layout keys are used in a row, the last one would ``win''; just as when
-you say |orient=90| directly followed by |orient=0|, the result is that the
-|orient| key is set to |0| because the last key ``wins''.
-
-Unfortunately, if keys like |tree layout| were ``just'' to select an algorithm,
-we would still need a key or some special syntax to actually start a
-(sub)layout. In early versions of the system this was exactly what people had
-to do and this was somewhat awkward. Because of this problem, the behavior of
-the layout keys in \pgfname\ (and only there, other display layers need to
-implement their own behavior) is now a bit more involved. When you use a key
-like |tree layout| (more precisely, any key that was declared as an algorithm
-key on the algorithm layer of the graph drawing system) in any scope in
-\pgfname, the following happens:
-%
-\begin{enumerate}
- \item The graph drawing system is told that a specific algorithm has been
- selected (the Reingold--Tilford-algorithm in this case; this
- information was communicated to the graph drawing system during the
- declaration of the algorithm). Being ``told'' about this means that a
- special entry is pushed onto the current options stack of the graph
- drawing system.
- \item An internal ``request'' for a ``scope and a layout'' is made. This
- has several effects:
- \item We first test whether we are already inside a layout scope. If not,
- we use |\pgfgdbeginscope| to open a graph drawing scope. This scope
- will be closed appropriately (see |\pgfgdsetrequestcallback| for
- details).
- \item Next, a layout scope is opened using |\pgfgdbeginlayout|. It will
- also be closed appropriately.
-\end{enumerate}
-
-The net effect of the above is that the first use of a layout key in a picture
-starts both a graph drawing scope and also a main layout, while subsequent uses
-of layout keys inside a picture will only open sublayouts.
-
-\begin{command}{\pgfgdsetrequestcallback\marg{macro}}
- This command sets up \meta{macro} as the macro that is called whenever a
- layout key ``requests'' that a layout and, possibly, a graph drawing scope
- is opened. When \meta{macro} is called, it gets two parameters, the
- \meta{begin code} and the \meta{end code}. In addition to whatever setup
- the \meta{macro} would like to do, it should execute the \meta{begin code}
- at the beginning of a \TeX\ scope (the code will open graph drawing and
- layout scopes) and the \meta{end code} at the end of the same \TeX\ scope.
-
- The need for this slightly strange macro arises from the fact that in
- \tikzname\ we often write things like |[spring layout,node sep=2cm]|. The
- point is that when the |spring layout| key is executed, we do \emph{not}
- wish to open a layout scope immediately. Rather, this should happen only
- after the option |nodes sep=2cm| has been executed. For this reason,
- \tikzname\ sets up a special \meta{macro} that ``delays'' the execution of
- the \meta{begin code} until the end of the opening of the next scope.
-
- Because of this, in \tikzname\ layout keys can only be used as an option
- when a \tikzname\ scope is started. Thus, you can pass them to |\tikz|, to
- |{tikzpicture}|, to |\scoped|, to |{scope}|, to |graph|, and to |{graph}|.
- For instance, the |tree layout| option can be used in the following ways:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{trees}}]
-\tikz [tree layout] \graph {1 -> {b,c}};
-\tikz \graph [tree layout] {2 -> {b,c}};
-\tikz \path graph [tree layout] {3 -> {b,c}};
-
-\begin{tikzpicture}[tree layout]
- \graph {4 -> {b,c}};
-\end{tikzpicture}
-
-\begin{tikzpicture}
- \scoped [tree layout] \graph {5 -> {b,c}};
-
- \begin{scope}[tree layout, xshift=1.5cm]
- \graph {6 -> {b,c}};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
- You can \emph{not} use layout keys with a single node or on a path. In
- particular, to typeset a tree given in the |child| syntax somewhere inside
- a |{tikzpicture}|, you must prefix it with the |\scoped| command:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphdrawing}
-\usegdlibrary{trees}}]
-\begin{tikzpicture}
- \scoped [tree layout]
- \node {root}
- child { node {left child} }
- child { node {right child} };
-\end{tikzpicture}
-\end{codeexample}
- %
- Naturally, the above could have been written more succinctly as
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphdrawing}
-\usegdlibrary{trees}}]
-\tikz [tree layout]
- \node {root}
- child { node {left child} }
- child { node {right child} };
-\end{codeexample}
- %
- Or even more succinctly:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{trees}}]
-\tikz \graph [tree layout] { root -- {left child, right child} };
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Parameters}
-\label{section-gd-parameters}
-
-When a graph drawing algorithm starts working, a set of options, called ``graph
-drawing parameters'' or just ``parameters'' can influence the way the algorithm
-works. For instance, a graph drawing parameter might be the average distance
-between vertices which the algorithm should take into account. Another example
-might be the fact the certain nodes are special nodes and that a certain edge
-should have a large label.
-
-These graph drawing parameters are different from ``usual'' \pgfname\ options:
-An algorithmic parameter influences the way the algorithm works, while usual
-options influence the way the result looks like. For instance, the fact that a
-node is red is not a graph drawing parameter, while the shape of a node might
-be an graph drawing parameter.
-
-The possible graph parameters are declared by the algorithmic layer through the
-|declare| method; you cannot declare parameters on the \pgfname\ layer since
-this would not be compatible across different display systems.
-
-Users use a graph parameter in the same way as a normal key. The difference is
-that each time a key representing a graph drawing parameter is used, a special
-function of the graph drawing system's interface is called to ``push'' the
-parameter onto an internal option stack (and elements are popped from this
-stack whenever the \TeX\ scope closes in which the key was used).
-
-The net effect of all of this is that the graph drawing system keeps track of a
-stack of option in parallel to \TeX. You cannot, however, access the current
-values of graph drawing parameters from \TeX\ since they are tucked away deep
-inside the graph drawing system.
-
-
-\subsection{Events}
-
-\emph{Events} are used to pass information from the parser about the syntactic
-structure of a graph to graph drawing algorithms. Consider, for instance, a
-graph that is actually a tree in which some node ``misses'' its first child. In
-this case, the information that the child is missing is neither part of any
-node (because the node is missing, after all) nor is it an option of the whole
-graph. However, events are created by the parser the allow an algorithm to
-reconstruct the fact that the child is missing. Naturally, graph drawing
-algorithms may choose to ignore events and most will.
-
-Most of the creation and handling of events is done automatically. The only
-reason you might wish to use the following commands is when you write a
-``parser extension'' together with a new graph drawing algorithm. For instance,
-you might come up with new options that, when used, trigger events.
-
-\begin{command}{\pgfgdevent\marg{kind}\marg{parameter}}
- Calls |createEvent| of the graph drawing system's interface class. This
- creates a new |Event| object on the Lua layer whose |kind| field is set to
- \meta{kind} and the |parameters| field to \meta{parameter}. You must be
- inside a graph drawing scope to use this command.
-\end{command}
-
-\begin{command}{\pgfgdbegineventgroup\marg{parameter}}
- Starts an event group. This just means that an |Event| of kind |begin| is
- created with the given \meta{parameter}.
-\end{command}
-
-\begin{command}{\pgfgdendeventgroup}
- Ends an event group. This is done by adding an event of kind |end| without
- any parameters to the event string.
-\end{command}
-
-\begin{command}{\pgfgdeventgroup\marg{parameters}}
- Starts an event group just like |\pgfgdbegineventgroup|, but adds a
- corresponding closing |end| event at the end of the current \TeX\ group
- (using |\aftergroup|).
-\end{command}
-
-
-\subsection{Subgraph Nodes}
-
-\begin{command}{\pgfgdsubgraphnode\marg{name}\marg{node options}\marg{node text}}
- A subgraph node is a node that ``surrounds'' the nodes of a subgraph. The
- special property of a subgraph node opposed to a normal node is that it is
- created only after the subgraph has been laid out. However, the difference
- to a collection like |hyper| is that the node is available immediately as a
- normal node in the sense that you can connect edges to it.
-
- What happens internally is that subgraph nodes get ``registered''
- immediately both on the \pgfname\ level and on the Lua level, but the
- actual node is only created inside the layout pipeline using a callback.
- The actual node creation happens when the innermost layout in which the
- subgraph node is declared has finished.
-
- When you create a subgraph node using this macro, you also start a
- collection (of an internal kind) that stores the subgraph. All following
- nodes in the current \TeX\ scope will become part of this collection.
-
- The \meta{name} is the node name by which you can refer to this node in the
- following. The \meta{node options} are normal \pgfname\ options (like |red|
- or |draw| or |circle|) that will influence the appearance when it is
- created later on. The \meta{node text} is the text that will be passed to
- |\pgfnode| upon creation of the node.
-
- See |InterfaceToDisplay.pushSubgraphVertex| for more details.
-\end{command}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-usage-tikz.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-usage-tikz.tex
deleted file mode 100644
index e34ed4d3f0..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-gd-usage-tikz.tex
+++ /dev/null
@@ -1,549 +0,0 @@
-% 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{Using Graph Drawing in \tikzname}
-
-{\noindent {\emph{by Till Tantau}}}
-
-\begin{tikzlibrary}{graphdrawing}
- This package provides capabilities for automatic graph drawing. It requires
- that the document is typeset using Lua\TeX. This package should work with
- Lua\TeX\ 0.54 or higher.
-\end{tikzlibrary}
-
-\ifluatex
-\else
- This section of the manual can only be typeset using Lua\TeX.
- \expandafter\endinput
-\fi
-
-
-\subsection{Choosing a Layout and a Library}
-
-The graph drawing engine is initialized when you load the library
-|graphdrawing|. This library provides the basic framework for graph drawing,
-including all options and keys described in the present section. However, this
-library does \emph{not} load any actual algorithms for drawing graphs. For
-this, you need to use the following command, which is defined by the
-|graphdrawing| library:
-
-\begin{command}{\usegdlibrary\marg{list of libraries}}
- This command is used to load the special graph drawing libraries (the |gd|
- in the name of the command stands for ``graph drawing''). The \meta{list of
- libraries} is a comma-separated list of library written in the Lua
- programming language (which is why a special command is needed).
-
- In detail, this command does the following. For each \meta{name} in the
- \meta{list of libraries} we do:
- %
- \begin{enumerate}
- \item Check whether Lua\TeX\ can call |require| on the library file
- |pgf.gd.|\meta{name}|.library|. Lua\TeX's usual file search
- mechanism will search the texmf-trees in the usual manner and the
- dots in the file name get converted into directory slashes.
- \item If the above failed, try to |require| the string
- |pgf.gd.|\meta{name}.
- \item If this fails, try to |require| the string \meta{name}|.library|.
- \item If this fails, try to |require| the string \meta{name}. If this
- fails, print an error message.
- \end{enumerate}
- %
- The net effect of the above is the following: Authors of graph drawing
- algorithms can bundle together multiple algorithms in a library by creating
- a |...xyz/library.lua| file that internally just calls |require| for all
- files containing declarations. On the other hand, if a graph drawing
- algorithm completely fits inside a single file, it can also be read
- directly using |\usegdlibrary|.
- %
-\begin{codeexample}[code only]
-\usetikzlibrary{graphdrawing}
-\usegdlibrary{trees,force}
-\end{codeexample}
-
- The different graph drawing libraries are documented in the following
- Sections~\ref{section-first-graphdrawing-library-in-manual} to
- \ref{section-last-graphdrawing-library-in-manual}.
-\end{command}
-
-Note that in addition to the graph \emph{drawing} libraries, you may also wish
-to load the normal \tikzname\ library |graphs|. It provides the powerful
-|graph| path command with its easy-to-use syntax for specifying graphs, but you
-can use the graph drawing engine independently of the |graphs| library, for
-instance in conjunction with the |child| or the |edge| syntax. Here is a
-typical setup:
-%
-\begin{codeexample}[code only]
-\usetikzlibrary{graphs, graphdrawing}
-\usegdlibrary{trees, layered}
-\end{codeexample}
-
-Having set things up, you must then specify for which scopes the graph drawing
-engine should apply a layout algorithm to the nodes in the scope. Typically,
-you just add an option ending with |... layout| to the |graph| path operation
-and then let the graph drawing do its magic:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{layered}}]
-\tikz [rounded corners]
- \graph [layered layout, sibling distance=8mm, level distance=8mm]
- {
- a -> {
- b,
- c -> { d, e }
- } ->
- f ->
- a
- };
-\end{codeexample}
-
-Whenever you use such an option, you can:
-%
-\begin{itemize}
- \item Create nodes in the usual way. The nodes will be created completely,
- but then tucked away in an internal table. This means that all of
- \tikzname's options for nodes can be applied. You can also name a node
- and reference it later.
- \item Create edges using either the syntax of the |graph| command (using
- |--|, |<-|, |->|, or |<->|), or using the |edge| command, or using the
- |child| command. These edges will, however, not be created immediately.
- Instead, the basic layer's command |\pgfgdedge| will be called, which
- stores ``all the information concerning the edge''. The actual drawing
- of the edge will only happen after all nodes have been positioned.
- \item Most of the keys that can be passed to an edge will work as expected.
- In particular, you can add labels to edges using the usual |node|
- syntax for edges.
- \item The |label| and |pin| options can be used in the usual manner with
- nodes inside a graph drawing scope. Only, the labels and nodes will
- play no role in the positioning of the nodes and they are added when
- the nodes are finally positioned.
- \item Similarly, nodes that are placed ``on an edge'' using the implicit
- positioning syntax can be used in the usual manner.
-\end{itemize}
-%
-Here are some things that will \emph{not} work:
-%
-\begin{itemize}
- \item Only edges created using the graph syntax, the |edge| command, or the
- |child| command will correctly pass their connection information to the
- basic layer. When you write |\draw (a)--(b);| inside a graph drawing
- scope, where |a| and |b| are nodes that have been created inside the
- scope, you will get an error message / things will look wrong. The
- reason is that the usual |--| is not ``caught'' by the graph drawing
- engine and, thus, tries to immediately connect two nodes that do not
- yet exist (except inside some internal table).
- \item The options of edges are executed twice: Once when the edge is
- ``examined'' by the |\pgfgdedge| command (using some magic to shield
- against the side effects) and then once more when the edge is actually
- created. Fortunately, in almost all cases, this will not be a problem;
- but if you do very evil magic inside your edge options, you must roll a
- D100 to see what strange things will happen. (Do no evil, by the way.)
-\end{itemize}
-
-If you are really interested in the ``fine print'' of what happens, please see
-Section~\ref{section-gd-pgf}.
-
-
-\subsection{Graph Drawing Parameters}
-
-Graph drawing algorithms can typically be configured in some way. For instance,
-for a graph drawing algorithm that visualizes its nodes as a tree, it will
-typically be useful when the user can change the so-called \emph{level
-distance} and the \emph{sibling distance}. For other algorithms, like
-force-based algorithms, a large number of parameters influence the way the
-algorithms work. Options that influence graph drawing algorithms will be called
-\emph{(graph drawing) parameters} in the following. From the user's point of
-view, these parameters look like normal \tikzname\ keys and you set them in the
-usual way. Internally, they are treated a bit differently from normal keys
-since their ``effect'' becomes apparent only later on, namely during the run of
-the graph drawing algorithm.
-
-A graph drawing algorithm may or may not take different graph parameters into
-account. After all, these options may even outright contradict each other, so
-an algorithm can only try to ``do its best''. While many graph parameters are
-very specific to a single algorithm, a number of graph parameters will be
-important for many algorithms and they are documented in the course of the
-present section. Here is an example of an option the ``always works'':
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{force}}]
-\tikz \graph [spring layout, vertical=1 to 2] { 1--2--3--1 };
-\end{codeexample}
-
-\includeluadocumentationof{pgf.gd.control.Distances}
-\includeluadocumentationof{pgf.gd.control.Anchoring}
-\includeluadocumentationof{pgf.gd.control.Orientation}
-
-\includeluadocumentationof{pgf.gd.control.FineTune}
-
-\includeluadocumentationof{pgf.gd.control.Components}
-\includeluadocumentationof{pgf.gd.control.ComponentOrder}
-\includeluadocumentationof{pgf.gd.control.ComponentDirection}
-\includeluadocumentationof{pgf.gd.control.ComponentAlign}
-\includeluadocumentationof{pgf.gd.control.ComponentDistance}
-
-\includeluadocumentationof{pgf.gd.control.NodeAnchors}
-
-\includeluadocumentationof{pgf.gd.model.Hyperedge}
-
-
-\subsection{Using Several Different Layouts to Draw a Single Graph}
-\label{section-gd-sublayouts}
-
-Inside each graph drawing scope, a main algorithm is used to perform the graph
-drawing. However, parts of the graph may be drawn using different algorithms:
-For instance, a graph might consist of several, say, cliques that are arranged
-in a tree-like fashion. In this case, it might be useful to layout each clique
-using a circular layout, but then lay out all laid out cliques using a tree
-drawing algorithm.
-
-In order to lay out a graph using multiple algorithms, we need two things:
-First, we must be able to \emph{specify} which algorithms should be used where
-and, second, we must be able to \emph{resolve} conflicts that may result from
-different algorithms ``having different ideas'' concerning where nodes should
-be placed.
-
-
-\subsubsection{Sublayouts}
-
-Specifying different layouts for a graph is easy: Inside a graph drawing scope,
-simply open scopes, in which you use an option like |tree layout| for the nodes
-mentioned in this scope. Inside these scopes, you can open even subscopes for
-sublayouts, and so on. Furthermore, the |graphs| library has special support
-for sublayouts.
-
-Let us start with the ``plain'' syntax for opening sublayouts: You pass a key
-for creating layouts to a |scope|:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphdrawing}
-\usegdlibrary{force,trees}}]
-\tikz [spring layout] {
- \begin{scope}[tree layout]
- \node (a) {a};
- \node (b) {b};
- \node (c) {c};
- \draw (a) edge (b) edge (c);
- \end{scope}
-
- \begin{scope}[tree layout]
- \node (1) {1};
- \node (2) {2};
- \draw (1) edge (2);
- \end{scope}
-
- \draw (a) edge (1);
-}
-\end{codeexample}
-
-Let us see, what is going on here. The main layout (|spring layout|) contains
-two sublayouts (the two |tree layouts|). Both of them are laid out
-independently (more on the details in a moment). Then, from the main layout's
-point of view, the sublayouts behave like ``large nodes'' and, thus, the edge
-between |a| and |1| is actually the only edge that is used by the
-|spring layout| -- resulting in a simple layout consisting of one big node at
-the top and a big node at the bottom.
-
-The |graphs| library has a special support for sublayouts: The syntax is as
-follows: wherever a normal node would go, you can write
-%
-\begin{quote}
- |//| \opt{\oarg{layout options}} |{|\meta{sublayout}|}|
-\end{quote}
-
-Following the double slash, you may provide \meta{layout options} in square
-brackets. However, you \emph{must} provide a sublayout in braces. The contents
-of \meta{sublayout} will be parsed using the usual |graph| syntax, but will
-form a sublayout.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{force,trees}}]
-\tikz \graph [spring layout] {
- // [tree layout] { a -- {b, c} };
- // [tree layout] { 1 -- 2 };
- a -- 1;
-};
-\end{codeexample}
-
-In the above example, there is no node before the double slash, which means
-that the two sublayouts will be part of the main graph, but will not be
-indicated otherwise.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{circular,trees}}]
-\tikz \graph [simple necklace layout] {
- // [simple necklace layout] { a -> b -> c -> d -> e -> f -> a };
-
- // [tree layout] { % first tentacle
- a -> {1, 2};
- };
-
- // [tree layout] {% second tentacle
- d -> {3, 4 -> {5, 6}}
- };
-};
-\end{codeexample}
-
-In the above example, the first sublayout is the one for the nodes with letter
-names. These nodes are arranged using a simple necklace layout as the sublayout
-inherits this option from the main layout. The two small trees (|a -> {1, 2}|
-and the tree starting at the |d| node) are also sublayouts, triggered by the
-|tree layout| option. They are also arranged. Then, all of the layouts are
-merged (as described later). The result is actually a single node, so the main
-layout does nothing here.
-
-Compare the above to the following code:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{circular,trees}}]
-\tikz \graph [simple necklace layout] {
- // [tree layout] { % first ``giant node''
- a -> {1, 2};
- };
-
- a -> b -> c -> d;
-
- // [tree layout] {% second ``giant node''
- d -> {3, 4 -> {5, 6}}
- },
-
- d -> e -> f -> a;
-};
-\end{codeexample}
-
-Here, only the two trees are laid out first. They are then contracted into
-``giant nodes'' and these are then part of the set of nodes that are arranged
-by the |simple necklace layout|. For details of how this contracting works, see
-below.
-
-
-\subsubsection{Subgraph Nodes}
-
-A \emph{subgraph node} is a special kind of node that ``surrounds'' the
-vertices of a subgraph. The special property of a subgraph node opposed to a
-normal node is that it is created only after the subgraph has been laid out.
-However, the difference to a collection like |hyper| is that the node is
-available immediately as a normal node in the sense that you can connect edges
-to it.
-
-The syntax used to declare a subgraph node in a |graph| specification is as
-follows:
-%
-\begin{quote}
- \opt{|"|}\meta{node name}\opt{|"|}\opt{|/|\opt{|"|}\meta{text}\opt{|"|}}
- \opt{\oarg{node options}} |//| \opt{\oarg{layout options}} |{|\meta{subgraph}|}|
-\end{quote}
-
-The idea ist that a subgraph node is declared like a normal node specification,
-but is followed by a double slash and a subgraph:
-%
-\begin{codeexample}[
- width=5cm,
- preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{circular,trees}},
-]
-\tikz \graph [simple necklace layout] {
- tree 1[draw, circle] // [tree layout] { a -> {1, 2}; }
- -> b
- -> c
- -> tree 2[draw] // [tree layout] { d -> {3, 4 -> {5, 6} } }
- -> e
- -> f
- -> tree 1;
-};
-\end{codeexample}
-
-Note how the two subgraph nodes |tree 1| and |tree 2| surround the two smaller
-trees. In the example, both had trees as contents and these trees were rendered
-using a sublayout. However, a subgraph layout does not need to have its own
-layout: If you do \emph{not} provide a layout name after the double slash, the
-subgraph node will simply surround all nodes that were placed by the main
-layout wherever they were placed:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{trees}}]
-\tikz [subgraph text bottom=text centered,
- subgraph nodes={font=\itshape}]
- \graph [tree layout] {
- a -> { b -> {c, d}, e -> {f, g -> h} };
-
- left [draw] // { b, c, d };
- right [draw] // { e, f, g, h};
-
- left <-> right;
- };
-\end{codeexample}
-
-Every time a subgraph node is created, the following style is execute:
-
-\begin{key}{/tikz/every subgraph node}
- Set a subgraph node style.
-\end{key}
-
-\begin{key}{/tikz/subgraph nodes=\meta{style}}
- Sets the |every subgraph node| style to \meta{style}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{trees}}]
-\tikz [subgraph text bottom=text centered,
- subgraph nodes=red]
- \graph [tree layout] {
- a -> { b -> {c, d}, e -> {f, g -> h} };
-
- left [draw] // { b, c, d };
- right [draw] // { e, f, g, h};
-
- left <-> right;
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/subgraph text none}
- When this option is used, the text of a subgraph node is not shown. Adding
- a slash after the node name achieves roughly the same effect, but this
- option is useful in situations when subgraph nodes generally should not
- have any text inside them.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{trees}}]
-\tikz [subgraph text none]
- \graph [tree layout] {
- a -> { b -> {c, d}, e -> {f, g -> h} };
-
- left [draw] // { b, c, d };
- right [draw] // { e, f, g, h};
-
- left <-> right;
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/subgraph text top=\meta{text alignment options} (default text ragged right)}
- Specifies that the text of a subgraph node should be placed at the top of
- the subgraph node: Still inside the node, but above all nodes inside the
- subgraph node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{trees}}]
-\tikz [subgraph text top=text ragged left]
- \graph [tree layout] {
- a -> { b -> {c, d}, e -> {f, g -> h} };
-
- left [draw] // { b, c, d };
- right [draw] // { e, f, g, h};
-
- left <-> right;
- };
-\end{codeexample}
- %
- You can pass any of the \meta{text alignment options} understood by
- \tikzname, such as |text centered|:
- %
-\begin{codeexample}[
- width=5cm,
- preamble={\usetikzlibrary{graphs,graphdrawing}
-\usegdlibrary{trees}},
-]
-\tikz [subgraph text top=text centered]
- \graph [tree layout] {
- a -> { b -> {c, d}, e -> {f, g -> h} };
-
- left [draw, circle] // { b, c, d };
- };
-\end{codeexample}
- %
- To place a label \emph{outside} the subgraph node, use a label, typically
- defined using the |quotes| library:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing,quotes}
-\usegdlibrary{trees}}]
-\tikz \graph [tree layout] {
- a -> { b -> {c, d}, e -> {f, g -> h} };
-
- / ["left", draw] // { b, c, d } <->
- / ["right", draw] // { e, f, g, h};
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/subgraph text bottom=\meta{text alignment options} (default ragged right)}
- Works like |subgraph text top|, only the text placed at the bottom.
-\end{key}
-
-Note that there are no keys |subgraph text left| or |... right|, for somewhat
-technical reasons.
-
-\begin{key}{/tikz/subgraph text sep=\meta{dimension} (initially .1em)}
- Some space added between the inner nodes of a subgraph node and the text
- labels.
-\end{key}
-
-
-\subsubsection{Overlapping Sublayouts}
-\label{section-gd-layout-resolve}
-
-Nodes and edges can be part of several layouts. This will inevitably lead to
-conflicts because algorithm will disagree on where a node should be placed on
-the canvas. For this reason, there are some rules governing how such conflicts
-are resolved: Given a layout, starting with the main layout, the graph drawing
-system does the following:
-%
-\begin{enumerate}
- \item We start by first processing the (direct) sublayouts of the current
- layout (recursively). Sublayouts may overlap (they may share one or
- more nodes), but we run the specified layout algorithm for each
- sublayout independently on a ``fresh copy'' of all the nodes making up
- the sublayout. In particular, different, conflicting positions may be
- computed for nodes when they are present in several sublayouts.
- \item Once all nodes in the sublayouts have been laid out in this way, we
- \emph{join} overlapping elements. The idea is that if two layouts share
- exactly one vertex, we can shift them around so that his vertex is at
- the same position in both layouts. In more detail, the following
- happens:
-
- We build a (conceptual) graph whose nodes are the sublayouts and in
- which there is an edge between two nodes if the sublayouts represented
- by these elements have a node in common. Inside the resulting graph, we
- treat each connected component separately. Each component has the
- property that the sublayouts represented by the nodes in the component
- overlap by at least one node. We now \emph{join} them as follows: We
- start with the first sublayout in the component (``first'' with respect
- to the order in which they appear in the input graph) and ``mark'' this
- sublayout. We loop the following instructions as long as possible:
- Search for the first sublayout (again, with respect to the order in
- which they appear in the input) that is connect by an edge to a marked
- sublayout. The sublayout will now have at least one node in common with
- the marked sublayouts (possibly, even more). We consider the first such
- node (again, first respect to the input ordering) and shift the whole
- sublayout is such a way that this particular node is at the position is
- has in the marked sublayouts. Note that after the shift, other nodes
- that are also present in the marked sublayouts may lie at a different
- position in the current sublayout. In this case, the position in the
- marked sublayouts ``wins''. We then mark the sublayout.
- \item When the above algorithm has run, we will have computed positions for
- all nodes in all sublayouts of each of the components. For each
- component, we contract all nodes of the component to a single node.
- This new node will be ``large'' in the sense that its convex hull is
- the convex hull of all the nodes in the component. All nodes that used
- to be part of the component are removed and the new large node is added
- (with arcs adjusted appropriately).
- \item We now run the layout's algorithm on the resulting nodes (the
- remaining original nodes and the contracted nodes).
- \item In a last step, once the graph has been laid out, we expand the nodes
- that were previously contracted. For this, the nodes that were deleted
- earlier get reinserted, but shifted by whatever amount the contraction
- node got shifted.
-\end{enumerate}
-
-
-\subsection{Miscellaneous Options}
-
-\includeluadocumentationof{pgf.gd.control.library}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-guidelines.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-guidelines.tex
deleted file mode 100644
index fa29cce302..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-guidelines.tex
+++ /dev/null
@@ -1,651 +0,0 @@
-% Copyright 2018 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{Guidelines on Graphics}
-
-The present section is not about \pgfname\ or \tikzname, but about general
-guidelines and principles concerning the creation of graphics for scientific
-presentations, papers, and books.
-
-The guidelines in this section come from different sources. Many of them are
-just what I would like to claim is ``common sense'', some reflect my personal
-experience (though, hopefully, not my personal preferences), some come from
-books (the bibliography is still missing, sorry) on graphic design and
-typography. The most influential source are the brilliant books by Edward
-Tufte. While I do not agree with everything written in these books, many of
-Tufte's arguments are so convincing that I decided to repeat them in the
-following guidelines.
-
-The first thing you should ask yourself when someone presents a bunch of
-guidelines is: Should I really follow these guidelines? This is an important
-question, because there are good reasons not to follow general guidelines. The
-person who set up the guidelines may have had other objectives than you do. For
-example, a guideline might say ``use the color red for emphasis''. While this
-guideline makes perfect sense for, say, a presentation using a projector, red
-``color'' has the \emph{opposite} effect of ``emphasis'' when printed using a
-black-and-white printer. Guidelines were almost always set up to address a
-specific situation. If you are not in this situation, following a guideline can
-do more harm than good.
-
-The second thing you should be aware of is the basic rule of typography is:
-``Every rule can be broken, as long as you are \emph{aware} that you are
-breaking a rule.'' This rule also applies to graphics. Phrased differently, the
-basic rule states: ``The only mistakes in typography are things done in
-ignorance.'' When you are aware of a rule and when you decide that breaking the
-rule has a desirable effect, break the rule.
-
-
-\subsection{Planning the Time Needed for the Creation of Graphics}
-
-When you create a paper with numerous graphics, the time needed to create these
-graphics becomes an important factor. How much time should you calculate for
-the creation of graphics?
-
-As a general rule, assume that a graphic will need as much time to create as
-would a text of the same length. For example, when I write a paper, I need
-about one hour per page for the first draft. Later, I need between two and four
-hours per page for revisions. Thus, I expect to need about half an hour for the
-creation of \emph{a first draft} of a half page graphic. Later on, I expect
-another one to two hours before the final graphic is finished.
-
-In many publications, even in good journals, the authors and editors have
-obviously invested a lot of time on the text, but seem to have spend about
-five minutes to create all of the graphics. Graphics often seem to have been
-added as an ``afterthought'' or look like a screen shot of whatever the
-authors's statistical software shows them. As will be argued later on, the
-graphics that programs like \textsc{gnuplot} produce by default are of poor
-quality.
-
-Creating informative graphics that help the reader and that fit together with
-the main text is a difficult, lengthy process.
-%
-\begin{itemize}
- \item Treat graphics as first-class citizens of your papers. They deserve
- as much time and energy as the text does. Indeed, the creation of
- graphics might deserve \emph{even more} time than the writing of the
- main text since more attention will be paid to the graphics and they
- will be looked at first.
- \item Plan as much time for the creation and revision of a graphic as you
- would plan for text of the same size.
- \item Difficult graphics with a high information density may require even
- more time.
- \item Very simple graphics will require less time, but most likely you do
- not want to have ``very simple graphics'' in your paper, anyway; just
- as you would not like to have a ``very simple text'' of the same
- size.
-\end{itemize}
-
-
-\subsection{Workflow for Creating a Graphic}
-
-When you write a (scientific) paper, you will most likely follow the following
-pattern: You have some results/ideas that you would like to report about. The
-creation of the paper will typically start with compiling a rough outline.
-Then, the different sections are filled with text to create a first draft. This
-draft is then revised repeatedly until, often after substantial revision, a
-final paper results. In a good journal paper there is typically not be a single
-sentence that has survived unmodified from the first draft.
-
-Creating a graphics follows the same pattern:
-%
-\begin{itemize}
- \item Decide on what the graphic should communicate. Make this a
- conscious decision, that is, determine ``What is the graphic supposed
- to tell the reader?''
- \item Create an ``outline'', that is, the rough overall ``shape'' of the
- graphic, containing the most crucial elements. Often, it is useful to
- do this using pencil and paper.
- \item Fill out the finer details of the graphic to create a first draft.
- \item Revise the graphic repeatedly along with the rest of the paper.
-\end{itemize}
-
-
-\subsection{Linking Graphics With the Main Text}
-
-Graphics can be placed at different places in a text. Either, they can be
-inlined, meaning they are somewhere ``in the middle of the text'' or they can
-be placed in stand-alone ``figures''. Since printers (the people) like to have
-their pages ``filled'', (both for aesthetic and economic reasons) stand-alone
-figures may traditionally be placed on pages in the document far away from the
-main text that refers to them. \LaTeX\ and \TeX\ tend to encourage this
-``drifting away'' of graphics for technical reasons.
-
-When a graphic is inlined, it will more or less automatically be linked with
-the main text in the sense that the labels of the graphic will be implicitly
-explained by the surrounding text. Also, the main text will typically make it
-clear what the graphic is about and what is shown.
-
-Quite differently, a stand-alone figure will often be viewed at a time when the
-main text that this graphic belongs to either has not yet been read or has been
-read some time ago. For this reason, you should follow the following guidelines
-when creating stand-alone figures:
-%
-\begin{itemize}
- \item Stand-alone figures should have a caption than should make them
- ``understandable by themselves''.
-
- For example, suppose a graphic shows an example of the different
- stages of a quicksort algorithm. Then the figure's caption should, at
- the very least, inform the reader that ``the figure shows the
- different stages of the quicksort algorithm introduced on page xyz''.
- and not just ``Quicksort algorithm''.
- \item A good caption adds as much context information as possible. For
- example, you could say: ``The figure shows the different stages of
- the quicksort algorithm introduced on page xyz. In the first line,
- the pivot element 5 is chosen. This causes\dots'' While this
- information can also be given in the main text, putting it in the
- caption will ensure that the context is kept. Do not feel afraid of a
- 5-line caption. (Your editor may hate you for this. Consider hating
- them back.)
- \item Reference the graphic in your main text as in ``for an example of
- quicksort `in action', see Figure~2.1 on page xyz''.
- \item Most books on style and typography recommend that you do not use
- abbreviations as in ``Fig.~2.1'' but write ``Figure~2.1''.
-
- The main argument against abbreviations is that ``a period is too
- valuable to waste it on an abbreviation''. The idea is that a period
- will make the reader assume that the sentence ends after ``Fig'' and
- it takes a ``conscious backtracking'' to realize that the sentence
- did not end after all.
-
- The argument in favor of abbreviations is that they save space.
-
- Personally, I am not really convinced by either argument. On the one
- hand, I have not yet seen any hard evidence that abbreviations slow
- readers down. On the other hand, abbreviating all ``Figure'' by
- ``Fig.'' is most unlikely to save even a single line in most documents.
- I avoid abbreviations.
-\end{itemize}
-
-
-\subsection{Consistency Between Graphics and Text}
-
-Perhaps the most common ``mistake'' people do when creating graphics (remember
-that a ``mistake'' in design is always just ``ignorance'') is to have a
-mismatch between the way their graphics look and the way their text looks.
-
-It is quite common that authors use several different programs for creating the
-graphics of a paper. An author might produce some plots using \textsc{gnuplot},
-a diagram using \textsc{xfig}, and include an |.eps| graphic a coauthor
-contributed using some unknown program. All these graphics will, most likely,
-use different line widths, different fonts, and have different sizes. In
-addition, authors often use options like |[height=5cm]| when including graphics
-to scale them to some ``nice size''.
-
-If the same approach were taken to writing the main text, every section would
-be written in a different font at a different size. In some sections all
-theorems would be underlined, in another they would be printed all in uppercase
-letters, and in another in red. In addition, the margins would be different on
-each page. Readers and editors would not tolerate a text if it were written in
-this fashion, but with graphics they often have to.
-
-To create consistency between graphics and text, stick to the following
-guidelines:
-%
-\begin{itemize}
- \item Do not scale graphics.
-
- This means that when generating graphics using an external program,
- create them ``at the right size''.
- \item Use the same font(s) both in graphics and the body text.
- \item Use the same line width in text and graphics.
-
- The ``line width'' for normal text is the width of the stem of letters
- like T{}. For \TeX, this is usually $0.4\,\mathrm{pt}$. However, some
- journals will not accept graphics with a normal line width below
- $0.5\,\mathrm{pt}$.
- \item When using colors, use a consistent color coding in the text and in
- graphics. For example, if red is supposed to alert the reader to
- something in the main text, use red also in graphics for important
- parts of the graphic. If blue is used for structural elements like
- headlines and section titles, use blue also for structural elements
- of your graphic.
-
- However, graphics may also use a logical intrinsic color
- coding. For example, no matter what colors you normally use, readers
- will generally assume, say, that the color green as ``positive, go,
- ok'' and red as ``alert, warning, action''.
-\end{itemize}
-
-Creating consistency when using different graphic programs is almost
-impossible. For this reason, you should consider sticking to a single graphics
-program.
-
-
-\subsection{Labels in Graphics}
-
-Almost all graphics will contain labels, that is, pieces of text that explain
-parts of the graphics. When placing labels, stick to the following guidelines:
-%
-\begin{itemize}
- \item Follow the rule of consistency when placing labels. You should do
- so in two ways: First, be consistent with the main text, that is, use
- the same font as the main text also for labels. Second, be consistent
- between labels, that is, if you format some labels in some particular
- way, format all labels in this way.
- \item In addition to using the same fonts in text and graphics, you
- should also use the same notation. For example, if you write $1/2$ in
- your main text, also use ``$1/2$'' as labels in graphics, not
- ``0.5''. A $\pi$ is a ``$\pi$'' and not ``$3.141$''. Finally,
- $\mathrm e^{-\mathrm i \pi}$ is ``$\mathrm e^{-\mathrm i \pi}$'', not
- ``$-1$'', let alone ``-1''.
- \item Labels should be legible. They should not only have a reasonably
- large size, they also should not be obscured by lines or other text.
- This also applies to labels of lines and text \emph{behind} the
- labels.
- \item Labels should be ``in place''. Whenever there is enough space,
- labels should be placed next to the thing they label. Only if
- necessary, add a (subdued) line from the label to the labeled object.
- Try to avoid labels that only reference explanations in external
- legends. Reader have to jump back and forth between the explanation and
- the object that is described.
- \item Consider subduing ``unimportant'' labels using, for example, a gray
- color. This will keep the focus on the actual graphic.
-\end{itemize}
-
-
-\subsection{Plots and Charts}
-
-One of the most frequent kind of graphics, especially in scientific papers, are
-\emph{plots}. They come in a large variety, including simple line plots,
-parametric plots, three dimensional plots, pie charts, and many more.
-
-Unfortunately, plots are notoriously hard to get right. Partly, the default
-settings of programs like \textsc{gnuplot} or Excel are to blame for this since
-these programs make it very convenient to create bad plots.
-
-The first question you should ask yourself when creating a plot is: Are there
-enough data points to merit a plot? If the answer is ``not really'', use a
-table.
-
-A typical situation where a plot is unnecessary is when people present a few
-numbers in a bar diagram. Here is a real-life example: At the end of a seminar
-a lecturer asked the participants for feedback. Of the 50 participants, 30
-returned the feedback form. According to the feedback, three participants
-considered the seminar ``very good'', nine considered it ``good'', ten ``ok'',
-eight ``bad'', and no one thought that the seminar was ``very bad''.
-
-A simple way of summing up this information is the following table:
-
-\medskip
-\begin{tabular}{lp{3.75cm}r}
- \emph{Rating given} & \raggedright\emph{Participants (out of 50) who gave this rating} &
- \emph{Percentage} \\[1.75em]
- ``very good'' & \hfil\hphantom{0}3\hfil & \hphantom{0}6\% \\
- ``good'' & \hfil\hphantom{0}9\hfil & 18\% \\
- ``ok'' & \hfil10\hfil & 20\% \\
- ``bad'' & \hfil\hphantom{0}8\hfil & 16\% \\
- ``very bad'' & \hfil\hphantom{0}0\hfil & \hphantom{0}0\% \\[2mm]
- none & \hfil20\hfil & 40\% \\
-\end{tabular}
-
-\bigskip
-What the lecturer did was to visualize the data using a 3D bar diagram. It
-looked like this (except that in reality the numbers where typeset using some
-extremely low-resolution bitmap font and were near-unreadable):
-
-\bigskip
-\par
-\begin{tikzpicture}[y=0.03cm,z=3mm]
- \foreach \y in {0,20,40,60,80,100}
- \draw[dashed] (0,\y,0) node[left] {\y} -- (0,\y,1) -- (6,\y,1);
-
- \draw (0,0,0) -- (0,100,0) (0,0,1) -- (0,100,1);
- \draw (0,0,0) -- (6,0,0);
-
- \foreach \x/\xtext/\height in {1/very good/10,2/good/30,3/ok/33,4/bad/27,5/very bad/0}
- {
- \draw (\x,0) node[rotate=90,anchor=east] {\xtext};
-
- \begin{scope}[xshift=\x cm]
-
- \filldraw[fill=blue!50] (-.3,0,0) rectangle (.3,\height,0);
- \filldraw[fill=blue!30] (.3,0,0) -- (.3,0,1) -- (.3,\height,1) -- (.3,\height,0) --cycle;
- \filldraw[fill=blue!20] (-.3,\height,0) -- (.3,\height,0) --
- (.3,\height,1) -- (-.3,\height,1) --cycle;
- \end{scope}
- }
-\end{tikzpicture}
-\bigskip
-
-Both the table and the ``plot'' have about the same size. If your first thought
-is ``the graphic looks nicer than the table'', try to answer the following
-questions based on the information in the table or in the graphic:
-%
-\begin{enumerate}
- \item How many participants were there?
- \item How many participants returned the feedback form?
- \item What percentage of the participants returned the feedback form?
- \item How many participants checked ``very good''?
- \item What percentage out of all participants checked ``very good''?
- \item Did more than a quarter of the participants check ``bad'' or ``very
- bad''?
- \item What percentage of the participants that returned the form checked
- ``very good''?
-\end{enumerate}
-
-Sadly, the graphic does not allow us to answer \emph{a single one of these
-questions}. The table answers all of them directly, except for the last one. In
-essence, the information density of the graphic is very close to zero. The
-table has a much higher information density; despite the fact that it uses
-quite a lot of white space to present a few numbers. Here is the list of things
-that went wrong with the 3D-bar diagram:
-%
-\begin{itemize}
- \item The whole graphic is dominated by irritating background lines.
- \item It is not clear what the numbers at the left mean; presumably
- percentages, but it might also be the absolute number of
- participants.
- \item The labels at the bottom are rotated, making them hard to read.
-
- (In the real presentation that I saw, the text was rendered at a very
- low resolution with about 10 by 6 pixels per letter with wrong
- kerning, making the rotated text almost impossible to read.)
- \item The third dimension adds complexity to the graphic without adding
- information.
- \item The three dimensional setup makes it much harder to gauge the
- height of the bars correctly. Consider the ``bad'' bar. It the number
- this bar stands for more than 20 or less? While the front of the bar
- is below the 20 line, the back of the bar (which counts) is above.
- \item It is impossible to tell which numbers are represented by the
- bars. Thus, the bars needlessly hide the information these bars are
- all about.
- \item What do the bar heights add up to? Is it 100\% or 60\%?
- \item Does the bar for ``very bad'' represent 0 or~1?
- \item Why are the bars blue?
-\end{itemize}
-
-You might argue that in the example the exact numbers are not important for the
-graphic. The important things is the ``message'', which is that there are more
-``very good'' and ``good'' ratings than ``bad'' and ``very bad''. However, to
-convey this message either use a sentence that says so or use a graphic that
-conveys this message more clearly:
-
-\medskip
-\par
-\begin{tikzpicture}
- \colorlet{good}{green!75!black}
- \colorlet{bad}{red}
- \colorlet{neutral}{black!60}
- \colorlet{none}{white}
-
- \node[align=center,text width=3cm]{Ratings given by 50~participants};
-
- \begin{scope}[line width=4mm,rotate=270]
- \draw[good] (-123:2cm) arc (-123:-101:2cm);
- \draw[good!60!white] (-36:2cm) arc (-36:-101:2cm);
- \draw[neutral] (-36:2cm) arc (-36:36:2cm);
- \draw[bad!60!white] (36:2cm) arc (36:93:2cm);
-
- \newcount\mycount
- \foreach \angle in {0,72,...,3599}
- {
- \mycount=\angle\relax
- \divide\mycount by 10\relax
- \draw[black!15,thick] (\the\mycount:18mm) -- (\the\mycount:22mm);
- }
-
- \draw (0:2.2cm) node[below] {``ok'': 10 (20\%)};
- \draw (165:2.2cm) node[above] {none: 20 (40\%)};
- \draw (-111:2.2cm) node[left] {``very good'': 3 (6\%)};
- \draw (-68:2.2cm) node[left] {``good'': 9 (18\%)};
- \draw (65:2.2cm) node[right] {``bad'': 8 (16\%)};
- \draw (93:2.2cm) node[right] {``very bad'': 0 (0\%)};
- \end{scope}
- \draw[gray] (0,0) circle (2.2cm) circle (1.8cm);
-\end{tikzpicture}
-
-\bigskip
-The above graphic has about the same information density as the table (about
-the same size and the same numbers are shown). In addition, one can directly
-``see'' that there are more good or very good ratings than bad ones. One can
-also ``see'' that the number of people who gave no rating at all is not
-negligible, which is quite common for feedback forms.
-
-Charts are not always a good idea. Let us look at an example that I redrew from
-a pie chart in \emph{Die Zeit}, June 4th, 2005:
-
-\bigskip
-\par
-\begin{tikzpicture}
- \begin{scope}[xscale=3.2,yscale=1.2]
-
- \sffamily
- \coordinate (right border) at (2.0cm,-1.7cm);
- \coordinate (left border) at (-2.5cm,2.1cm);
-
- \fill[black!25] ([xshift=-2mm,yshift=1.1cm]left border) rectangle ([xshift=2mm,yshift=-.3cm]right border);
-
- \node[below right,text width=10cm,inner sep=0pt] at ([yshift=.9cm,xshift=-1mm]left border)
- { {\color{black!75} \Large Kohle ist am wichtigsten}\\
- Energiemix bei der deutschen Stromerzeugung 2004};
-
- \filldraw[draw=gray,fill=white] ([xshift=-1mm]left border) node[below right,black]
- {\footnotesize Gesamte Netto-Stromerzeugung in Prozent, in
- Milliarden Kilowattstunden (Mrd.\ kWh)}
- rectangle ([xshift=1mm]right border);
-
- % The 3D stuff
- \pgfdeclarehorizontalshading{zeit}{100bp}
- {color(0pt)=(black);
- color(25bp)=(black);
- color(37bp)=(white);
- color(50bp)=(black);
- color(62bp)=(white);
- color(75bp)=(black);
- color(100bp)=(black)}
-
- \shadedraw[very thin,shading=zeit,yshift=-1.5mm] (0,0) circle (1cm);
-
- \fill[green!20!gray] (0,0) -- (90:1cm) arc (90:-5:1cm);
- \fill[white!20!gray] (0,0) -- (-5:1cm) arc (-5:-105:1cm);
- \fill[orange!20!gray] (0,0) -- (-105:1cm) arc (-105:-180:1cm);
- \fill[orange!60!white] (0,0) -- (180:1cm) arc (180:150:1cm);
- \fill[black!75!white] (0,0) -- (150:1cm) arc (150:145:1cm);
- \fill[blue!90!white] (0,0) -- (145:1cm) arc (145:135:1cm);
- \fill[blue!50!white] (0,0) -- (135:1cm) arc (135:92:1cm);
- \fill[yellow!50!black] (0,0) -- (92:1cm) arc (92:90:1cm);
-
- \begin{scope}[very thin]
- \draw (0,0) -- (90:1cm);
- \draw (0,0) -- (-5:1cm);
- \draw (0,0) -- (-105:1cm);
- \draw (0,0) -- (-180:1cm);
- \draw (0,0) -- (150:1cm);
- \draw (0,0) -- (145:1cm);
- \draw (0,0) -- (135:1cm);
- \draw (0,0) -- (92:1cm);
-
- \draw(0,0) circle (1cm);
- \end{scope}
-
- \node (Regenerative) at (115:.75cm) {\bfseries 9,4\%};
- \node (Kernenergie) at (30:.5cm) {\bfseries 27,8\%};
- \node (Braunkohle) at (-45:.6cm) {\bfseries 25,6\%};
- \node (Steinkohle) at (-135:.6cm) {\bfseries 22,3\%};
- \node (Erdgas) at (168:.75cm) {\bfseries 10,4\%};
- \coordinate (Mineral) at (147:.9cm);
- \coordinate (Sonstige) at (140:.9cm);
-
- \small
- \draw (Regenerative.north) |- ([yshift=.25cm]Regenerative.north -| right border) coordinate (Regenerative label);
- \draw (91:.9cm) |- (Regenerative label);
- \node[above left] at (Regenerative label) {Regenerative\
- {\footnotesize (53,7 kWh)/davon} Wind \textbf{4,4\%} \footnotesize (25,0 kWh)};
-
- \draw (Kernenergie.base east) -- (Kernenergie.base east -| right border) coordinate (Kernenergie label);
- \node[above left] at (Kernenergie label) {Kernenergie};
- \node[below left] at (Kernenergie label) {\footnotesize (158,4 kWh)};
-
- \draw (Braunkohle.south) |- ([yshift=-.75cm]Braunkohle.south -| right border) coordinate (Braunkohle label);
- \node[above left] at (Braunkohle label) {Braunkohle\ \ \footnotesize (146,0 kWh)};
-
- \draw (Steinkohle.south) |- ([yshift=-.75cm]Steinkohle.south -| left border) coordinate (Steinkohle label);
- \node[above right] at (Steinkohle label) {Steinkohle\ \ \footnotesize (127,1 kWh)};
-
- \draw (Erdgas.base west) -- (Erdgas.base west -| left border) coordinate (Erdgas label);
- \node[above right] at (Erdgas label) {Erdgas\ \ \footnotesize (59,2 kWh)};
-
- \draw (Mineral) -- (Mineral -| left border) coordinate (Mineral label);
- \node[above right] at (Mineral label) {Mineral\"olprodukte\ \
- \footnotesize (9,2 kWh) \ \ \normalsize\textbf{1,6\%}};
-
- \draw (Sonstige) |- (Regenerative label -| left border) coordinate (Sonstige label);
- \node[above right] at (Sonstige label) {Sonstige\ \
- \footnotesize (16,5 kWh) \hskip1.5cm\
- \normalsize\textbf{2,9\%}};
- \end{scope}
-\end{tikzpicture}
-
-This graphic has been redrawn in \tikzname, but the original looks almost
-exactly the same.
-
-At first sight, the graphic looks ``nice and informative'', but there are a lot
-of things that went wrong:
-%
-\begin{itemize}
- \item The chart is three dimensional. However, the shadings add nothing
- ``information-wise'', at best, they distract.
- \item In a 3D-pie-chart the relative sizes are very strongly distorted.
- For example, the area taken up by the gray color of ``Braunkohle'' is
- larger than the area taken up by the green color of ``Kernenergie''
- \emph{despite the fact that the percentage of Braunkohle is less than
- the percentage of Kernenergie}.
- \item The 3D-distortion gets worse for small areas. The area of
- ``Regenerative'' somewhat larger than the area of ``Erdgas''. The
- area of ``Wind'' is slightly smaller than the area of
- ``Mineral\"olprodukte'' \emph{although the percentage of Wind is
- nearly three times larger than the percentage of
- Mineral\"olprodukte.}
-
- In the last case, the different sizes are only partly due to
- distortion. The designer(s) of the original graphic have also made
- the ``Wind'' slice too small, even taking distortion into
- account. (Just compare the size of ``Wind'' to ``Regenerative'' in
- general.)
- \item According to its caption, this chart is supposed to inform us that
- coal was the most important energy source in Germany in 2004.
- Ignoring the strong distortions caused by the superfluous and
- misleading 3D-setup, it takes quite a while for this message to get
- across.
-
- Coal as an energy source is split up into two slices: one for
- ``Steinkohle'' and one for ``Braunkohle'' (two different kinds of
- coal). When you add them up, you see that the whole lower half of
- the pie chart is taken up by coal.
-
- The two areas for the different kinds of coal are not visually
- linked at all. Rather, two different colors are used, the labels are
- on different sides of the graphic. By comparison, ``Regenerative''
- and ``Wind'' are very closely linked.
- \item The color coding of the graphic follows no logical pattern at all.
- Why is nuclear energy green? Regenerative energy is light blue,
- ``other sources'' are blue. It seems more like a joke that the area
- for ``Braunkohle'' (which literally translates to ``brown coal'') is
- stone gray, while the area for ``Steinkohle'' (which literally
- translates to ``stone coal'') is brown.
- \item The area with the lightest color is used for ``Erdgas''. This area
- stands out most because of the brighter color. However, for this
- chart ``Erdgas'' is not really important at all.
-\end{itemize}
-%
-Edward Tufte calls graphics like the above ``chart junk''. (I am happy to
-announce, however, that \emph{Die Zeit} has stopped using 3D pie charts and
-their information graphics have got somewhat better.)
-
-Here are a few recommendations that may help you avoid producing chart junk:
-%
-\begin{itemize}
- \item Do not use 3D pie charts. They are \emph{evil}.
- \item Consider using a table instead of a pie chart.
- \item Do not apply colors randomly; use them to direct the readers's
- focus and to group things.
- \item Do not use background patterns, like a crosshatch or diagonal
- lines, instead of colors. They distract. Background patterns in
- information graphics are \emph{evil}.
-\end{itemize}
-
-
-\subsection{Attention and Distraction}
-
-Pick up your favorite fiction novel and have a look at a typical page. You will
-notice that the page is very uniform. Nothing is there to distract the reader
-while reading; no large headlines, no bold text, no large white areas. Indeed,
-even when the author does wish to emphasize something, this is done using
-italic letters. Such letters blend nicely with the main text -- at a distance
-you will not be able to tell whether a page contains italic letters, but you
-would notice a single bold word immediately. The reason novels are typeset this
-way is the following paradigm: Avoid distractions.
-
-Good typography (like good organization) is something you do \emph{not} notice.
-The job of typography is to make reading the text, that is, ``absorbing'' its
-information content, as effortless as possible. For a novel, readers absorb the
-content by reading the text line-by-line, as if they were listening to someone
-telling the story. In this situation anything on the page that distracts the
-eye from going quickly and evenly from line to line will make the text harder
-to read.
-
-Now, pick up your favorite weekly magazine or newspaper and have a look at a
-typical page. You will notice that there is quite a lot ``going on'' on the
-page. Fonts are used at different sizes and in different arrangements, the text
-is organized in narrow columns, typically interleaved with pictures. The reason
-magazines are typeset in this way is another paradigm: Steer attention.
-
-Readers will not read a magazine like a novel. Instead of reading a magazine
-line-by-line, we use headlines and short abstracts to check whether we want to
-read a certain article or not. The job of typography is to steer our attention
-to these abstracts and headlines, first. Once we have decided that we want to
-read an article, however, we no longer tolerate distractions, which is why the
-main text of articles is typeset exactly the same way as a novel.
-
-The two principles ``avoid distractions'' and ``steer attention'' also apply to
-graphics. When you design a graphic, you should eliminate everything that will
-``distract the eye''. At the same time, you should try to actively help the
-reader ``through the graphic'' by using fonts/colors/line widths to highlight
-different parts.
-
-Here is a non-exhaustive list of things that can distract readers:
-%
-\begin{itemize}
- \item Strong contrasts will always be registered first by the eye. For
- example, consider the following two grids:
-
- \medskip\par
- \begin{tikzpicture}[x=40pt,y=40pt]
- \draw[step=10pt,gray] (0,0) grid +(1,1);
- \draw[step=2pt] (2,0) grid +(1,1);
- \end{tikzpicture}
-
- \medskip
- Even though the left grid comes first in English reading order, the
- right one is much more likely to be seen first: The white-to-black
- contrast is higher than the gray-to-white contrast. In addition,
- there are more ``places'' adding to the overall contrast in the right
- grid.
-
- Things like grids and, more generally, help lines usually should not
- grab the attention of the readers and, hence, should be typeset with
- a low contrast to the background. Also, a loosely-spaced grid is less
- distracting than a very closely-spaced grid.
- \item Dashed lines create many points at which there is black-to-white
- contrast. Dashed or dotted lines can be very distracting and, hence,
- should be avoided in general.
-
- Do not use different dashing patterns to differentiate curves in
- plots. You lose data points this way and the eye is not particularly
- good at ``grouping things according to a dashing pattern''. The eye
- is \emph{much} better at grouping things according to colors.
- \item Background patterns filling an area using diagonal lines or
- horizontal and vertical lines or just dots are almost always
- distracting and, usually, serve no real purpose.
- \item Background images and shadings distract and only seldomly add
- anything of importance to a graphic.
- \item Cute little clip arts can easily draw attention away from the data.
-\end{itemize}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-installation.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-installation.tex
deleted file mode 100644
index 307e972f66..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-installation.tex
+++ /dev/null
@@ -1,171 +0,0 @@
-% Copyright 2018 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{Installation}
-
-There are different ways of installing \pgfname, depending on your system and
-needs, and you may need to install other packages as well, see below. Before
-installing, you may wish to review the licenses under which the package is
-distributed, see Section~\ref{section-license}.
-
-Typically, the package will already be installed on your system. Naturally, in
-this case you do not need to worry about the installation process at all and
-you can skip the rest of this section.
-
-
-\subsection{Package and Driver Versions}
-
-This documentation is part of version \pgfversion\ of the \pgfname\ package. In
-order to run \pgfname, you need a reasonably recent \TeX\ installation. When
-using \LaTeX, you need the following packages installed (newer versions should
-also work):
-%
-\begin{itemize}
- \item |xcolor| version \xcolorversion.
-\end{itemize}
-%
-With plain \TeX, |xcolor| is not needed, but you obviously do not get its
-(full) functionality.
-
-Currently, \pgfname\ supports the following backend drivers:
-%
-\begin{itemize}
- \item |luatex| version 0.76 or higher. Most earlier versions also work.
- \item |pdftex| version 0.14 or higher. Earlier versions do not work.
- \item |dvips| version 5.94a or higher. Earlier versions may also work.
-
- For inter-picture connections, you need to process pictures using
- |pdftex| version 1.40 or higher running in DVI mode.
- \item |dvipdfm| version 0.13.2c or higher. Earlier versions may also
- work.
-
- For inter-picture connections, you need to process pictures using
- |pdftex| version 1.40 or higher running in DVI mode.
- \item |dvipdfmx| version 0.13.2c or higher. Earlier versions may also
- work.
- \item |dvisvgm| version 1.2.2 or higher. Earlier versions may also work.
- \item |tex4ht| version 2003-05-05 or higher. Earlier versions may also
- work.
- \item |vtex| version 8.46a or higher. Earlier versions may also work.
- \item |textures| version 2.1 or higher. Earlier versions may also work.
- \item |xetex| version 0.996 or higher. Earlier versions may also work.
-\end{itemize}
-
-Currently, \pgfname\ supports the following formats:
-%
-\begin{itemize}
- \item |latex| with complete functionality.
- \item |plain| with complete functionality, except for graphics inclusion,
- which works only for pdf\TeX.
- \item |context| with complete functionality, except for graphics
- inclusion, which works only for pdf\TeX.
-\end{itemize}
-
-For more details, see Section~\ref{section-formats}.
-
-
-\subsection{Installing Prebundled Packages}
-
-I do not create or manage prebundled packages of \pgfname, but, fortunately,
-nice other people do. I cannot give detailed instructions on how to install
-these packages, since I do not manage them, but I \emph{can} tell you were to
-find them. If you have a problem with installing, you might wish to have a look
-at the Debian page or the MiK\TeX\ page first.
-
-
-\subsubsection{Debian}
-
-The command ``|aptitude install pgf|'' should do the trick. Sit back and relax.
-
-
-\subsubsection{MiKTeX}
-
-For MiK\TeX, use the update wizard to install the (latest versions of the)
-packages called |pgf| and |xcolor|.
-
-
-\subsection{Installation in a texmf Tree}
-
-For a permanent installation, you place the files of the \textsc{pgf} package
-in an appropriate |texmf| tree.
-
-When you ask \TeX\ to use a certain class or package, it usually looks for the
-necessary files in so-called |texmf| trees. These trees are simply huge
-directories that contain these files. By default, \TeX\ looks for files in
-three different |texmf| trees:
-%
-\begin{itemize}
- \item The root |texmf| tree, which is usually located at
- |/usr/share/texmf/| or |c:\texmf\| or somewhere similar.
- \item The local |texmf| tree, which is usually located at
- |/usr/local/share/texmf/| or |c:\localtexmf\| or somewhere similar.
- \item Your personal |texmf| tree, which is usually located in your home
- directory at |~/texmf/| or |~/Library/texmf/|.
-\end{itemize}
-
-You should install the packages either in the local tree or in your personal
-tree, depending on whether you have write access to the local tree.
-Installation in the root tree can cause problems, since an update of the whole
-\TeX\ installation will replace this whole tree.
-
-
-\subsubsection{Installation that Keeps Everything Together}
-
-Once you have located the right texmf tree, you must decide whether you want to
-install \pgfname\ in such a way that ``all its files are kept in one place'' or
-whether you want to be ``\textsc{tds}-compliant'', where \textsc{tds} means
-``\TeX\ directory structure''.
-
-If you want to keep ``everything in one place'', inside the |texmf| tree that
-you have chosen create a sub-sub-directory called |texmf/tex/generic/pgf| or
-|texmf/tex/generic/pgf-|\texttt{\pgfversion}, if you prefer. Then place all
-files of the |pgf| package in this directory. Finally, rebuild \TeX's filename
-database. This is done by running the command |texhash| or |mktexlsr| (they are
-the same). In MiK\TeX, there is a menu option to do this.
-
-
-\subsubsection{Installation that is TDS-Compliant}
-
-While the above installation process is the most ``natural'' one and although I
-would like to recommend it since it makes updating and managing the \pgfname\
-package easy, it is not \textsc{tds}-compliant. If you want to be
-\textsc{tds}-compliant, proceed as follows: (If you do not know what
-\textsc{tds}-compliant means, you probably do not want to be
-\textsc{tds}-compliant.)
-
-The |.tar| file of the |pgf| package contains the following files and
-directories at its root: |README|, |doc|, |generic|, |plain|, and |latex|. You
-should ``merge'' each of the four directories with the following directories
-|texmf/doc|, |texmf/tex/generic|, |texmf/tex/plain|, and |texmf/tex/latex|. For
-example, in the |.tar| file the |doc| directory contains just the directory
-|pgf|, and this directory has to be moved to |texmf/doc/pgf|. The root |README|
-file can be ignored since it is reproduced in |doc/pgf/README|.
-
-You may also consider keeping everything in one place and using symbolic links
-to point from the \textsc{tds}-compliant directories to the central
-installation.
-
-\vskip1em For a more detailed explanation of the standard installation process
-of packages, you might wish to consult
-\href{http://www.ctan.org/installationadvice/}{|http://www.ctan.org/installationadvice/|}.
-However, note that the \pgfname\ package does not come with a |.ins| file
-(simply skip that part).
-
-
-\subsection{Updating the Installation}
-
-To update your installation from a previous version, all you need to do is to
-replace everything in the directory |texmf/tex/generic/pgf| with the files of
-the new version (or in all the directories where |pgf| was installed, if you
-chose a \textsc{tds}-compliant installation). The easiest way to do this is to
-first delete the old version and then proceed as described above. Sometimes,
-there are changes in the syntax of certain commands from version to version. If
-things no longer work that used to work, you may wish to have a look at the
-release notes and at the change log.
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-introduction.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-introduction.tex
deleted file mode 100644
index 2e65e1dabc..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-introduction.tex
+++ /dev/null
@@ -1,261 +0,0 @@
-% 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{Introduction}
-
-Welcome to the documentation of \tikzname\ and the underlying \pgfname\ system.
-What began as a small \LaTeX\ style for creating the graphics in my (Till
-Tantau's) PhD thesis directly with pdf\LaTeX\ has now grown to become a
-full-blown graphics language with a manual of over a thousand pages. The wealth
-of options offered by \tikzname\ is often daunting to beginners; but
-fortunately this documentation comes with a number slowly-paced tutorials that
-will teach you almost all you should know about \tikzname\ without your having
-to read the rest.
-
-I wish to start with the questions ``What is \tikzname?'' Basically, it just
-defines a number of \TeX\ commands that draw graphics. For example, the code
-|\tikz \draw (0pt,0pt) -- (20pt,6pt);| yields the line \tikz \draw (0pt,0pt) --
-(20pt,6pt); and the code |\tikz \fill[orange] (1ex,1ex) circle (1ex);| yields
-\tikz \fill[orange] (1ex,1ex) circle (1ex);. In a sense, when you use
-\tikzname\ you ``program'' your graphics, just as you ``program'' your document
-when you use \TeX. This also explains the name: \tikzname\ is a recursive
-acronym in the tradition of ``\textsc{gnu}'s Not Unix'' and means ``\tikzname\
-ist \emph{kein} Zeichenprogramm'', which translates to ``\tikzname\ is not a
-drawing program'', cautioning the reader as to what to expect. With \tikzname\
-you get all the advantages of the ``\TeX-approach to typesetting'' for your
-graphics: quick creation of simple graphics, precise positioning, the use of
-macros, often superior typography. You also inherit all the disadvantages:
-steep learning curve, no \textsc{wysiwyg}, small changes require a long
-recompilation time, and the code does not really ``show'' how things will look
-like.
-
-Now that we know what \tikzname\ is, what about ``\pgfname''? As mentioned
-earlier, \tikzname\ started out as a project to implement \TeX\ graphics macros
-that can be used both with pdf\LaTeX\ and also with the classical
-(PostScript-based) \LaTeX. In other words, I wanted to implement a ``portable
-graphics format'' for \TeX\ -- hence the name \pgfname. These early macros are
-still around and they form the ``basic layer'' of the system described in this
-manual, but most of the interaction an author has theses days is with
-\tikzname\ -- which has become a whole language of its own.
-
-
-\subsection{The Layers Below \tikzname}
-
-It turns out that there are actually \emph{two} layers below \tikzname:
-%
-\begin{description}
- \item[System layer:] This layer provides a complete abstraction of what
- is going on ``in the driver''. The driver is a program like |dvips|
- or |dvipdfm| that takes a |.dvi| file as input and generates a |.ps|
- or a |.pdf| file. (The |pdftex| program also counts as a driver, even
- though it does not take a |.dvi| file as input. Never mind.) Each
- driver has its own syntax for the generation of graphics, causing
- headaches to everyone who wants to create graphics in a portable way.
- \pgfname's system layer ``abstracts away'' these differences. For
- example, the system command |\pgfsys@lineto{10pt}{10pt}| extends the
- current path to the coordinate $(10\mathrm{pt},10\mathrm{pt})$ of
- the current |{pgfpicture}|. Depending on whether |dvips|, |dvipdfm|,
- or |pdftex| is used to process the document, the system command will
- be converted to different |\special| commands. The system layer is as
- ``minimalistic'' as possible since each additional command makes it
- more work to port \pgfname\ to a new driver.
-
- As a user, you will not use the system layer directly.
- \item[Basic layer:] The basic layer provides a set of basic commands that
- allow you to produce complex graphics in a much easier manner than by
- using the system layer directly. For example, the system layer provides
- no commands for creating circles since circles can be composed from the
- more basic Bézier curves (well, almost). However, as a user you will
- want to have a simple command to create circles (at least I do) instead
- of having to write down half a page of Bézier curve support
- coordinates. Thus, the basic layer provides a command |\pgfpathcircle|
- that generates the necessary curve coordinates for you.
-
- The basic layer consists of a \emph{core}, which consists of several
- interdependent packages that can only be loaded \emph{en bloc}, and
- additional \emph{modules} that extend the core by more
- special-purpose commands like node management or a plotting
- interface. For instance, the \textsc{beamer} package uses only the
- core and not, say, the |shapes| modules.
-\end{description}
-
-In theory, \tikzname\ itself is just one of several possible ``frontends''.
-which are sets of commands or a special syntax that makes using the basic layer
-easier. A problem with directly using the basic layer is that code written for
-this layer is often too ``verbose''. For example, to draw a simple triangle,
-you may need as many as five commands when using the basic layer: One for
-beginning a path at the first corner of the triangle, one for extending the
-path to the second corner, one for going to the third, one for closing the
-path, and one for actually painting the triangle (as opposed to filling it).
-With the \tikzname\ frontend all this boils down to a single simple
-\textsc{metafont}-like command:
-%
-\begin{verbatim}
-\draw (0,0) -- (1,0) -- (1,1) -- cycle;
-\end{verbatim}
-
-In practice, \tikzname\ is the only ``serious'' frontend for \pgfname. It gives
-you access to all features of \pgfname, but it is intended to be easy to use.
-The syntax is a mixture of \textsc{metafont} and \textsc{pstricks} and some
-ideas of myself. There are other frontends besides \tikzname, but they are intended
-more as ``technology studies'' and less as serious alternatives to
-\tikzname. In particular, the |pgfpict2e| frontend reimplements the standard
-\LaTeX\ |{picture}| environment and commands like |\line| or |\vector| using
-the \pgfname\ basic layer. This layer is not really ``necessary'' since the
-|pict2e.sty| package does at least as good a job at reimplementing the
-|{picture}| environment. Rather, the idea behind this package is to have a
-simple demonstration of how a frontend can be implemented.
-
-Since most users will only use \tikzname\ and almost no one will use the system
-layer directly, this manual is mainly about \tikzname\ in the first parts; the
-basic layer and the system layer are explained at the end.
-
-
-\subsection{Comparison with Other Graphics Packages}
-
-\tikzname\ is not the only graphics package for \TeX. In the following, I try
-to give a reasonably fair comparison of \tikzname\ and other packages.
-%
-\begin{enumerate}
- \item The standard \LaTeX\ |{picture}| environment allows you to create
- simple graphics, but little more. This is certainly not due to a lack
- of knowledge or imagination on the part of \LaTeX's designer(s).
- Rather, this is the price paid for the |{picture}| environment's
- portability: It works together with all backend drivers.
- \item The |pstricks| package is certainly powerful enough to create any
- conceivable kind of graphic, but it is not really portable. Most
- importantly, it does not work with |pdftex| nor with any other driver
- that produces anything but PostScript code.
-
- Compared to \tikzname, |pstricks| has a similar support base. There
- are many nice extra packages for special purpose situations that have
- been contributed by users over the last decade. The \tikzname\ syntax
- is more consistent than the |pstricks| syntax as \tikzname\ was
- developed ``in a more centralized manner'' and also ``with the
- shortcomings on |pstricks| in mind''.
- \item The |xypic| package is an older package for creating graphics.
- However, it is more difficult to use and to learn because the syntax
- and the documentation are a bit cryptic.
- \item The |dratex| package is a small graphic package for creating a
- graphics. Compared to the other package, including \tikzname, it is
- very small, which may or may not be an advantage.
- \item The |metapost| program is a powerful alternative to \tikzname. It
- used to be an external program, which entailed a bunch of problems,
- but in Lua\TeX\ it is now built in. An obstacle with |metapost| is
- the inclusion of labels. This is \emph{much} easier to achieve using
- \pgfname.
- \item The |xfig| program is an important alternative to \tikzname\ for
- users who do not wish to ``program'' their graphics as is necessary
- with \tikzname\ and the other packages above. There is a conversion
- program that will convert |xfig| graphics to \tikzname.
-\end{enumerate}
-
-
-\subsection{Utility Packages}
-
-The \pgfname\ package comes along with a number of utility package that are not
-really about creating graphics and which can be used independently of \pgfname.
-However, they are bundled with \pgfname, partly out of convenience, partly
-because their functionality is closely intertwined with \pgfname. These utility
-packages are:
-%
-\begin{enumerate}
- \item The |pgfkeys| package defines a powerful key management facility.
- It can be used completely independently of \pgfname.
- \item The |pgffor| package defines a useful |\foreach| statement.
- \item The |pgfcalendar| package defines macros for creating calendars.
- Typically, these calendars will be rendered using \pgfname's graphic
- engine, but you can use |pgfcalendar| also typeset calendars using
- normal text. The package also defines commands for ``working'' with
- dates.
- \item The |pgfpages| package is used to assemble several pages into a
- single page. It provides commands for assembling several ``virtual
- pages'' into a single ``physical page''. The idea is that whenever
- \TeX\ has a page ready for ``shipout'', |pgfpages| interrupts this
- shipout and instead stores the page to be shipped out in a special
- box. When enough ``virtual pages'' have been accumulated in this way,
- they are scaled down and arranged on a ``physical page'', which then
- \emph{really} shipped out. This mechanism allows you to create ``two
- page on one page'' versions of a document directly inside \LaTeX\
- without the use of any external programs. However, |pgfpages| can do
- quite a lot more than that. You can use it to put logos and watermark
- on pages, print up to 16 pages on one page, add borders to pages, and
- more.
-\end{enumerate}
-
-
-\subsection{How to Read This Manual}
-
-This manual describes both the design of \tikzname\ and its usage. The
-organization is very roughly according to ``user-friendliness''. The commands
-and subpackages that are easiest and most frequently used are described first,
-more low-level and esoteric features are discussed later.
-
-If you have not yet installed \tikzname, please read the installation first.
-Second, it might be a good idea to read the tutorial. Finally, you might wish
-to skim through the description of \tikzname. Typically, you will not need to
-read the sections on the basic layer. You will only need to read the part on
-the system layer if you intend to write your own frontend or if you wish to
-port \pgfname\ to a new driver.
-
-The ``public'' commands and environments provided by the system are described
-throughout the text. In each such description, the described command,
-environment or option is printed in red. Text shown in green is optional and
-can be left out.
-
-
-\subsection{Authors and Acknowledgements}
-\label{section-authors}
-
-The bulk of the \pgfname\ system and its documentation was written by Till
-Tantau. A further member of the main team is Mark Wibrow, who is responsible,
-for example, for the \pgfname\ mathematical engine, many shapes, the decoration
-engine, and matrices. The third member is Christian Feuers\"anger who
-contributed the floating point library, image externalization, extended key
-processing, and automatic hyperlinks in the manual.
-
-Furthermore, occasional contributions have been made by Christophe Jorssen,
-Jin-Hwan Cho, Olivier Binda, Matthias Schulz, Ren\'ee Ahrens, Stephan Schuster,
-and Thomas Neumann.
-
-Additionally, numerous people have contributed to the \pgfname\ system by
-writing emails, spotting bugs, or sending libraries and patches. Many thanks to
-all these people, who are too numerous to name them all!
-
-
-\subsection{Getting Help}
-
-When you need help with \pgfname\ and \tikzname, please do the following:
-
-\begin{enumerate}
- \item Read the manual, at least the part that has to do with your
- problem.
- \item If that does not solve the problem, try having a look at the
- GitHub development page for \pgfname\ and \tikzname\ (see the
- title of this document). Perhaps someone has already reported a
- similar problem and someone has found a solution.
- \item On the website you will find numerous forums for getting help.
- There, you can write to help forums, file bug reports, join mailing
- lists, and so on.
- \item Before you file a bug report, especially a bug report concerning
- the installation, make sure that this is really a bug. In particular,
- have a look at the |.log| file that results when you \TeX\ your
- files. This |.log| file should show that all the right files are
- loaded from the right directories. Nearly all installation problems
- can be resolved by looking at the |.log| file.
- \item \emph{As a last resort} you can try to email me (Till Tantau) or,
- if the problem concerns the mathematical engine, Mark Wibrow. I do
- not mind getting emails, I simply get way too many of them. Because
- of this, I cannot guarantee that your emails will be answered in a
- timely fashion or even at all. Your chances that your problem will
- be fixed are somewhat higher if you mail to the \pgfname\ mailing
- list (naturally, I read this list and answer questions when I have
- the time).
-\end{enumerate}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-3d.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-3d.tex
deleted file mode 100644
index 79bb47a2f7..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-3d.tex
+++ /dev/null
@@ -1,245 +0,0 @@
-% 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{Three Dimensional Drawing Library}
-
-\begin{tikzlibrary}{3d}
- This package provides some styles and options for drawing three dimensional
- shapes.
-\end{tikzlibrary}
-
-
-\subsection{Coordinate Systems}
-
-\begin{coordinatesystem}{xyz cylindrical}
- The |xyz cylindrical| coordinate system allows to you specify a point in
- terms of cylindrical coordinates, sometimes also referred to as cylindrical
- polar coordinates or polar cylindrical coordinates. It is very similar to
- the |canvas polar| and |xy polar| coordinate systems with the difference
- that you provide an elevation over the $xy$-plane using the |z| key.
- %
- \begin{key}{/tikz/cs/angle=\meta{degrees} (initially 0)}
- The angle of the coordinate interpreted in the ellipse whose axes are
- the $x$-vector and the $y$-vector.
- \end{key}
- %
- \begin{key}{/tikz/cs/radius=\meta{number} (initially 0)}
- A factor by which the $x$-vector and $y$-vector are multiplied prior to
- forming the ellipse.
- \end{key}
- %
- \begin{key}{/tikz/cs/z=\meta{number} (initially 0)}
- Factor by which the $z$-vector is multiplied.
- \end{key}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{3d}}]
-\begin{tikzpicture}[->]
- \draw (0,0,0) -- (xyz cylindrical cs:radius=1);
- \draw (0,0,0) -- (xyz cylindrical cs:radius=1,angle=90);
- \draw (0,0,0) -- (xyz cylindrical cs:z=1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{coordinatesystem}
-
-\begin{coordinatesystem}{xyz spherical}
- The |xyz spherical| coordinate system allows you to specify a point in
- terms of spherical coordinates.
- %
- \begin{key}{/tikz/cs/radius=\meta{number} (initially 0)}
- Factor by which the $x$-, $y$-, and $z$-vector are multiplied.
- \end{key}
- %
- \begin{key}{/tikz/cs/latitude=\meta{degrees} (initially 0)}
- Angle of the coordinate between the $y$- and $z$-vector, measured from
- the $y$-vector.
- \end{key}
- %
- \begin{key}{/tikz/cs/longitude=\meta{degrees} (initially 0)}
- Angle of the coordinate between the $x$- and $y$-vector, measured from
- the $y$-vector.
- \end{key}
- %
- \begin{key}{/tikz/cs/angle=\meta{degrees} (initially 0)}
- Same as |longitude|.
- \end{key}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{3d}}]
-\begin{tikzpicture}[->]
- \draw (0,0,0) -- (xyz spherical cs:radius=1);
- \draw (0,0,0) -- (xyz spherical cs:radius=1,latitude=90);
- \draw (0,0,0) -- (xyz spherical cs:radius=1,longitude=90);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{coordinatesystem}
-
-
-\subsection{Coordinate Planes}
-
-Sometimes drawing with full three dimensional coordinates is not necessary and
-it suffices to draw in two dimensions but in a different coordinate plane. The
-following options help you to switch to a different plane.
-
-
-\subsubsection{Switching to an arbitrary plane}
-
-\begin{key}{/tikz/plane origin=\meta{point} (initially {(0,0)})}
- Origin of the plane.
-\end{key}
-
-\begin{key}{/tikz/plane x=\meta{point} (initially {(1,0)})}
- Unit vector of the $x$-direction in the new plane.
-\end{key}
-
-\begin{key}{/tikz/plane y=\meta{point} (initially {(0,1)})}
- Unit vector of the $y$-direction in the new plane.
-\end{key}
-
-\begin{key}{/tikz/canvas is plane}
- Perform the transformation into the new canvas plane using the units above.
- Note that you have to set the units \emph{before} calling
- |canvas is plane|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{3d}}]
-\begin{tikzpicture}[
- ->,
- plane x={(0.707,-0.707)},
- plane y={(0.707,0.707)},
- canvas is plane,
-]
- \draw (0,0) -- (1,0);
- \draw (0,0) -- (0,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Predefined planes}
-
-\begin{key}{/tikz/canvas is xy plane at z=\meta{dimension}}
- A plane with
- %
- \begin{itemize}
- \item |plane origin={(0,0,|\meta{dimension}|)}|,
- \item |plane x={(1,0,|\meta{dimension}|)}|, and
- \item |plane y={(0,1,|\meta{dimension}|)}|.
- \end{itemize}
-\end{key}
-
-\begin{key}{/tikz/canvas is yx plane at z=\meta{dimension}}
- A plane with
- %
- \begin{itemize}
- \item |plane origin={(0,0,|\meta{dimension}|)}|,
- \item |plane x={(0,1,|\meta{dimension}|)}|, and
- \item |plane y={(1,0,|\meta{dimension}|)}|.
- \end{itemize}
-\end{key}
-
-\begin{key}{/tikz/canvas is xz plane at y=\meta{dimension}}
- A plane with
- %
- \begin{itemize}
- \item |plane origin={(0,|\meta{dimension}|,0)}|,
- \item |plane x={(1,|\meta{dimension}|,0)}|, and
- \item |plane y={(0,|\meta{dimension}|,1)}|.
- \end{itemize}
-\end{key}
-
-\begin{key}{/tikz/canvas is zx plane at y=\meta{dimension}}
- A plane with
- %
- \begin{itemize}
- \item |plane origin={(0,|\meta{dimension}|,0)}|,
- \item |plane x={(0,|\meta{dimension}|,1)}|, and
- \item |plane y={(1,|\meta{dimension}|,0)}|.
- \end{itemize}
-\end{key}
-
-\begin{key}{/tikz/canvas is yz plane at x=\meta{dimension}}
- A plane with
- %
- \begin{itemize}
- \item |plane origin={(|\meta{dimension}|,0,0)}|,
- \item |plane x={(|\meta{dimension}|,1,0)}|, and
- \item |plane y={(|\meta{dimension}|,0,1)}|.
- \end{itemize}
-\end{key}
-
-\begin{key}{/tikz/canvas is zy plane at x=\meta{dimension}}
- A plane with
- %
- \begin{itemize}
- \item |plane origin={(|\meta{dimension}|,0,0)}|,
- \item |plane x={(|\meta{dimension}|,0,1)}|, and
- \item |plane y={(|\meta{dimension}|,1,0)}|.
- \end{itemize}
-\end{key}
-
-
-\subsection{Examples}
-
-\begin{codeexample}[preamble={\usetikzlibrary{3d}}]
-\begin{tikzpicture}[z={(10:10mm)},x={(-45:5mm)}]
- \def\wave{
- \draw[fill,thick,fill opacity=.2]
- (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0)
- sin (5,1) cos (6,0) sin (7,-1) cos (8,0)
- sin (9,1) cos (10,0)sin (11,-1)cos (12,0);
- \foreach \shift in {0,4,8}
- {
- \begin{scope}[xshift=\shift cm,thin]
- \draw (.5,0) -- (0.5,0 |- 45:1cm);
- \draw (1,0) -- (1,1);
- \draw (1.5,0) -- (1.5,0 |- 45:1cm);
- \draw (2.5,0) -- (2.5,0 |- -45:1cm);
- \draw (3,0) -- (3,-1);
- \draw (3.5,0) -- (3.5,0 |- -45:1cm);
- \end{scope}
- }
- }
- \begin{scope}[canvas is zy plane at x=0,fill=blue]
- \wave
- \node at (6,-1.5) [transform shape] {magnetic field};
- \end{scope}
- \begin{scope}[canvas is zx plane at y=0,fill=red]
- \draw[help lines] (0,-2) grid (12,2);
- \wave
- \node at (6,1.5) [rotate=180,xscale=-1,transform shape] {electric field};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{3d}}]
-\begin{tikzpicture}
- \begin{scope}[canvas is zy plane at x=0]
- \draw (0,0) circle (1cm);
- \draw (-1,0) -- (1,0) (0,-1) -- (0,1);
- \end{scope}
-
- \begin{scope}[canvas is zx plane at y=0]
- \draw (0,0) circle (1cm);
- \draw (-1,0) -- (1,0) (0,-1) -- (0,1);
- \end{scope}
-
- \begin{scope}[canvas is xy plane at z=0]
- \draw (0,0) circle (1cm);
- \draw (-1,0) -- (1,0) (0,-1) -- (0,1);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-angles.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-angles.tex
deleted file mode 100644
index e210cb2d75..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-angles.tex
+++ /dev/null
@@ -1,109 +0,0 @@
-% 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{Angle Library}
-\label{section-angle}
-
-\begin{tikzlibrary}{angles}
- This library defines pic types for drawing angles.
-\end{tikzlibrary}
-
-\begin{pictype}{angle}{\opt{|=|\meta{A}|--|\meta{B}|--|\meta{C}}}
- This pic adds a drawing of an angle to the current path. This ``drawing of
- an angle'' consist of a ``sector'' or ``wedge'' or ``slice'' whose pointed
- end is at point \meta{B} and whose straight sides lie on the lines form
- \meta{B} to \meta{A} and from \meta{B} to \meta{C}. The length of these
- lines is governed by the following key:
- %
- \begin{key}{/tikz/angle radius=\meta{dimension} (initially 5mm)}
- The length of the sides of the angle's wedge:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{angles}}]
-\tikz \draw (2,0) coordinate (A) -- (0,0) coordinate (B)
- -- (-1,-1) coordinate (C)
- pic [fill=black!50] {angle = A--B--C}
- pic [draw,->,red,thick,angle radius=1cm] {angle = C--B--A};
-\end{codeexample}
- \end{key}
-
- The three points \meta{A}, \meta{B}, and \meta{C} \emph{must} be the names
- of nodes or coordinates; you cannot use direct coordinates like ``|(1,1)|''
- here.
-
- You can leave out the three points, in this case the text |A--B--C| is
- used; so in the above examples we could just have written |{angle}| in the
- first pic.
-
- Concerning the sector that makes up the drawing of the angle, the angular
- part of this sector is drawn in front of the path if the |draw| option is
- given to the |pic|, while filled sector is drawn behind the |pic|, provided
- an option like |fill| or |shade| is passed to the pic. The following
- example shows the difference:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{angles}}]
-\tikz \draw [line width=2mm]
- (2,0) coordinate (A) -- (0,0) coordinate (B)
- -- (1,1) coordinate (C)
- pic [draw=blue, fill=blue!50, angle radius=1cm] {angle};
-\end{codeexample}
-
- When |pic text| is set (which you typically do by using the quotes syntax),
- a node will be created whose name is empty (and, thus, inherits the pic's
- name) and which will be at the half-way angle between the lines to \meta{A}
- and \meta{C} and whose distance from \meta{B} is |angle radius| times the
- following factor:
- %
- \begin{key}{/tikz/angle eccentricity=\meta{factor} (initially 0.6)}
-\begin{codeexample}[preamble={\usetikzlibrary{angles,quotes}}]
-\tikz \draw (2,0) coordinate (A) -- (0,0) coordinate (B)
- -- (1,1) coordinate (C)
- pic ["$\alpha$", draw, ->] {angle};
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{angles,quotes}}]
-\tikz \draw (2,0) coordinate (A) -- (0,0) coordinate (B)
- -- (1,1) coordinate (C)
- pic ["$\alpha$", draw, angle eccentricity=1] {angle};
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{angles,quotes}}]
-\tikz {
- \draw (2,0) coordinate (A) -- (0,0) coordinate (B)
- -- (1,1) coordinate (C)
- pic (alpha) ["$\alpha$", draw] {angle};
-
- \draw (alpha) circle [radius=5pt];
-}
-\end{codeexample}
- \end{key}
-\end{pictype}
-
-\begin{pictype}{right angle}{\opt{|=|\meta{A}|--|\meta{B}|--|\meta{C}}}
- This pic adds a drawing of a right angle to the current path. It works in
- the same way as |angle| pic.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{angles}}]
- \tikz
- \draw (0,0,0) coordinate (O)
- (1,0,0) coordinate (A) -- (O)
- (0,0,1) coordinate (B) -- (O)
- (0,1,0) coordinate (C) -- (O)
- pic [fill=gray,angle radius=4mm] {right angle = A--O--B}
- pic [draw,red,thick,angle eccentricity=.5,pic text=.]
- {right angle = A--O--C};
-\end{codeexample}
- %
-\end{pictype}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-arrows.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-arrows.tex
deleted file mode 100644
index 9597701c41..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-arrows.tex
+++ /dev/null
@@ -1,245 +0,0 @@
-% Copyright 2018 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{Arrow Tip Library}
-\label{section-library-arrows}
-
-The libraries |arrows| and |arrows.spaced| from older versions of \pgfname\ are
-still available for compatibility, but they are considered deprecated.
-
-The standard arrow tips, which are loaded by the library |arrows.meta|, are
-documented in Section~\ref{section-arrows-meta}.
-
-
-% \subsection{Mathematical Arrow Tips}
-%
-% \begin{tabular}{ll}
-% \symarrow{to} \\
-% \symarrow{to reversed} \\
-% \symarrowdouble{implies} \\
-% \symarrow{spaced to} \\
-% \symarrow{spaced to reversed} \\
-% \symarrowdouble{spaced implies} \\
-% \end{tabular}
-%
-%
-% \subsection{Triangular Arrow Tips}
-%
-% \begin{tabular}{ll}
-% \symarrowdouble{latex} \\
-% \symarrowdouble{latex reversed} \\
-% \symarrow{latex'} \\
-% \symarrow{latex' reversed} \\
-% \symarrowdouble{stealth} \\
-% \symarrowdouble{stealth reversed} \\
-% \symarrow{stealth'} \\
-% \symarrow{stealth' reversed}\\
-% \symarrow{triangle 90} \\
-% \symarrow{triangle 90 reversed} \\
-% \symarrow{triangle 60} \\
-% \symarrow{triangle 60 reversed} \\
-% \symarrow{triangle 45} \\
-% \symarrow{triangle 45 reversed} \\
-% \symarrow{open triangle 90} \\
-% \symarrow{open triangle 90 reversed} \\
-% \symarrow{open triangle 60} \\
-% \symarrow{open triangle 60 reversed} \\
-% \symarrow{open triangle 45} \\
-% \symarrow{open triangle 45 reversed} \\
-% \end{tabular}
-%
-% \medskip
-% \noindent
-% \begin{tabular}{ll}
-% \symarrowdouble{spaced latex} \\
-% \symarrowdouble{spaced latex reversed} \\
-% \symarrow{spaced latex'} \\
-% \symarrow{spaced latex' reversed} \\
-% \symarrowdouble{spaced stealth} \\
-% \symarrowdouble{spaced stealth reversed} \\
-% \symarrow{spaced stealth'} \\
-% \symarrow{spaced stealth' reversed}\\
-% \end{tabular}
-%
-% \medskip
-% \noindent
-% \begin{tabular}{ll}
-% \symarrow{spaced triangle 90} \\
-% \symarrow{spaced triangle 90 reversed} \\
-% \symarrow{spaced triangle 60} \\
-% \symarrow{spaced triangle 60 reversed} \\
-% \symarrow{spaced triangle 45} \\
-% \symarrow{spaced triangle 45 reversed} \\
-% \symarrow{spaced open triangle 90} \\
-% \symarrow{spaced open triangle 90 reversed} \\
-% \symarrow{spaced open triangle 60} \\
-% \symarrow{spaced open triangle 60 reversed} \\
-% \symarrow{spaced open triangle 45} \\
-% \symarrow{spaced open triangle 45 reversed} \\
-% \end{tabular}
-%
-%
-% \subsection{Barbed Arrow Tips}
-%
-% \begin{tabular}{ll}
-% \symarrow{angle 90} \\
-% \symarrow{angle 90 reversed} \\
-% \symarrow{angle 60} \\
-% \symarrow{angle 60 reversed} \\
-% \symarrow{angle 45} \\
-% \symarrow{angle 45 reversed} \\
-% \symarrow{hooks} \\
-% \symarrow{hooks reversed} \\
-% \end{tabular}
-%
-% \medskip
-% \noindent
-% \begin{tabular}{ll}
-% \symarrow{spaced angle 90} \\
-% \symarrow{spaced angle 90 reversed} \\
-% \symarrow{spaced angle 60} \\
-% \symarrow{spaced angle 60 reversed} \\
-% \symarrow{spaced angle 45} \\
-% \symarrow{spaced angle 45 reversed} \\
-% \symarrow{spaced hooks} \\
-% \symarrow{spaced hooks reversed} \\
-% \end{tabular}
-%
-%
-% \subsection{Bracket-Like Arrow Tips}
-%
-% {
-% \bigskip
-% \catcode`\|=12
-% \begin{tabular}{ll}
-% \sarrow{[}{]} \\
-% \sarrow{]}{[} \\
-% \sarrow{(}{)} \\
-% \sarrow{)}{(} \\
-% \index{*vbar@\protect\texttt{\protect\myvbar} arrow tip}%
-% \index{Arrow tips!*vbar@\protect\texttt{\protect\myvbar}}%
-% \texttt{\char`\|-\char`\|} & yields thick
-% \begin{tikzpicture}[arrows={|-|},thick]
-% \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex);
-% \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ;
-% \draw (0pt,.5ex) -- (1cm,.5ex);
-% \end{tikzpicture} and thin
-% \begin{tikzpicture}[arrows={|-|},thin]
-% \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex);
-% \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ;
-% \draw (0pt,.5ex) -- (1cm,.5ex);
-% \end{tikzpicture}\\
-% \sarrow{spaced [}{spaced ]} \\
-% \sarrow{spaced ]}{spaced [} \\
-% \sarrow{spaced (}{spaced )} \\
-% \sarrow{spaced )}{spaced (} \\
-% \index{*spaced vbar@\protect\texttt{spaced \protect\myvbar} arrow tip}%
-% \index{Arrow tips!*spaced vbar@\protect\texttt{spaced \protect\myvbar}}%
-% \texttt{spaced \char`\|-spaced \char`\|} & yields thick
-% \begin{tikzpicture}[arrows={spaced |-spaced |},thick]
-% \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex);
-% \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ;
-% \draw (0pt,.5ex) -- (1cm,.5ex);
-% \end{tikzpicture} and thin
-% \begin{tikzpicture}[arrows={spaced |-spaced |},thin]
-% \useasboundingbox (-1mm,-0.5ex) rectangle (1.1cm,2ex);
-% \fill [black!15] (1cm,-.5ex) rectangle (1.1cm,1.5ex) (-1mm,-.5ex) rectangle (0mm,1.5ex) ;
-% \draw (0pt,.5ex) -- (1cm,.5ex);
-% \end{tikzpicture}
-% \end{tabular}
-% }
-%
-% \subsection{Circle, Diamond and Square Arrow Tips}
-%
-%
-% \begin{tabular}{ll}
-% \symarrow{o} \\
-% \symarrow{*} \\
-% \symarrow{diamond} \\
-% \symarrow{open diamond} \\
-% \symarrow{square} \\
-% \symarrow{open square} \\
-% \end{tabular}
-%
-%
-% \medskip
-% \noindent
-% \begin{tabular}{ll}
-% \symarrow{spaced o} \\
-% \symarrow{spaced *} \\
-% \symarrow{spaced diamond} \\
-% \symarrow{spaced open diamond} \\
-% \symarrow{spaced square} \\
-% \symarrow{spaced open square} \\
-% \end{tabular}
-%
-%
-% \subsection{Serif-Like Arrow Tips}
-%
-% \begin{tabular}{ll}
-% \symarrow{serif cm} \\
-% \symarrow{spaced serif cm}
-% \end{tabular}
-%
-%
-% \subsection{Partial Arrow Tips}
-%
-% \begin{tabular}{ll}
-% \symarrow{left to} \\
-% \symarrow{left to reversed} \\
-% \symarrow{right to} \\
-% \symarrow{right to reversed} \\
-% \symarrow{left hook} \\
-% \symarrow{left hook reversed} \\
-% \symarrow{right hook} \\
-% \symarrow{right hook reversed}\\
-% \symarrow{spaced left to} \\
-% \symarrow{spaced left to reversed} \\
-% \symarrow{spaced right to} \\
-% \symarrow{spaced right to reversed} \\
-% \symarrow{spaced left hook} \\
-% \symarrow{spaced left hook reversed} \\
-% \symarrow{spaced right hook} \\
-% \symarrow{spaced right hook reversed}
-% \end{tabular}
-%
-%
-% \subsection{Line Caps}
-%
-% \begin{tabular}{ll}
-% \carrow{round cap} \\
-% \carrow{butt cap} \\
-% \carrow{triangle 90 cap} \\
-% \carrow{triangle 90 cap reversed} \\
-% \carrow{fast cap} \\
-% \carrow{fast cap reversed} \\
-% \carrow{spaced round cap} \\
-% \carrow{spaced butt cap} \\
-% \carrow{spaced triangle 90 cap} \\
-% \carrow{spaced triangle 90 cap reversed} \\
-% \carrow{spaced fast cap} \\
-% \carrow{spaced fast cap reversed} \\
-% \end{tabular}
-%
-%
-% \subsection{Spacing Tips}
-%
-% The spacing arrow tips are useful for combining them with other arrows
-% to get arrows that do not touch the end of the line.
-%
-% \begin{tabular}{ll}
-% \symarrow{space} \\
-% \end{tabular}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-automata.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-automata.tex
deleted file mode 100644
index c56bb6fd11..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-automata.tex
+++ /dev/null
@@ -1,335 +0,0 @@
-% 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{Automata Drawing Library}
-
-\begin{tikzlibrary}{automata}
- This packages provides shapes and styles for drawing finite state automata
- and Turing machines.
-\end{tikzlibrary}
-
-
-\subsection{Drawing Automata}
-
-The |automata| (drawing) library is intended to make it easy to draw finite
-automata and Turing machines. It does not cover every situation imaginable, but
-most finite automata and Turing machines found in text books can be drawn in a
-nice and convenient fashion using this library.
-
-To draw an automaton, proceed as follows:
-%
-\begin{enumerate}
- \item For each state of the automaton, there should be one node with the
- option |state|.
- \item To place the states, you can either use absolute positions or
- relative positions, using options like |above| or |right|.
- \item Give a unique name to each state node.
- \item Accepting and initial states are indicated by adding the options
- |accepting| and |initial|, respectively, to the state nodes.
- \item Once the states are fixed, the edges can be added. For this, the
- |edge| operation is most useful. It is, however, also possible to add
- edges after each node has been placed.
- \item For loops, use the |edge [loop]| operation.
-\end{enumerate}
-
-Let us now see how this works for a real example. Let us consider a
-nondeterministic four state automaton that checks whether an input contains the
-sequence $0^*1$ or the sequence $1^*0$.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{automata,positioning}}]
-\begin{tikzpicture}[shorten >=1pt,node distance=2cm,on grid,auto]
- \draw[help lines] (0,0) grid (3,2);
-
- \node[state,initial] (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,accepting](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}
-
-
-\subsection{States With and Without Output}
-
-The |state| style actually just ``selects'' a default underlying style. Thus,
-you can define multiple new complicated state style and then simply set the
-|state| style to your given style to get the desired kind of styles.
-
-By default, the following state styles are defined:
-%
-\begin{stylekey}{/tikz/state without output}
- This node style causes nodes to be drawn as circles. Also, this style calls
- |every state|.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/state with output}
- This node style causes nodes to be drawn as split circles, that is, using
- the |circle split| shape. In the upper part of the shape you have the name
- of the style, in the lower part the output is placed. To specify the
- output, use the command |\nodepart{lower}| inside the node. This style also
- calls |every state|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{automata}}]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \node[state without output] {$q_0$};
-
- \node[state with output] at (2,0) {$q_1$ \nodepart{lower} $00$};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/state (initially state without output)}
- You should redefine it to something else, if you wish to use states of a
- different nature.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{automata}}]
-\begin{tikzpicture}[state/.style=state with output]
- \node[state] {$q_0$ \nodepart{lower} $11$};
- \node[state] at (2,0) {$q_1$ \nodepart{lower} $00$};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/every state (initially \normalfont empty)}
- This style is used by |state with output| and also by
- |state without output|. By default, it does nothing, but you can use it to
- make your state look more fancy:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,automata,positioning}}]
-\begin{tikzpicture}[shorten >=1pt,node distance=2cm,on grid,>={Stealth[round]},
- every state/.style={draw=blue!50,very thick,fill=blue!20}]
-
- \node[state,initial] (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$};
-
- \path[->] (q_0) edge node [above left] {0} (q_1)
- edge node [below left] {1} (q_2)
- (q_1) edge [loop above] node {0} ()
- (q_2) edge [loop below] node {1} ();
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsection{Initial and Accepting States}
-
-The styles |initial| and |accepting| are similar to the |state| style as they
-also just select an ``underlying'' style, which installs the actual settings
-for initial and accepting states.
-
-Let us start with the initial states.
-%
-\begin{stylekey}{/tikz/initial (initially initial by arrow)}
- This style is used to draw initial states.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/initial by arrow}
- This style causes an arrow and, possibly, some text to be added to the
- node. The arrow points from the text to the node. The node text and the
- direction and the distance can be set using the following key:
- %
- \begin{key}{/tikz/initial text=\meta{text} (initially start)}
- This key sets the text to be used. Use an empty text to suppress all
- text.
- \end{key}
- %
- \begin{key}{/tikz/initial where=\meta{direction} (initially left)}
- Set the place where the text should be shown. Allowed values are
- |above|, |below|, |left|, and |right|.
- \end{key}
- %
- \begin{key}{/tikz/initial distance=\meta{distance} (initially 3ex)}
- Sets the length of the arrow leading from the text to the state node.
- \end{key}
- %
- \begin{stylekey}{/tikz/every initial by arrow (initially \normalfont empty)}
- This style is executed at the beginning of every path that contains the
- arrow and the text. You can use it to, say, make the text red or
- whatever.
- \end{stylekey}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{automata}}]
-\begin{tikzpicture}[every initial by arrow/.style={text=red,->>}]
- \node[state,initial,initial distance=2cm] {$q_0$};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/initial above}
- This is a shorthand for |initial by arrow,initial where=above|.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/initial below}
- Works similarly to the previous option.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/initial left}
- Works similarly to the previous option.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/initial right}
- Works similarly to the previous option.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/initial by diamond}
- This style uses a diamond to indicate an initial node.
-\end{stylekey}
-
-For the accepting states, the situation is similar: There is also an
-|accepting| style that selects the way accepting states are rendered. There are
-now two options: First, |accepting by arrow|, which works the same way as
-|initial by arrow|, only with the direction of arrow reversed, and
-|accepting by double|, where accepting states get a double line around them.
-
-\begin{stylekey}{/tikz/accepting (initially accepting by double)}
- This style is used to draw accepting states. You can replace this by the
- style |accepting by arrow| to get accepting states with an arrow leaving
- them.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/accepting by double}
- This style causes a double line to be drawn around a state.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/accepting by arrow}
- This style causes an arrow and, possibly, some text to be added to the
- node. The arrow points to the text from the node.
-
- The same options as for initial states can be used, only with |initial|
- replaced by |accepting|:
- %
- \begin{key}{/tikz/accepting text=\meta{text} (initially \normalfont empty)}
- This key sets the text to be used.
- \end{key}
- %
- \begin{key}{/tikz/accepting where=\meta{direction} (initially right)}
- Set the place where the text should be shown. Allowed values are
- |above|, |below|, |left|, and |right|.
- \end{key}
- %
- \begin{key}{/tikz/initial distance=\meta{distance} (initially 3ex)}
- Sets the length of the arrow leading from the text to the state
- node.
- \end{key}
- %
- \begin{stylekey}{/tikz/every accepting by arrow (initially \normalfont empty)}
- Executed at the beginning of every path that contains the arrow and the
- text.
- \end{stylekey}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,automata,positioning}}]
-\begin{tikzpicture}
- [shorten >=1pt,node distance=2cm,on grid,>={Stealth[round]},initial text=,
- every state/.style={draw=blue!50,very thick,fill=blue!20},
- accepting/.style=accepting by arrow]
-
- \node[state,initial] (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,accepting](q_3) [below right=of q_1] {$q_3$};
-
- \path[->] (q_0) edge node [above left] {0} (q_1)
- edge node [below left] {1} (q_2)
- (q_1) edge node [above right] {1} (q_3)
- edge [loop above] node {0} ()
- (q_2) edge node [below right] {0} (q_3)
- edge [loop below] node {1} ();
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/accepting above}
- This is a shorthand for |accepting by arrow,accepting where=above|.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/accepting below}
- Works similarly to the previous option.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/accepting left}
- Works similarly to the previous option.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/accepting right}
- Works similarly to the previous option.
-\end{stylekey}
-
-
-\subsection{Examples}
-
-In the following example, we once more typeset the automaton presented in the
-previous sections. This time, we use the following rule for accepting/initial
-state: Initial states are red, accepting states are green, and normal states
-are orange. Then, we must find a path from a red state to a green state.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,automata,positioning,shadows}}]
-\begin{tikzpicture}[shorten >=1pt,node distance=2cm,on grid,>={Stealth[round]},thick,
- every state/.style={fill,draw=none,orange,text=white,circular drop shadow},
- accepting/.style ={green!50!black,text=white},
- initial/.style ={red,text=white}]
-
- \node[state,initial] (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,accepting](q_3) [below right=of q_1] {$q_3$};
-
- \path[->] (q_0) edge node [above left] {0} (q_1)
- edge node [below left] {1} (q_2)
- (q_1) edge node [above right] {1} (q_3)
- edge [loop above] node {0} ()
- (q_2) edge node [below right] {0} (q_3)
- edge [loop below] node {1} ();
-\end{tikzpicture}
-\end{codeexample}
-
-The next example is the current candidate for the five-state busiest beaver:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,automata,positioning}}]
-\begin{tikzpicture}[->,>={Stealth[round]},shorten >=1pt,%
- auto,node distance=2cm,on grid,semithick,
- inner sep=2pt,bend angle=45]
- \node[initial,state] (A) {$q_a$};
- \node[state] (B) [above right=of A] {$q_b$};
- \node[state] (D) [below right=of A] {$q_d$};
- \node[state] (C) [below right=of B] {$q_c$};
- \node[state] (E) [below=of D] {$q_e$};
-
- \path [every node/.style={font=\footnotesize}]
- (A) edge node {0,1,L} (B)
- edge node {1,1,R} (C)
- (B) edge [loop above] node {1,1,L} (B)
- edge node {0,1,L} (C)
- (C) edge node {0,1,L} (D)
- edge [bend left] node {1,0,R} (E)
- (D) edge [loop below] node {1,1,R} (D)
- edge node {0,1,R} (A)
- (E) edge [bend left] node {1,0,R} (A);
-\end{tikzpicture}
-\end{codeexample}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-babel.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-babel.tex
deleted file mode 100644
index 221a84c640..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-babel.tex
+++ /dev/null
@@ -1,94 +0,0 @@
-% Copyright 2019 by Mark Wibrow
-%
-% 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{Babel Library}
-\label{section-library-babel}
-
-\begin{tikzlibrary}{babel}
- A tiny library that make the interaction with the |babel| package easier.
- Despite the name, it may also be useful in other contexts, namely whenever
- the catcodes of important symbols are changed globally. Normally, using
- this library is always a good idea; it is not always loaded by default
- since in some rare cases it may break old code.
-\end{tikzlibrary}
-
-The problems this library tries to fix have to do with the so-called
-``catcodes'' of symbols used inside \tikzname. In normal \TeX\ operation,
-symbols like |!| or |"| are ``normal'' characters and the \tikzname\ parser
-expects them to be. Some packages, most noticeably the |babel| package,
-aggressively change these character codes so that for instance a semicolon gets
-a little extra space in |french| mode or a quotation mark followed by a
-vertical bar breaks ligatures in |german| mode.
-
-Unfortunately, \tikzname\ expects the character codes of some symbols to be
-``normal''. In some important cases it will tolerate changed character codes,
-but when the changes made by |babel| (or some other package) are too
-``aggressive'', compilation of \tikzname\ code will fail.
-
-The |babel| library of \tikzname\ is intended to help out in this situation.
-All this library does is to set the following two keys to |true|. You can,
-however, also set these keys directly and also switch them off or on
-individually and independently of this library.
-
-\begin{key}{/tikz/handle active characters in code=\opt{\meta{true or false}} (initially false)}
- When this key is set, at the beginning of every |\tikz| command and every
- |{tikzpicture}|, the character codes of all symbols used by \tikzname\ are
- reset to their normal values. Furthermore, at the beginning of each node,
- the catcodes are restored to the values they had prior to the current
- picture.
-
- The net effect of this is that, in most cases, symbols having a special
- character code can be used nicely both in \tikzname\ code and also in node
- texts.
-
- In the following, slightly silly, example we make the dot an active
- character and define it in some strange way. Now, in the later \tikzname\
- command, the dot in |3.0cm| may no longer be active and setting the
- |handle...| option achieves exactly this. However, as can be seen, the dot
- is once more active inside the node.
- %
-\begin{codeexample}[]
-\catcode`\.=\active
-\def.{\o}
-
-\tikz [handle active characters in code]
- \node [draw, minimum width=3.0cm] {hall. pe.ple};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/handle active characters in nodes=\opt{\meta{true or false}} (initially false)}
- This key is needed for a special situation: As explained for the
- |handle ... code| key, that key switches off all special meaning of symbols
- and switches them back on again at the beginning of nodes. However, there
- is one situation when this is not possible: When some text has already been
- read by \TeX, the catcodes can no longer change. Now, for normal nodes this
- is not a problem since their contents has not been read at the moment the
- catcodes are restored. In contrast for label nodes for edges, nodes
- produced by the |graph| and |quotes| libraries, and some others nodes,
- their text \emph{has} already been read when the catcodes get adjusted.
-
- The present key may help in such situations: It causes the text of all such
- ``indirectly created'' nodes to be surrounded by a call to the
- |\scantokens| command. This command attempts to reread an already read
- text, but allows catcodes to change. As users of this command will know, it
- is not a perfect substitute for directly reading the text by \TeX, but it
- normally has the desired effect.
- %
-\begin{codeexample}[]
-\catcode`\.=\active
-\def.{\o}
-
-\tikz [handle active characters in code,
- handle active characters in nodes]
- \node [draw, label=f..] {hall. pe.ple};
-\end{codeexample}
- %
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-backgrounds.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-backgrounds.tex
deleted file mode 100644
index 4d9d49e9cf..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-backgrounds.tex
+++ /dev/null
@@ -1,283 +0,0 @@
-% 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{Background Library}
-\label{section-tikz-backgrounds}
-
-\begin{tikzlibrary}{backgrounds}
- This library defines ``backgrounds'' for pictures. This does not refer to
- background pictures, but rather to frames drawn around and behind pictures.
- For example, this package allows you to just add the |framed| option to a
- picture to get a rectangular box around your picture or |gridded| to put a
- grid behind your picture.
-\end{tikzlibrary}
-
-The first use of this library is to make the following key available:
-%
-\begin{key}{/tikz/on background layer=\meta{options}}
- This key can (only) be used with a |{scope}| or |\scoped|. It will cause
- everything inside the scope to be typeset on a background layer.
-
- The \meta{options} will be executed \emph{inside} background scope. This is
- useful since \emph{other} options passed to the |{scope}| environment will
- be executed \emph{before} the actual background material starts and, thus,
- will have no effect on it.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\begin{tikzpicture}
- % On main layer:
- \fill[blue] (0,0) circle (1cm);
-
- \begin{scope}[on background layer={color=yellow}]
- \fill (-1,-1) rectangle (1,1);
- \end{scope}
-
- \begin{scope}[on background layer]
- \fill[black] (-.8,-.8) rectangle (.8,.8);
- \end{scope}
-
- % On main layer again:
- \fill[blue!50] (-.5,-1) rectangle (.5,1);
-\end{tikzpicture}
-\end{codeexample}
-
- A scope with this option set should not be ``deeply nested'' inside the
- picture since changes to the graphic state (like the color or the
- transformation matrix) ``do not survive a layer switch'', see also
- Section~\ref{section-layers} for details. In particular, setting, say, the
- line width at the beginning of a picture will not have an effect on the
- background picture.
-
- For this reason, it may be useful to setup the following style:
- %
- \begin{stylekey}{/tikz/every on background layer}
- This style is executed at the beginning of each background layer. If
- you have a global setup in |every picture|, you should consider putting
- that part of it that concerns the graphics state into this style.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\tikzset{
- every picture/.style={line width=1ex},
- every on background layer/.style={every picture}
-}
-\begin{tikzpicture}
- \draw [->] (0,0) -- (2,1);
-
- \scoped[on background layer]
- \draw[red] (0,1) -- (2,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{stylekey}
-\end{key}
-
-When this package is loaded, the following styles become available:
-%
-\begin{stylekey}{/tikz/show background rectangle}
- This style causes a rectangle to be drawn behind your graphic. This style
- option must be given to the |{tikzpicture}| environment or to the |\tikz|
- command.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\begin{tikzpicture}[show background rectangle]
- \draw (0,0) ellipse (10mm and 5mm);
-\end{tikzpicture}
-\end{codeexample}
- %
- The size of the background rectangle is determined as follows: We start
- with the bounding box of the picture. Then, a certain separator distance is
- added on the sides. This distance can be different for the $x$- and
- $y$-directions and can be set using the following options:
- %
- \begin{key}{/tikz/inner frame xsep=\meta{dimension} (initially 1ex)}
- Sets the additional horizontal separator distance for the background
- rectangle.
- \end{key}
- %
- \begin{key}{/tikz/inner frame ysep=\meta{dimension} (initially 1ex)}
- Same for the vertical separator distance.
- \end{key}
- %
- \begin{key}{/tikz/inner frame sep=\meta{dimension}}
- Sets the horizontal and vertical separator distances simultaneously.
- \end{key}
- %
- The following two styles make setting the inner separator a bit easier to
- remember:
- %
- \begin{stylekey}{/tikz/tight background}
- Sets the inner frame separator to 0pt. The background rectangle will
- have the size of the bounding box.
- \end{stylekey}
- %
- \begin{stylekey}{/tikz/loose background}
- Sets the inner frame separator to 2ex.
- \end{stylekey}
-
- You can influence how the background rectangle is rendered by setting the
- following style:
- %
- \begin{stylekey}{/tikz/background rectangle (initially draw)}
- This style dictates how the background rectangle is drawn or filled.
- The default setting causes the path of the background rectangle to be
- drawn in the usual way. Setting this style to, say, |fill=blue!20|
- causes a light blue background to be added to the picture. You can also
- use more fancy settings as shown in the following example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\begin{tikzpicture}
- [background rectangle/.style=
- {double,ultra thick,draw=red,top color=blue,rounded corners},
- show background rectangle]
- \draw (0,0) ellipse (10mm and 5mm);
-\end{tikzpicture}
-\end{codeexample}
- %
- Naturally, no one in their right mind would use the above, but here is
- a nice background:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\begin{tikzpicture}
- [background rectangle/.style=
- {draw=blue!50,fill=blue!20,rounded corners=1ex},
- show background rectangle]
- \draw (0,0) ellipse (10mm and 5mm);
-\end{tikzpicture}
-\end{codeexample}
- \end{stylekey}
-\end{stylekey}
-
-\begin{stylekey}{/tikz/framed}
- This is a shorthand for |show background rectangle|.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/show background grid}
- This style behaves similarly to the |show background rectangle| style, but
- it will not use a rectangle path, but a grid. The lower left and upper
- right corner of the grid is computed in the same way as for the background
- rectangle:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\begin{tikzpicture}[show background grid]
- \draw (0,0) ellipse (10mm and 5mm);
-\end{tikzpicture}
-\end{codeexample}
- %
- You can influence the background grid by setting the following style:
- %
- \begin{stylekey}{/tikz/background grid (initially draw,help lines)}
- This style dictates how the background grid path is drawn.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\begin{tikzpicture}
- [background grid/.style={thick,draw=red,step=.5cm},
- show background grid]
- \draw (0,0) ellipse (10mm and 5mm);
-\end{tikzpicture}
-\end{codeexample}
- \end{stylekey}
- %
- This option can be combined with the |framed| option (use the |framed|
- option first):
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\tikzset{background grid/.style={thick,draw=red,step=.5cm},
- background rectangle/.style={rounded corners,fill=yellow}}
-\begin{tikzpicture}[framed,gridded]
- \draw (0,0) ellipse (10mm and 5mm);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/gridded}
- This is a shorthand for |show background grid|.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/show background top}
- This style causes a single line to be drawn at the top of the background
- rectangle. Normally, the line coincides exactly with the top line of the
- background rectangle:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\begin{tikzpicture}[
- background rectangle/.style={fill=yellow},
- framed,show background top]
- \draw (0,0) ellipse (10mm and 5mm);
-\end{tikzpicture}
-\end{codeexample}
- %
- The following option allows you to lengthen (or shorten) the line:
- %
- \begin{key}{/tikz/outer frame xsep=\meta{dimension} (initially 0pt)}
- The \meta{dimension} is added at the left and right side of the line.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\begin{tikzpicture}
- [background rectangle/.style={fill=yellow},
- framed,
- show background top,
- outer frame xsep=1ex]
- \draw (0,0) ellipse (10mm and 5mm);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/outer frame ysep=\meta{dimension} (initially 0pt)}
- This option does not apply to the top line, but to the left and right
- lines, see below.
- \end{key}
- %
- \begin{key}{/tikz/outer frame sep=\meta{dimension}}
- Sets both the $x$- and $y$-separation.
- \end{key}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\begin{tikzpicture}
- [background rectangle={fill=blue!20},
- outer frame sep=1ex,%
- show background top,%
- show background bottom,%
- show background left,%
- show background right]
- \draw (0,0) ellipse (10mm and 5mm);
-\end{tikzpicture}
-\end{codeexample}
- %
- You can influence how the line is drawn grid by setting the following
- style:
- %
- \begin{stylekey}{/tikz/background top (initially draw)}
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\tikzset{background rectangle/.style={fill=blue!20},
- background top/.style={draw=blue!50,line width=1ex}}
-\begin{tikzpicture}[framed,show background top]
- \draw (0,0) ellipse (10mm and 5mm);
-\end{tikzpicture}
-\end{codeexample}
- \end{stylekey}
-\end{stylekey}
-
-\begin{stylekey}{/tikz/show background bottom}
- Works like the style for the top line.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/show background left}
- Works similarly.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/show background right}
- Works similarly.
-\end{stylekey}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-calc.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-calc.tex
deleted file mode 100644
index 49ece07ff9..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-calc.tex
+++ /dev/null
@@ -1,7 +0,0 @@
-
-\section{Calc Library}
-
-\begin{tikzlibrary}{calc}
- The library allows advanced Coordinate Calculations. It is documented in
- all detail in Section~\ref{tikz-lib-calc} on page~\pageref{tikz-lib-calc}.
-\end{tikzlibrary}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-calendar.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-calendar.tex
deleted file mode 100644
index 4b324a1529..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-calendar.tex
+++ /dev/null
@@ -1,976 +0,0 @@
-% 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{Calendar Library}
-\label{section-calender}
-
-\begin{tikzlibrary}{calendar}
- The library defines the |\calendar| command, which can be used to typeset
- calendars. The command relies on the |\pgfcalendar| command from the
- |pgfcalendar| package, which is loaded automatically.
-
- The |\calendar| command is quite configurable, allowing you to produce all
- kinds of different calendars.
-\end{tikzlibrary}
-
-
-\subsection{Calendar Command}
-
-The core command for creating calendars in \tikzname\ is the |\calendar|
-command. It is available only inside |{tikzpicture}| environments (similar to,
-say, the |\draw| command).
-
-\begin{command}{\calendar \meta{calendar specification}|;|}
- The syntax for this command is similar to commands like |\node| or
- |\matrix|. However, it has its complete own parser and only those commands
- described in the following will be recognized, nothing else. Note,
- furthermore, that a \meta{calendar specification} is not a path
- specification, indeed, no path is created for the calendar.
-
-
- \medskip
- \textbf{The specification syntax.}
- The \meta{calendar specification} must be a sequence of elements, each of
- which has one of the following structures:
- %
- \begin{itemize}
- \item |[|\meta{options}|]|
-
- You provide \meta{options} in square brackets as in
- |[red,draw=none]|. These \meta{options} can be any \tikzname\
- option and they apply to the whole calendar. You can provide this
- element multiple times, the effect accumulates.
- \item |(|\meta{name}|)|
-
- This has the same effect as saying |[name=|\meta{name}|]|. The
- effect of providing a \meta{name} is explained later. Note already
- that \emph{a calendar is not a node} and the \meta{name} is
- \emph{not the name of a node}.
- \item |at (|\meta{coordinate}|)|
-
- This has the same effect as saying |[at=(|\meta{coordinate}|)]|.
- \item |if (|\meta{date condition}|)| \meta{options or commands}\opt{|else|\meta{else options or commands}}
-
- The effect of such an |if| is explained later.
- \end{itemize}
-
- At the beginning of every calendar, the following style is used:
- %
- \begin{stylekey}{/tikz/every calendar (initially \normalfont empty)}
- This style is used with every calendar.
- \end{stylekey}
-
-
- \medskip
- \textbf{The date range.}
- The overall effect of the |\calendar| command is to execute code for each
- day of a range of dates. This range of dates is set using the following
- option:
- %
- \begin{key}{/tikz/dates=\meta{start date}| to |\meta{end date}}
- This option specifies the date range. Both the start and end date are
- specified and described on page~\pageref{calendar-date-format}. In
- short: You can provide ISO-format type dates like |2006-01-02|, you can
- replace the day of month by |last| to refer to the last day of a month
- (so |2006-02-last| is the same as |2006-02-28|), and you can add a plus
- sign followed by a number to specify an offset (so |2006-01-01+-1| is
- the same as |2005-12-31|).
- \end{key}
- %
- It will be useful to fix two pieces of terminology for the following
- descriptions: The |\calendar| command iterates over the dates in the range.
- The \emph{current date} refers to the current date the command is
- processing as it iterates over the dates. For each current date code is
- executed, which will be called the \emph{current date code}. The current
- date code consists of different parts, to be detailed later.
-
- The central part of the current date code is the execution of the code
- |\tikzdaycode|. By default, this code simply produces a node whose text is
- set to the day of month. This means that unless further action is taken,
- all days of a calendar will be put on top of each other! To avoid this, you
- must modify the current date code to shift days around appropriately.
- Predefined arrangements like |day list downward| or |week list| do this for
- you, but you can define arrangements yourself. Since defining an
- arrangement is a bit tricky, it is explained only later on. For the time
- being, let us use a predefined arrangement to produce our first calendar:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list];
-\end{codeexample}
-
-
- \medskip
- \textbf{Changing the spacing.}
- In the above calendar, the spacing between the days is determined by
- numerous options. Most arrangements do not use all of these options, but
- only those that apply naturally.
- %
- \begin{key}{/tikz/day xshift=\meta{dimension} (initially 3.5ex)}
- Specifies the horizontal shift between days. This is not the gap
- between days, but the shift between the anchors of their nodes.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,day xshift=3ex];
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/day yshift=\meta{dimension} (initially 3ex)}
- Specifies the vertical shift between days. Again, this is the shift
- between the anchors of their nodes.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,day yshift=2ex];
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/month xshift=\meta{dimension}}
- Specifies an additional horizontal shift between different months.
- \end{key}
- %
- \begin{key}{/tikz/month yshift=\meta{dimension}}
- Specifies an additional vertical shift between different months.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz \calendar[dates=2000-01-01 to 2000-02-last,week list,
- month yshift=0pt];
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz \calendar[dates=2000-01-01 to 2000-02-last,week list,
- month yshift=1cm];
-\end{codeexample}
- \end{key}
-
-
- \medskip
- \textbf{Changing the position of the calendar.}
- The calendar is placed in such a way that, normally, the anchor of the
- first day label is at the origin. This can be changed by using the |at|
- option. When you say |at={(1,1)}|, this anchor of the first day will lie at
- coordinate $(1,1)$.
-
- In general, arrangements will not always place the anchor of the first day
- at the origin. Sometimes, additional spacing rules get in the way. There
- are different ways of addressing this problem: First, you can just ignore
- it. Since calendars are often placed in their own |{tikzpicture}| and since
- their size if computed automatically, the exact position of the origin
- often does not matter at all. Second, you can put the calendar inside a
- node as in |...node {\tikz \calendar...}|. This allows you to position the
- node in the normal ways using the node's anchors. Third, you can be very
- clever and use a single-cell matrix. The advantage is that a matrix allows
- you to provide any anchor of any node inside the matrix as an anchor for
- the whole matrix. For example, the following calendar is placed in such a
- way the center of 2000-01-20 lies on the position $(2,2)$:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \matrix [anchor=cal-2000-01-20.center] at (2,2)
- { \calendar(cal)[dates=2000-01-01 to 2000-01-31,week list]; \\};
-\end{tikzpicture}
-\end{codeexample}
- %
- Unfortunately, the matrix-base positions, which is the cleanest way, isn't
- as portable as the other approaches (it currently does not work with the
- \textsc{svg} backend for instance).
-
-
- \medskip
- \textbf{Changing the appearance of days.}
- As mentioned before, each day in the above calendar is produced by an
- execution of the |\tikzdaycode|. Each time this code is executed, the
- coordinate system will have been set up appropriately to place the day of
- the month correctly. You can change both the code and its appearance using
- the following options.
- %
- \begin{key}{/tikz/day code=\meta{code} (initially \normalfont see below)}
- This option allows you to change the code that is executed for each
- day. The default is to create a node with an appropriate name, but you
- can change this:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
- day code={\fill[blue] (0,0) circle (2pt);}];
-\end{codeexample}
- %
- The default code is the following:
- %
-\begin{codeexample}[code only]
-\node[name=\pgfcalendarsuggestedname,every day]{\tikzdaytext};
-\end{codeexample}
- %
- The first part causes the day nodes to be accessible via the following
- names: If \meta{name} is the name given to the calendar via a |name=|
- option or via the specification element |(|\meta{name}|)|, then
- |\pgfcalendarsuggestedname| will expand to \meta{name}|-|\meta{date},
- where \meta{date} is the date of the day that is currently being
- processed in ISO format.
-
- For example, if January 1, 2006 is being processed and the calendar has
- been named |mycal|, then the node containing the |1| for this date will
- be names |mycal-2006-01-01|. You can later reference this node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\begin{tikzpicture}
- \calendar (mycal) [dates=2000-01-01 to 2000-01-31,week list];
-
- \draw[red] (mycal-2000-01-20) circle (4pt);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/day text=\meta{text}}
- This option changes the setting of the |\tikzdaytext|. By default, this
- macro simply yields the current day of month, but you can change it
- arbitrarily. Here is a silly example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
- day text=x];
-\end{codeexample}
- %
- More useful examples are based on using the |\%| command. This command
- is redefined inside a |\pgfcalendar| to mean the same as
- |\pgfcalendarshorthand|. (The original meaning of |\%| is lost inside
- the calendar, you need to save if before the calendar if you really
- need it.)
-
- The |\%| inserts the current day/month/year/day of week in a certain
- format into the text. The first letter following the |\%| selects the
- type (permissible values are |d|, |m|, |y|, |w|), the second letter
- specifies how the value should be displayed (|-| means numerically, |=|
- means numerically with leading space, |0| means numerically with
- leading zeros, |t| means textual, and |.| means textual, abbreviated).
- For example |\%d0| gives the day with a leading zero (for more details
- see the description of |\pgfcalendarshorthand| on
- page~\pageref{pgfcalendarshorthand}).
-
- Let us redefine the |day text| so that it yields the day with a leading
- zero:
- %
-\begin{codeexample}[leave comments,preamble={\usetikzlibrary{calendar}}]
-\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
- day text=\%d0];
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/every day (initially anchor=base east)}
- This style is executed by the default node code for each day. The
- |every day| style is useful for changing the way days look. For
- example, let us make all days red:
- %
-\begin{codeexample}[leave comments,preamble={\usetikzlibrary{calendar}}]
-\tikz[every day/.style=red]
- \calendar[dates=2000-01-01 to 2000-01-31,week list];
-\end{codeexample}
- \end{key}
-
-
- \medskip
- \textbf{Changing the appearance of month and year labels.}
- In addition to the days of a calendar, labels for the months and even years
- (for really long calendars) can be added. These labels are only added once
- per month or year and this is not done by default. Rather, special styles
- starting with |month label| place these labels and make them visible:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz \calendar[dates=2000-01-01 to 2000-02-last,week list,
- month label above centered];
-\end{codeexample}
-
- The following options change the appearance of the month and year label:
- %
- \begin{key}{/tikz/month code=\meta{code} (initially \normalfont see below)}
- This option allows you to specify what the macro |\tikzmonthcode|
- should expand to.
-
- By default, the |\tikzmonthcode| it is set to
- %
-\begin{codeexample}[code only]
-\node[every month]{\tikzmonthtext};
-\end{codeexample}
- %
- Note that this node is not named by default.
- \end{key}
-
- \begin{key}{/tikz/month text=\meta{text}}
- This option allows you to change the macro |\tikzmonthtext|. By
- default, the month text is a long textual presentation of the current
- month being typeset.
- %
-\begin{codeexample}[leave comments,preamble={\usetikzlibrary{calendar}}]
-\tikz \calendar[dates=2000-01-01 to 2000-01-31,week list,
- month label above centered,
- month text=\textcolor{red}{\%mt} \%y-];
-\end{codeexample}
- \end{key}
-
- \begin{stylekey}{/tikz/every month (initially \normalfont empty)}
- This style can be used to change the appearance of month labels.
- \end{stylekey}
-
- \begin{key}{/tikz/year code=\meta{code}}
- Works like |month code|, only for years.
- \end{key}
-
- \begin{key}{/tikz/year text=\meta{text}}
- Works like |month text|, only for years.
- \end{key}
-
-
- \begin{key}{/tikz/every year}
- Works like |every month|, only for years.
- \end{key}
-
-
- \medskip
- \textbf{Date ifs.}
- Much of the power of the |\calendar| command comes from the use of
- conditionals. There are two equivalent way of specifying such a
- conditional. First, you can add the text
- |if (|\meta{conditions}|) |\meta{code or options} to your \meta{calendar
- specification}, possibly followed by |else|\meta{else code or options}. You
- can have multiple such conditionals (but you cannot nest them in this
- simple manner). The second way is to use the following option:
- %
- \begin{key}{/tikz/if=|(|\meta{conditions}|)|\meta{code or options}\opt{|else|\meta{else code or options}}}
- This option has the same effect as giving a corresponding if in the
- \meta{calendar specification}. The option is mostly useful for use in
- the |every calendar| style, where you cannot provide if conditionals
- otherwise.
- \end{key}
- %
- Now, regardless of how you specify a conditional, it has the following
- effect (individually and independently for each date in the calendar):
- %
- \begin{enumerate}
- \item It is checked whether the current date is one of the
- possibilities listed in \meta{conditions}. An example of such a
- condition is |Sunday|. Thus, when you write
- |if (Saturday,Sunday) {foo}|, then |foo| will be executed for every
- day in the calendar that is a Saturday \emph{or} a Sunday.
-
- The command |\ifdate| and, thereby, |\pgfcalendarifdate| are used
- to evaluate the \meta{conditions}, see
- page~\pageref{pgfcalendarifdate} for a complete list of possible
- tests. The most useful tests are: Tests like |Monday| and so on,
- |workday| for the days Monday to Friday, |weekend| for Saturday and
- Sunday, |equals| for testing whether the current date equals a
- given date, |at least| and |at least| for comparing the current
- date with a given date.
- \item If the date passes the check, the \meta{code or options} is
- evaluated in a manner to be described in a moment; if the date
- fails, the \meta{else code or options} is evaluated, if present.
-
- The \meta{code or options} can either be some code. This is
- indicated by surrounding the code with curly braces. It can also be
- a list of \tikzname\ options. This is indicated by surrounding the
- options with square brackets. For example in the date test
- |if (Sunday) {\draw...} else {\fill...}| there are two pieces of
- code involved. By comparison, |if (Sunday) [red] else [green]|
- involves two options.
-
- If \meta{code or options} is code, it is simply executed (for the
- current day). If it is a list of options, these options are passed
- to a scope surrounding the current date.
- \end{enumerate}
- %
- Let us now have a look at some examples. First, we use a conditional to
- make all Sundays red.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar
- [dates=2000-01-01 to 2000-01-31,week list]
- if (Sunday) [red];
-\end{codeexample}
- %
- Next, let us do something on a specific date:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar
- [dates=2000-01-01 to 2000-01-31,week list]
- if (Sunday) [red]
- if (equals=2000-01-20) {\draw (0,0) circle (8pt);};
-\end{codeexample}
- %
- You might wonder why the circle seems to be ``off'' the date. Actually, it
- is centered on the date, it is just that the date label uses the
- |base east| anchor, which shifts the label up and right. To overcome this
- problem we can change the anchor:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz [every day/.style={anchor=mid}]
- \calendar
- [dates=2000-01-01 to 2000-01-31,week list]
- if (Sunday) [red]
- if (equals=2000-01-20) {\draw (0,0) circle (8pt);};
-\end{codeexample}
- %
- However, the single day dates are now no longer aligned correctly. For
- this, we can change the day text to |\%d=|, which adds a space at the
- beginning of single day text.
-
- In the following, more technical information is covered. Most readers may
- wish to skip it.
-
- \medskip
- \textbf{The current date code.}
- As mentioned earlier, for each date in the calendar the current date code
- is executed. It is the job of this code to shift around date nodes, to
- render the date nodes, to draw the month labels and to do all other stuff
- that is necessary to draw a calendar.
-
- The current date code consists of the following parts, in this order:
- %
- \begin{enumerate}
- \item The before-scope code.
- \item A scope is opened.
- \item The at-begin-scope code.
- \item All date-ifs from the \meta{calendar specification} are executed.
- \item The at-end-scope code.
- \item The scope is closed.
- \item The after-scope code.
- \end{enumerate}
- %
- All of the codes mentioned above can be changed using appropriate options,
- see below. In case you wonder why so many are needed, the reason is that
- the current date code as a whole is not surrounded by a scope or \TeX\
- group. This means that code executed in the before-scope code and in the
- after-scope code has an effect on all following days. For example, if the
- after-scope code modifies the transformation matrix by shifting everything
- downward, all following days will be shifted downward. If each day does
- this, you get a list of days, one below the other.
-
- However, you do not always want code to have an effect on everything that
- follows. For instance, if a day has the date-if |if (Sunday) [red]|, we
- only want this Sunday to red, not all following days also. Similarly,
- sometimes it is easier to compute the position of a day relative to a fixed
- origin and we do not want any modifications of the transformation matrix to
- have an effect outside the scope.
-
- By cleverly adjusting the different codes, all sorts of different day
- arrangements are possible.
-
- \begin{key}{/tikz/execute before day scope=\meta{code}}
- The \meta{code} is executed before everything else for each date.
- Multiple calls of this option have an accumulative effect. Thus, if you
- use this option twice, the code from the first use is used first for
- each day, followed by the code given the second time.
- \end{key}
- %
- \begin{key}{/tikz/execute at begin day scope=\meta{code}}
- This code is execute before everything else inside the scope of the
- current date. Again, the effect is accumulative.
- \end{key}
- %
- \begin{key}{/tikz/execute at end day scope=\meta{code}}
- This code is executed just before the day scope is closed. The effect
- is also accumulative, however, in reverse order. This is useful to
- pair, say, |\scope| and |\endscope| commands in at-begin- and
- at-end-code.
- \end{key}
- %
- \begin{key}{/tikz/execute after day scope=\meta{code}}
- This is executed at the very end of the current date, outside the
- scope. The accumulation is also in reverse.
- \end{key}
-\end{command}
-
-In the rest of the following subsections we have a look at how the different
-scope codes can be used to create different calendar arrangements.
-
-
-\subsubsection{Creating a Simple List of Days}
-
-We start with a list of the days of the calendar, one day below the other. For
-this, we simply shift the coordinate system downward at the end of the code for
-each day. This shift must be \emph{outside} the day scope as we want day shifts
-to accumulate. Thus, we use the following code:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-01 to 2000-01-08,
- execute after day scope=
- {\pgftransformyshift{-1em}}];
-\end{codeexample}
-%
-Clearly, we can use this approach to create day lists going up, down, right,
-left, or even diagonally.
-
-
-\subsubsection{Adding a Month Label}
-
-We now want to add a month label to the left of the beginning of each month.
-The idea is to do two things:
-%
-\begin{enumerate}
- \item We add code that is executed only on the first of each month.
- \item The code is executed before the actual day is rendered. This ensures
- that options applying to the days do not affect the month rendering.
-\end{enumerate}
-%
-We have two options where we should add the month code: Either we add it at the
-beginning of the day scope or before. Either will work fine, but it might be
-safer to put the code inside the scope to ensure that settings to not
-inadvertently ``leak outside''.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar
- [dates=2000-01-01 to 2000-01-08,
- execute after day scope={\pgftransformyshift{-1em}},
- execute at begin day scope=
- {\ifdate{day of month=1}{\tikzmonthcode}{}},
- every month/.append style={anchor=base east,xshift=-2em}];
-\end{codeexample}
-
-In the above code we used the |\ifdate|\marg{condition}\marg{then
-code}\marg{else code} command, which is described on page~\pageref{ifdate} in
-detail and which has much the same effect as
-|if (|\meta{condition}|)|\marg{then code}| else |\marg{else code}, but works in
-normal code.
-
-
-\subsubsection{Creating a Week List Arrangement}
-
-Let us now address a more complicated arrangement: A week list. In this
-arrangement there is line for each week. The horizontal placement of the days
-is thus that all Mondays lie below each other, likewise for all Tuesdays, and
-so on.
-
-In order to typeset this arrangement, we can use the following approach: The
-origin of the coordinate system rests at the anchor for the Monday of each
-week. That means that at the end of each week the origin is moved downward one
-line. On all other days, the origin at the end of the day code is the same as
-at the beginning. To position each day correctly, we use code inside and at the
-beginning of the day scope to horizontally shift the day according to its day
-of week.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar
- [dates=2000-01-01 to 2000-01-20,
- % each day is shifted right according to the day of week
- execute at begin day scope=
- {\pgftransformxshift{\pgfcalendarcurrentweekday em}},
- % after each week, the origin is shifted downward:
- execute after day scope=
- {\ifdate{Sunday}{\pgftransformyshift{-1em}}{}}];
-\end{codeexample}
-
-
-\subsubsection{Creating a Month List Arrangement}
-
-For another example, let us create an arrangement that contains one line for
-each month. This is easy enough to do as for weeks, unless we add the following
-requirement: Again, we want all days in a column to have the same day of week.
-Since months start on different days of week, this means that each row has to
-have an individual offset.
-
-One possible way is to use the following approach: After each month (or at the
-beginning of each month) we advance the vertical position of the offset by one
-line. For horizontal placement, inside the day scope we locally shift the day
-by its day of month. Furthermore, we must additionally shift the day to ensure
-that the first day of the month lies on the correct day of week column. For
-this, we remember this day of week the first time we see it.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\newcount\mycount
-\tikz
- \calendar
- [dates=2000-01-01 to 2000-02-last,
- execute before day scope=
- {
- \ifdate{day of month=1} {
- % Remember the weekday of first day of month
- \mycount=\pgfcalendarcurrentweekday
- % Shift downward
- \pgftransformyshift{-1em}
- }{}
- },
- execute at begin day scope=
- {
- % each day is shifted right according to the day of month
- \pgftransformxshift{\pgfcalendarcurrentday em}
- % and additionally according to the weekday of the first
- \pgftransformxshift{\the\mycount em}
- }];
-\end{codeexample}
-
-
-\subsection{Arrangements}
-
-An \emph{arrangement} specifies how the days of calendar are arranged on the
-page. The |calendar| library defines a number of predefined arrangements.
-
-We start with arrangements in which the days are listed in a long line.
-
-\begin{stylekey}{/tikz/day list downward}
- This style causes the days of a month to be typeset one below the other.
- The shift between days is given by |day yshift|. Between month an
- additional shift of |month yshift| is added.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-28 to 2000-02-03,
- day list downward,month yshift=1em];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/day list upward}
- Works as above, only the list grows upward instead of downward.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-28 to 2000-02-03,
- day list upward,month yshift=1em];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/day list right}
- This style also works as before, but the list of days grows to the right.
- Instead of |day yshift| and |month yshift|, the values of |day xshift| and
- |month xshift| are used.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-28 to 2000-02-03,
- day list right,month xshift=1em];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/day list left}
- As above, but the list grows left.
-\end{stylekey}
-
-The next arrangement lists days by the week.
-
-\begin{stylekey}{/tikz/week list}
- This style creates one row for each week in the range. The value of
- |day xshift| is used for the distance between days in each week row, the
- value of |day yshift| is used for the distance between rows. In both cases,
- ``distance'' refers to the distance between the anchors of the nodes of the
- days (or, more generally, the distance between the origins of the little
- pictures created for each day).
-
- The days inside each week are shifted such that Monday is always at the
- first position (to change this, you need to copy and then modify the code
- appropriately). If the date range does not start on a Monday, the first
- line will not start in the first column, but rather in the column
- appropriate for the first date in the range.
-
- At the beginning of each month (except for the first month in the range) an
- additional vertical space of |month yshift| is added. If this is set to
- |0pt| you get a continuous list of days.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-01 to 2000-02-last,week list];
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-01 to 2000-02-last,week list,
- month yshift=0pt];
-\end{codeexample}
- %
-\end{stylekey}
-
-The following arrangement gives a very compact view of a whole year.
-%
-\begin{stylekey}{/tikz/month list}
- In this arrangement there is a row for each month. As for the |week list|,
- the |day xshift| is used for the horizontal distance. For the vertical
- shift, |month yshift| is used.
-
- In each row, all days of the month are listed alongside each other.
- However, it is once more ensured that days in each column lie on the same
- day of week. Thus, the very first column contains only Mondays. If a month
- does not start with a Monday, its days are shifted to the right such that
- the days lie on the correct columns.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\sffamily\scriptsize
-\tikz
- \calendar [dates=2000-01-01 to 2000-12-31,
- month list,month label left,month yshift=1.25em]
- if (Sunday) [black!50];
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsection{Month Labels}
-
-For many calendars you may wish to add a label to each month. We have already
-covered how month nodes are created and rendered in the description of the
-|\calendar| command: use |month text|, |every month|, and also |month code| (if
-necessary) to change the appearance of the month labels.
-
-What we have not yet covered is where these labels are placed. By default, they
-are not placed at all as there is no good ``default position'' for them.
-Instead, you can use one of the following options to specify a position for the
-labels:
-%
-\begin{stylekey}{/tikz/month label left}
- Places the month label to the left of the first day of the month. (For
- |week list| and |month list| where a month does not start on a Monday, the
- position is chosen ``as if'' the month had started on a Monday -- which is
- usually exactly what you want.)
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-28 to 2000-02-03,
- day list downward,month yshift=1em,
- month label left];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/month label left vertical}
- This style works like the above style, only the label is rotated
- counterclockwise by 90 degrees.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-28 to 2000-02-03,
- day list downward,month yshift=1em,
- month label left vertical];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/month label right}
- This style places the month label to the right of the row in which the
- first day of the month lies. This means that for a day list the label is to
- the right of the first day, for a week list it is to the right of the first
- week, and for a month list it is to the right of the whole month.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-28 to 2000-02-03,
- day list downward,month yshift=1em,
- month label right];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/month label right vertical}
- Works as above, only the label is rotated clockwise by 90 degrees.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-28 to 2000-02-03,
- day list downward,month yshift=1em,
- month label right vertical];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/month label above left}
- This style places the month label above of the row of the first day,
- flushed left to the leftmost column. The amount by which the label is
- raised is fixed to |1.25em|; use the |yshift| option with the month node to
- modify this.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-28 to 2000-02-03,
- day list right,month xshift=1em,
- month label above left];
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-20 to 2000-02-10,
- week list,month label above left];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/month label above centered}
- Works as above, only the label is centered above the row containing the
- first day.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-02-01 to 2000-02-last,
- day list right,month label above centered];
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-20 to 2000-02-10,
- week list,month label above centered];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/month label above right}
- Works as above, but flushed right
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-01-20 to 2000-02-10,
- week list,month label above right];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/month label below left}
- Works like |month label above left|, only the label is placed below the
- row. This placement is not really useful with the |week list| arrangement,
- but rather with the |day list right| or |month list| arrangement.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-02-01 to 2000-02-last,
- day list right,month label below left];
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/month label below centered}
- Works like |month label above centered|, only below.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\tikz
- \calendar [dates=2000-02-01 to 2000-02-last,
- day list right,month label below centered];
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsection{Examples}
-
-In the following, some example calendars are shown that come either from real
-applications or are just nice to look at.
-
-Let us start with a year-2100-countdown, in which we cross out dates as we
-approach the big celebration. For this, we set the shape to |strike out| for
-these dates.
-%
-\begin{codeexample}[
- leave comments,
- preamble={\usetikzlibrary{calendar,shapes.misc}},
-]
-\begin{tikzpicture}
- \calendar
- [
- dates=2099-12-01 to 2100-01-last,
- week list,inner sep=2pt,month label above centered,
- month text=\%mt \%y0
- ]
- if (at most=2099-12-29) [nodes={strike out,draw}]
- if (weekend) [black!50,nodes={draw=none}]
- ;
-\end{tikzpicture}
-\end{codeexample}
-
-The next calendar shows a deadline, which is 10 days in the future from the
-current date. The last three days before the deadline are in red, because we
-really should be done by then. All days on which we can no longer work on the
-project are crossed out.
-%
-\begin{codeexample}[
- leave comments,
- preamble={\usetikzlibrary{calendar,shapes.misc}},
-]
-\begin{tikzpicture}
- \calendar
- [
- dates=\year-\month-\day+-25 to \year-\month-\day+25,
- week list,inner sep=2pt,month label above centered,
- month text=\textit{\%mt \%y0}
- ]
- if (at least=\year-\month-\day) {}
- else [nodes={strike out,draw}]
- if (at most=\year-\month-\day+7)
- [green!50!black]
- if (between=\year-\month-\day+8 and \year-\month-\day+10)
- [red]
- if (Sunday)
- [gray,nodes={draw=none}]
- ;
-\end{tikzpicture}
-\end{codeexample}
-
-The following example is a futuristic calendar that is all about circles:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calendar}}]
-\sffamily
-
-\colorlet{winter}{blue}
-\colorlet{spring}{green!60!black}
-\colorlet{summer}{orange}
-\colorlet{fall}{red}
-
-% A counter, since TikZ is not clever enough (yet) to handle
-% arbitrary angle systems.
-\newcount\mycount
-
-\begin{tikzpicture}
- [transform shape,
- every day/.style={anchor=mid,font=\fontsize{6}{6}\selectfont}]
- \node{\normalsize\the\year};
- \foreach \month/\monthcolor in
- {1/winter,2/winter,3/spring,4/spring,5/spring,6/summer,
- 7/summer,8/summer,9/fall,10/fall,11/fall,12/winter}
- {
- % Compute angle:
- \mycount=\month
- \advance\mycount by -1
- \multiply\mycount by 30
- \advance\mycount by -90
-
- % The actual calendar
- \calendar at (\the\mycount:6.4cm)
- [
- dates=\the\year-\month-01 to \the\year-\month-last,
- ]
- if (day of month=1) {\color{\monthcolor}\tikzmonthcode}
- if (Sunday) [red]
- if (all)
- {
- % Again, compute angle
- \mycount=1
- \advance\mycount by -\pgfcalendarcurrentday
- \multiply\mycount by 11
- \advance\mycount by 90
- \pgftransformshift{\pgfpointpolar{\mycount}{1.4cm}}
- };
- }
-\end{tikzpicture}
-\end{codeexample}
-
-Next, let's us have a whole year in a tight column:
-%
-\begin{codeexample}[leave comments,preamble={\usetikzlibrary{calendar}}]
-\begin{tikzpicture}
- \small\sffamily
- \colorlet{darkgreen}{green!50!black}
- \calendar[dates=\year-01-01 to \year-12-31,week list,
- month label left,month yshift=0pt,
- month text=\textcolor{darkgreen}{\%m0}]
- if (Sunday) [black!50];
-\end{tikzpicture}
-\end{codeexample}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-chains.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-chains.tex
deleted file mode 100644
index e601610e7f..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-chains.tex
+++ /dev/null
@@ -1,499 +0,0 @@
-% 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{Chains}
-\label{section-chains}
-
-\begin{tikzlibrary}{chains}
- This library defines options for creating chains.
-\end{tikzlibrary}
-
-
-\subsection{Overview}
-
-\emph{Chains} are sequences of nodes that are -- typically -- arranged in a row
-or a column and that are -- typically -- connected by edges. More generally,
-they can be used to position nodes of a branching network in a systematic
-manner. For the positioning of nodes in rows and columns you can also use
-matrices, see Section~\ref{section-matrices}, but chains can also be used to
-describe the connections between nodes that have already been connected using,
-say, matrices. Thus, it often makes sense to use matrices for the positioning
-of elements and chains to describe the connections.
-
-
-\subsection{Starting and Continuing a Chain}
-
-Typically, you construct one chain at a time, but it is permissible to
-construct multiple chains simultaneously. In this case, the chains must be
-named differently and you must specify for each node which chain it belongs to.
-
-The first step toward creating a chain is to use the |start chain| option.
-
-\begin{key}{/tikz/start chain=\opt{\meta{chain name}}\opt{\meta{direction}}}
- This key should, but need not, be given as an option to a scope enclosing
- all nodes of the chain. Typically, this will be a |scope| or the whole
- |tikzpicture|, but it might just be a path on which all nodes of the chain
- are found. If no \meta{chain name} is given, the default value |chain| will
- be used instead.
-
- The key starts a chain named \meta{chain name} and makes it \emph{active},
- which means that it is currently being constructed. The |start chain| can
- be issued only once to activate a chain, inside a scope in which a chain is
- active you cannot use this option once more (for the same chain name). The
- chain stops being active at the end of the scope in which the |start chain|
- command was given.
-
- Although chains are only locally active (that is, active inside the scope
- the |start chain| command was issued), the information concerning the
- chains is stored globally and it is possible to \emph{continue} a chain
- after a scope has ended. For this, the |continue chain| option can be used,
- which allows you to reactivate an existing chain in another scope.
-
- The \meta{direction} is used to determine the placement rule for nodes on
- the chain. If it is omitted, the current value of the following key is
- used:
- %
- \begin{key}{/tikz/chain default direction=\meta{direction} (initially going right)}
- This \meta{direction} is used in a |chain| option, if no other
- \meta{direction} is specified.
- \end{key}
-
- The \meta{direction} can have two different forms:
- \declare{|going |\meta{options}} or \declare{|placed |\meta{options}}. The
- effect of these rules will be explained in the description of the
- |on chain| option. Right now, just remember that the \meta{direction} you
- provide with the |chain| option applies to the whole chain.
-
- Other than this, this key has no further effect. In particular, to place
- nodes on the chain, you must use the |on chain| option, described next.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{chains}}]
-\begin{tikzpicture}[start chain]
- % The chain is called just "chain"
- \node [on chain] {A};
- \node [on chain] {B};
- \node [on chain] {C};
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{chains,scopes}}]
-\begin{tikzpicture}
- % Same as above, using the scope shorthand
- { [start chain]
- \node [on chain] {A};
- \node [on chain] {B};
- \node [on chain] {C};
- }
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{chains}}]
-\begin{tikzpicture}[start chain=1 going right,
- start chain=2 going below,
- node distance=5mm,
- every node/.style=draw]
- \node [on chain=1] {A};
- \node [on chain=1] {B};
- \node [on chain=1] {C};
-
- \node [on chain=2] at (0.5,-.5) {0};
- \node [on chain=2] {1};
- \node [on chain=2] {2};
-
- \node [on chain=1] {D};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/continue chain=\opt{\meta{chain name}}\opt{\meta{direction}}}
- This option allows you to (re)activate an existing chain and to possibly
- change the default direction. If the |chain name| is missing, the name of
- the innermost activated chain is used. If no chain is activated, |chain| is
- used.
-
- Let us have a look at the two different applications of this option. The
- first is to change the direction of a chain as it is being constructed. For
- this, just give this option somewhere inside the scope of the chain.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{chains}}]
-\begin{tikzpicture}[start chain=going right,node distance=5mm]
- \node [draw,on chain] {Hello};
- \node [draw,on chain] {World};
- \node [draw,continue chain=going below,on chain] {,};
- \node [draw,on chain] {this};
- \node [draw,on chain] {is};
-\end{tikzpicture}
-\end{codeexample}
-
- The second application is to reactivate a chain after it ``has already been
- closed down''.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{chains,scopes}}]
-\begin{tikzpicture}[node distance=5mm,
- every node/.style=draw]
- { [start chain=1]
- \node [on chain] {A};
- \node [on chain] {B};
- \node [on chain] {C};
- }
-
- { [start chain=2 going below]
- \node [on chain=2] at (0.5,-.5) {0};
- \node [on chain=2] {1};
- \node [on chain=2] {2};
- }
-
- { [continue chain=1]
- \node [on chain] {D};
- }
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Nodes on a Chain}
-
-\begin{key}{/tikz/on chain=\opt{\meta{chain name}}\opt{\meta{direction}}}
- This key should be given as an option to a node. When the option is used,
- the \meta{chain name} must be the name of a chain that has been started
- using the |start chain| option. If \meta{chain name} is the empty string,
- the current value of the innermost activated chain is used. If this option
- is used several times for a node, only the last invocation ``wins''. (To
- place a node on several chains, use the |\chainin| command repeatedly.)
-
- The \meta{direction} part is optional. If present, it sets the direction
- used for this node, otherwise the \meta{direction} that was given to the
- original |start chain| option is used (or of the last |continue chain|
- option, which allows you to change this default).
-
- The effects of this option are the following:
- %
- \begin{enumerate}
- \item An internal counter (there is one local counter for each chain)
- is increased. This counter reflects the current number of the node
- in the chain, where the first node is node 1, the second is node 2,
- and so on.
-
- The value of this internal counter is globally stored in the macro
- \declare{|\tikzchaincount|}.
- \item If the node does not yet have a name, (having been given using
- the |name| option or the name-syntax), the name of the node is set
- to \meta{chain name}|-|\meta{value of the internal chain counter}.
- For instance, if the chain is called |nums|, the first node would
- be named |nums-1|, the second |nums-2|, and so on. For the default
- chain name |chain|, the first node is named |chain-1|, the second
- |chain-2|, and so on.
- \item Independently of whether the name has been provided automatically
- or via the |name| option, the name of the node is globally stored
- in the macro \declare{|\tikzchaincurrent|}.
- \item Except for the first node, the macro
- \declare{|\tikzchainprevious|} is now globally set to the name of
- the node of the previous node on the chain. For the first node of
- the chain, this macro is globally set to the empty string.
- \item Except possibly for the first node of the chain, the placement
- rule is now executed. The placement rule is just a \tikzname\
- option that is applied automatically to each node on the chain.
- Depending on the form of the \meta{direction} parameter (either the
- locally given one or the one given to the |start chain| option),
- different things happen.
-
- First, it makes a difference whether the \meta{direction} starts
- with |going| or with |placed|. The difference is that in the first
- case, the placement rule is not applied to the first node of the
- chain, while in the second case the placement rule is applied also
- to this first node. The idea is that a |going|-direction indicates
- that we are ``going somewhere relative to the previous node''
- whereas a |placed| indicates that we are ``placing nodes according
- to their number''.
-
- Independently of which form is used, the \meta{text} inside
- \meta{direction} that follows |going| or |placed| (separated by a
- compulsory space) can have two different effects:
- %
- \begin{enumerate}
- \item If it contains an equal sign, then this \meta{text} is
- used as the placement rule, that is, it is simply executed.
- \item If it does not contain an equal sign, then
- \meta{text}|=of \tikzchainprevious| is used as the
- placement rule.
- \end{enumerate}
-
- Note that in the first case, inside the \meta{text} you have access
- to |\tikzchainprevious| and |\tikzchaincount| for doing your
- positioning calculations.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{chains}}]
-\begin{tikzpicture}[start chain=circle placed {at=(\tikzchaincount*30:1.5)}]
- \foreach \i in {1,...,10}
- \node [on chain] {\i};
-
- \draw (circle-1) -- (circle-10);
-\end{tikzpicture}
-\end{codeexample}
- \item The following style is executed:
- %
- \begin{stylekey}{/tikz/every on chain}
- This key is executed for every node on a chain, including the
- first one.
- \end{stylekey}
- \end{enumerate}
-
- Recall that the standard placement rule has a form like
- |right=of (\tikzchainprevious)|. This means that each new node is placed to
- the right of the previous one, spaced by the current value of
- |node distance|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{chains}}]
-\begin{tikzpicture}[start chain,node distance=5mm]
- \node [draw,on chain] {};
- \node [draw,on chain] {Hallo};
- \node [draw,on chain] {Welt};
-\end{tikzpicture}
-\end{codeexample}
-
- The optional \meta{direction} allows us to temporarily change the direction
- in the middle of a chain:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{chains}}]
-\begin{tikzpicture}[start chain,node distance=5mm]
- \node [draw,on chain] {Hello};
- \node [draw,on chain] {World};
- \node [draw,on chain=going below] {,};
- \node [draw,on chain] {this};
- \node [draw,on chain] {is};
-\end{tikzpicture}
-\end{codeexample}
-
- You can also use more complicated computations in the \meta{direction}:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{chains}}]
-\begin{tikzpicture}[start chain=going {at=(\tikzchainprevious),shift=(30:1)}]
- \draw [help lines] (0,0) grid (3,2);
- \node [draw,on chain] {1};
- \node [draw,on chain] {Hello};
- \node [draw,on chain] {World};
- \node [draw,on chain] {.};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-For each chain, two special ``pseudo nodes'' are created.
-
-\begin{predefinednode}{\meta{chain name}-begin}
- This node is the same as the first node on the chain. It is only defined
- after a first node has been defined.
-\end{predefinednode}
-
-\begin{predefinednode}{\meta{chain name}-end}
- This node is the same as the (currently) last node on the chain. As the
- chain is extended, this node changes.
-\end{predefinednode}
-
-The |on chain| option can also be used, in conjunction with |late options|, to
-add an already existing node to a chain. The following command, which is only
-defined inside scopes where a |start chain| option is present, simplifies this
-process.
-
-\begin{command}{\chainin |(|\meta{existing name}|)| \opt{\oarg{options}}}
- This command makes it easy to add a node to chain that has already been
- constructed. This node may even be part of a another chain.
-
- When you say |\chainin (some node);|, the node |some node| must already
- exist. It will then be made part of the current chain. This does not mean
- that the node can be changed (it is already constructed, after all), but
- the |join| option can be used to join |some node| to the previous last node
- on the chain and subsequent nodes will be placed relative to |some node|.
-
- It is permissible to give the |on chain| option inside the \meta{options}
- in order to specify on which chain the node should be put.
-
- This command is just a shortcut for
- %
- \begin{quote}
- |\path (|\meta{existing name}|) [late options={on chain,every chain in,|\meta{options}|}]|
- \end{quote}
- %
- In particular, it is possible to continue to path after a |\chainin|
- command, though that does not seem very useful.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{chains}}]
-\begin{tikzpicture}[node distance=5mm,
- every node/.style=draw,every join/.style=->]
- \draw [help lines] (0,0) grid (3,2);
-
- \node[red] (existing) at (0,2) {existing};
-
- \begin{scope}[start chain]
- \node [draw,on chain,join] {Hello};
- \node [draw,on chain,join] {World};
- \chainin (existing) [join];
- \node [draw,on chain,join] {this};
- \node [draw,on chain,join] {is};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
- Here is an example where nodes are positioned using a matrix and then
- connected using a chain
- %
-{\catcode`\|=12
-\begin{codeexample}[preamble={\usetikzlibrary{chains,matrix,scopes,shapes.geometric}}]
-\begin{tikzpicture}[every node/.style=draw]
- \matrix [matrix of nodes,column sep=5mm,row sep=5mm]
- {
- |(a)| World & |(b) [circle]| peace \\
- |(c)| be & |(d) [isosceles triangle]| would \\
- |(e) [ellipse]| great & |(f)| ! \\
- };
-
- % (the `scopes' library needs to be loaded to make the following work)
- { [start chain,every on chain/.style={join=by ->}]
- \chainin (a);
- \chainin (b);
- \chainin (d);
- \chainin (c);
- \chainin (e);
- \chainin (f);
- }
-\end{tikzpicture}
-\end{codeexample}
-}
- %
-\end{command}
-
-
-\subsection{Joining Nodes on a Chain}
-
-\begin{key}{/tikz/join=\opt{|with |\meta{with} }\opt{|by |\meta{options}}}
- When this key is given to any node on a chain (except possibly for the
- first node), an |edge| command is added after the node. The |with| part
- specifies which node should be used for the start point of the edge; if the
- |with| part is omitted, the |\tikzchainprevious| is used. This |edge|
- command gets the \meta{options} as parameter and the current node as its
- target. If there is no previous node and no |with| is given, no |edge|
- command gets executed.
- %
- \begin{stylekey}{/tikz/every join}
- This style is executed each time this command is used.
- \end{stylekey}
-
- Note that it makes sense to call this option several times for a node, in
- order to connect it to several nodes. This is especially useful for joining
- in branches, see the next section.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{chains}}]
-\begin{tikzpicture}[start chain,node distance=5mm,
- every join/.style={->,red}]
- \node [draw,on chain,join] {};
- \node [draw,on chain,join] {Hallo};
- \node [draw,on chain,join] {Welt};
- \node [draw,on chain=going below,
- join,join=with chain-1 by {blue,<-}] {foo};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Branches}
-
-A \emph{branch} is a chain that (typically only temporarily) extends an
-existing chain. The idea is the following: Suppose we are constructing a chain
-and at some node |x| there is a fork. In this case, one (or even more) branches
-starts at this fork. For each branch a chain is created, but the first node on
-this chain should be~|x|. For this, it is useful to use |\chainin| on the node
-|x| to make it part of the different branch chains and to name the branch
-chains in some way that reflects the name of the main chain.
-
-The |start branch| option provides a shorthand for doing exactly what was just
-described.
-
-\begin{key}{/tikz/start branch=\meta{branch name}\opt{\meta{direction}}}
- This key is used in the same manner as the |start chain| command, however,
- the effect is slightly different:
- %
- \begin{itemize}
- \item This option may only be used if some chain is already active and
- there is a (last) node on this chain. Let us call this node the
- \meta{fork node}.
- \item The chain is not just called \meta{branch name}, but
- \meta{current chain}|/|\meta{branch name}. For instance, if the
- \meta{fork node} is part of the chain called |trunk| and the
- \meta{branch name} is set to |left|, the complete chain name of the
- branch is |trunk/left|. The \meta{branch name} must be given, there
- is no default value.
- \item The \meta{fork node} is automatically ``chained into'' the branch
- chain as its first node. Thus, for the first node on the branch
- that you provide, the |join| option will cause it to be connected
- to the fork node.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{chains,scopes}}]
-\begin{tikzpicture}[every on chain/.style=join,every join/.style=->,
- node distance=2mm and 1cm]
- { [start chain=trunk]
- \node [on chain] {A};
- \node [on chain] {B};
-
- { [start branch=numbers going below]
- \node [on chain] {1};
- \node [on chain] {2};
- \node [on chain] {3};
- }
- { [start branch=greek going above]
- \node [on chain] {$\alpha$};
- \node [on chain] {$\beta$};
- \node [on chain] {$\gamma$};
- }
-
- \node [on chain,join=with trunk/numbers-end,join=with trunk/greek-end] {C};
- { [start branch=symbols going below]
- \node [on chain] {$\star$};
- \node [on chain] {$\circ$};
- \node [on chain] {$\int$};
- }
- }
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/continue branch=\meta{branch name}\opt{\meta{direction}}}
- This option works like the |continue chain| option, only \meta{current
- chain}|/|\meta{branch name} is used as the chain name, rather than just
- \meta{branch name}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{chains,scopes}}]
-\begin{tikzpicture}[every on chain/.style=join,every join/.style=->,
- node distance=2mm and 1cm]
- { [start chain=trunk]
- \node [on chain] {A};
- \node [on chain] {B};
- { [start branch=numbers going below] } % just a declaration,
- { [start branch=greek going above] } % we will come back later
- \node [on chain] {C};
-
- % Now come the branches...
- { [continue branch=numbers]
- \node [on chain] {1};
- \node [on chain] {2};
- }
- { [continue branch=greek]
- \node [on chain] {$\alpha$};
- \node [on chain] {$\beta$};
- }
- }
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-circuits.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-circuits.tex
deleted file mode 100644
index b46e562880..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-circuits.tex
+++ /dev/null
@@ -1,2236 +0,0 @@
-% Copyright 2019 by Till Tantau and Mark Wibrow
-%
-% 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{Circuit Libraries}
-\label{section-library-circuits}
-
-\emph{Written and documented by Till Tantau, and Mark Wibrow. Inspired
-by the work of Massimo Redaelli.}
-
-
-\subsection{Introduction}
-
-The circuit libraries can be used to draw different kinds of electrical or
-logical circuits. There is not a single library for this, but a whole hierarchy
-of libraries that work in concert. The main design goal was to create a balance
-between ease-of-use and ease-of-extending, while creating high-quality
-graphical representations of circuits.
-%
-\begin{codeexample}[setup code,hidden]
-\tikzset{
- % from `shape` library
- shape example/.style= {color = black!30,
- draw,
- fill = yellow!30,
- line width = .5cm,
- inner xsep = 2.5cm,
- inner ysep = 0.5cm}
-}
-\end{codeexample}
-
-
-\subsubsection{A First Example}
-
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}[circuit ee IEC,x=3cm,y=2cm,semithick,
- every info/.style={font=\footnotesize},
- small circuit symbols,
- set resistor graphic=var resistor IEC graphic,
- set diode graphic=var diode IEC graphic,
- set make contact graphic= var make contact IEC graphic]
- % Let us start with some contacts:
- \foreach \contact/\y in {1/1,2/2,3/3.5,4/4.5,5/5.5}
- {
- \node [contact] (left contact \contact) at (0,\y) {};
- \node [contact] (right contact \contact) at (1,\y) {};
- }
- \draw (right contact 1) -- (right contact 2) -- (right contact 3)
- -- (right contact 4) -- (right contact 5);
-
- \draw (left contact 1) to [diode] ++(down:1)
- to [voltage source={near start,
- direction info={volt=3}},
- resistor={near end,ohm=3}] ++(right:1)
- to (right contact 1);
- \draw (left contact 1) to [resistor={ohm=4}] (right contact 1);
- \draw (left contact 1) to [resistor={ohm=3}] (left contact 2);
- \draw (left contact 2) to [voltage source={near start,
- direction info={<-,volt=8}},
- resistor={ohm=2,near end}] (right contact 2);
- \draw (left contact 2) to [resistor={near start,ohm=1},
- make contact={near end,info'={[red]$S_1$}}]
- (left contact 3);
- \draw (left contact 3) to [current direction'={near start,info=$\iota$},
- resistor={near end,info={$R=4\Omega$}}]
- (right contact 3);
- \draw (left contact 4) to [voltage source={near start,
- direction info={<-,volt=8}},
- resistor={ohm=2,near end}] (right contact 4);
- \draw (left contact 3) to [resistor={ohm=1}] (left contact 4);
- \draw (left contact 4) to [resistor={ohm=3}] (left contact 5);
- \draw (left contact 5) to [resistor={ohm=4}] (right contact 5);
- \draw (left contact 5) to [diode] ++(up:1)
- to [voltage source={near start,
- direction info={volt=3}},
- resistor={near end,ohm=3}] ++(right:1)
- to (right contact 5);
-\end{tikzpicture}
-\end{codeexample}
-
-An important feature of the |circuits| library is that the appearance of a
-circuit can be configured in general ways and that the labels are placed
-automatically by default. Here is the graphic once more, generated from
-\emph{exactly the same source code}, with only the options of the
-|{tikzpicture}| environment replaced by
-|[rotate=-90,circuit ee IEC,x=3.25cm,y=2.25cm]|:
-%
-\begin{tikzpicture}[rotate=-90,circuit ee IEC,x=3cm,y=2.25cm]
- % Let us start with some contacts:
- \foreach \contact/\y in {1/1,2/2,3/3.5,4/4.5,5/5.5}
- {
- \node [contact] (left contact \contact) at (0,\y) {};
- \node [contact] (right contact \contact) at (1,\y) {};
- }
- \draw (right contact 1) -- (right contact 2) -- (right contact 3)
- -- (right contact 4) -- (right contact 5);
-
- \draw (left contact 1) to [diode] ++(down:1)
- to [voltage source={near start,direction info={volt=3}},
- resistor={near end,ohm=3}] ++(right:1)
- to (right contact 1);
- \draw (left contact 1) to [resistor={ohm=4}] (right contact 1);
- \draw (left contact 1) to [resistor={ohm=3}] (left contact 2);
- \draw (left contact 2) to [voltage source={near start,
- direction info={<-,volt=8}},
- resistor={ohm=2,near end}] (right contact 2);
- \draw (left contact 2) to [resistor={near start,ohm=1},
- make contact={near end,info'={[red]$S_1$}}] (left contact 3);
- \draw (left contact 3) to [current direction'={near start,info=$\iota$},
- resistor={near end,info={$R=4\Omega$}}]
- (right contact 3);
- \draw (left contact 4) to [voltage source={near start,
- direction info={<-,volt=8}},
- resistor={ohm=2,near end}] (right contact 4);
- \draw (left contact 3) to [resistor={ohm=1}] (left contact 4);
- \draw (left contact 4) to [resistor={ohm=3}] (left contact 5);
- \draw (left contact 5) to [resistor={ohm=4}] (right contact 5);
- \draw (left contact 5) to [diode] ++(up:1)
- to [voltage source={near start,direction info={volt=3}},
- resistor={near end,ohm=3}] ++(right:1)
- to (right contact 5);
-\end{tikzpicture}
-
-
-\subsubsection{Symbols}
-
-A circuit typically consists of numerous electronic elements like logical gates
-or resistors or diodes that are connected by wires. In \pgfname/\tikzname, we
-use nodes for the electronic elements and normal lines for the wires.
-\tikzname\ offers a large number of different ways of positioning and
-connecting nodes in general, all of which can be used here. Additionally, the
-|circuits| library defines an additional useful |to|-path that is particularly
-useful for elements like a resistor on a line.
-
-There are many different names that are used to refer to electrical
-``elements'', so a bit of terminology standardization is useful: We will call
-such elements \emph{symbols}. A \emph{symbol shape} is a \pgfname\ shape
-declared using the |\pgfdeclareshape| command. A \emph{symbol node} is a node
-whose shape is a symbol shape.
-
-
-\subsubsection{Symbol Graphics}
-
-Symbols can be created by |\node[shape=some symbol shape]|. However, in order
-to represent some symbols correctly, just using standard \pgfname\ shapes is
-not sufficient. For instance, most symbols have a visually appealing ``default
-size'', but the size of a symbol shape depends only on the current values of
-parameters like |minimum height| or |inner xsep|.
-
-For these reasons, the circuit libraries introduce the concept of a
-\emph{symbol graphic}. This is a style that causes a |\node| to not only have
-the correct shape, but also the correct size and the correct path usage. More
-generally, this style may set up things in any way so that the ``symbol looks
-correct''. When you write, for instance, |\node[diode]|, then the style called
-|diode graphic| is used, which in turn is set to something like
-|shape=diode IEC,draw,minimum height=...|.
-
-Here is an overview of the different kinds of circuit libraries:
-%
-\begin{itemize}
- \item The \tikzname-library |circuits| defines general keys for creating
- circuits. Mostly, these keys are useful for defining more specialized
- libraries.
-
- You normally do not use this library directly since it does not define
- any symbol graphics.
- \item The \tikzname-library |circuits.logic| defines keys for creating
- logical gates like and-gates or xor-gates. However, this library also
- does not actually define any symbol graphics; this is done by two
- sublibraries:
- %
- \begin{itemize}
- \item The library |circuits.logic.US| defines symbol graphics that
- cause the logical gates to be rendered in the ``US-style''. It
- includes all of the above libraries and you can use this
- library directly.
- \item The library |circuits.logic.IEC| also defines symbol graphics
- for logical gates, but it uses rectangular gates rather that
- the round US-gates. This library can coexist peacefully with
- the above library, you can change which symbol graphics are
- used ``on the fly''.
- \end{itemize}
- \item The \tikzname-library |circuits.ee| defines keys for symbols from
- electrical engineering like resistors or capacitors. Again,
- sublibraries define the actual symbol graphics.
- %
- \begin{itemize}
- \item The library |circuits.ee.IEC| defines symbol shapes that
- follow the IEC norm.
- \end{itemize}
- \item The \pgfname-libraries |shapes.gates.*| define (circuit) symbol
- shapes. However, you normally do not use these shapes directly, rather
- you use a style that uses an appropriate symbol graphic, which in turn
- uses one of these shapes.
-\end{itemize}
-
-Let us have a look at a simple example. Suppose we wish to create a logical
-circuit. Then we first have to decide which symbol graphics we would like to
-use. Suppose we wish to use the US-style, then we would include the library
-|circuits.logic.US|. If you wish to use IEC-style symbols, use
-|circuits.logic.IEC|. If you cannot decide, include both:
-%
-\begin{codeexample}[code only]
-\usetikzlibrary{circuits.logic.US,circuits.logic.IEC}
-\end{codeexample}
-%
-To create a picture that contains a US-style circuit you can now use the option
-|circuit logic US|. This will set up keys like |and gate| to create use an
-appropriate symbol graphic for rendering an |and gate|. Using the
-|circuit logic IEC| instead will set up |and gate| to use another symbol
-graphic.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.US}}]
-\begin{tikzpicture}[circuit logic US]
- \matrix[column sep=7mm]
- {
- \node (i0) {0}; & & \\
- & \node [and gate] (a1) {}; & \\
- \node (i1) {0}; & & \node [or gate] (o) {};\\
- & \node [nand gate] (a2) {}; & \\
- \node (i2) {1}; & & \\
- };
- \draw (i0.east) -- ++(right:3mm) |- (a1.input 1);
- \draw (i1.east) -- ++(right:3mm) |- (a1.input 2);
- \draw (i1.east) -- ++(right:3mm) |- (a2.input 1);
- \draw (i2.east) -- ++(right:3mm) |- (a2.input 2);
- \draw (a1.output) -- ++(right:3mm) |- (o.input 1);
- \draw (a2.output) -- ++(right:3mm) |- (o.input 2);
- \draw (o.output) -- ++(right:3mm);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.IEC}}]
-\begin{tikzpicture}[circuit logic IEC]
- \matrix[column sep=7mm]
- {
- \node (i0) {0}; & & \\
- & \node [and gate] (a1) {}; & \\
- \node (i1) {0}; & & \node [or gate] (o) {};\\
- & \node [nand gate] (a2) {}; & \\
- \node (i2) {1}; & & \\
- };
- \draw (i0.east) -- ++(right:3mm) |- (a1.input 1);
- \draw (i1.east) -- ++(right:3mm) |- (a1.input 2);
- \draw (i1.east) -- ++(right:3mm) |- (a2.input 1);
- \draw (i2.east) -- ++(right:3mm) |- (a2.input 2);
- \draw (a1.output) -- ++(right:3mm) |- (o.input 1);
- \draw (a2.output) -- ++(right:3mm) |- (o.input 2);
- \draw (o.output) -- ++(right:3mm);
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{Annotations}
-
-An \emph{annotation} is a little extra drawing that can be added to a symbol.
-For instance, when you add two little parallel arrows pointing away from some
-electrical element, this usually means that the element is light emitting.
-
-Instead of having one symbol for ``diode'' and another for ``light emitting
-diode'', there is just one |diode| symbol, but you can add the |light emitting|
-annotation to it. This is done by passing the annotation as a parameter to the
-symbol as in the following example:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC]
- \draw (0,0) to [diode={light emitting}] (3,0)
- to [resistor={adjustable}] (3,2);
-\end{codeexample}
-
-
-\subsection{The Base Circuit Library}
-
-\begin{tikzlibrary}{circuits}
- This library is a base library that is included by other circuit libraries.
- You do not include it directly, but you will typically use some of the
- general keys, described below.
-\end{tikzlibrary}
-
-\begin{key}{/tikz/circuits}
- This key should be passed as an option to a picture or a scope that contains
- a circuit. It will do some internal setups. This key is normally called by
- more specialized keys like |circuit ee IEC|.
-\end{key}
-
-
-\subsubsection{Symbol Size}
-
-\begin{key}{/tikz/circuit symbol unit=\meta{dimension} (initially 7pt)}
- This dimension is a ``unit'' for the size of symbols. The libraries
- generally define the sizes of symbols relative to this dimension. For
- instance, the longer side of an inductor is, by default, in the IEC library
- equal to five times this \meta{dimension}. When you change this
- \meta{dimension}, the size of all symbols will automatically change
- accordingly.
-
- Note, that it is still possible to overwrite the size of any particular
- symbol. These settings apply only to the default sizes.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}[circuit ee IEC]
- \draw (0,1) to [resistor] (3.5,1);
- \draw[circuit symbol unit=14pt]
- (0,0) to [resistor] (3.5,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{stylekey}{/tikz/huge circuit symbols}
- This style sets the default circuit symbol unit to |10pt|.
-\end{stylekey}
-%
-\begin{stylekey}{/tikz/large circuit symbols}
- This style sets the default circuit symbol unit to |8pt|.
-\end{stylekey}
-%
-\begin{stylekey}{/tikz/medium circuit symbols}
- This style sets the default circuit symbol unit to |7pt|.
-\end{stylekey}
-%
-\begin{stylekey}{/tikz/small circuit symbols}
- This style sets the default circuit symbol unit to |6pt|.
-\end{stylekey}
-%
-\begin{stylekey}{/tikz/tiny circuit symbols}
- This style sets the default circuit symbol unit to |5pt|.
-\end{stylekey}
-
-\begin{key}{/tikz/circuit symbol size=|width| \meta{width} |height| \meta{height}}
- This key sets |minimum height| to \meta{height} times the current value of
- the circuit symbol unit and the |minimum width| to \meta{width} times this
- value. Thus, this option can be used with a node command to set the size of
- the node as a multiple of the circuit symbol unit.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}[circuit ee IEC]
- \draw (0,1) to [resistor] (2,1) to[inductor] (4,1);
-
- \begin{scope}
- [every resistor/.style={circuit symbol size=width 3 height 1}]
- \draw (0,0) to [resistor] (2,0) to[inductor] (4,0);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Declaring New Symbols}
-
-\begin{key}{/tikz/circuit declare symbol=\meta{name}}
- This key is used to declare a symbol. It does not cause this symbol to be
- shown nor does it set a graphic to be used for the symbol, it simply
- ``prepares'' several keys that can later be used to draw a symbol and to
- configure it.
-
- In detail, the first key that is defined is just called \meta{name}. This
- key should be given as an option to a |node| or on a |to| path, as
- explained below. The key will take options, which can be used to influence
- the way the symbol graphic is rendered.
-
- Let us have a look at an example. Suppose we want to define a symbol called
- |foo|, which just looks like a simple rectangle. We could then say
- %
-\begin{codeexample}[code only]
-\tikzset{circuit declare symbol=foo}
-\end{codeexample}
- %
- The symbol could now be used like this:
- %
-\begin{codeexample}[code only]
- \node [foo] at (1,1) {};
- \node [foo={red}] at (2,1) {};
-\end{codeexample}
-
- However, in the above example we would not actually see anything since we
- have not yet set up the graphic to be used by |foo|. For this, we must use
- a key called |set foo graphic| or, generally, |set| \meta{name} |graphic|.
- This key gets graphic options as parameter that will be set when a symbol
- |foo| should be shown:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits}}]
-\begin{tikzpicture}
- [circuit declare symbol=foo,
- set foo graphic={draw,shape=rectangle,minimum size=5mm}]
-
- \node [foo] at (1,1) {};
- \node [foo={red}] at (2,1) {};
-\end{tikzpicture}
-\end{codeexample}
-
- In detail, when you use the key \meta{name}=\meta{options} with a node, the
- following happens:
- %
- \begin{enumerate}
- \item The |inner sep| is set to |0.5pt|.
- \item The following style is executed:
- %
- \begin{stylekey}{/tikz/every circuit symbol}
- Use this style to set up things in general.
- \end{stylekey}
- \item The graphic options that have been set using |set| \meta{name}
- |graphic| are set.
- \item The style |every |\meta{name} is executed. You can use it to
- configure the symbol further.
- \item The \meta{options} are executed.
- \end{enumerate}
-
- The key \meta{name} will have a different effect when it is used on a |to|
- path command inside a |circuit| environment (the |circuit| environment sets
- up |to| paths in such a way that the use of a key declared using
- |circuit declare symbol| is automatically detected). When \meta{name} is
- used on a |to| path, the above actions also happen (setting the inner
- separation, using the symbol graphic, and so on), but they are passed to
- the key |circuit handle symbol|, which is explained next.
-\end{key}
-
-\begin{key}{/tikz/circuit handle symbol=\meta{options}}
- This key is mostly used internally. Its purpose is to render a symbol. The
- effect of this key differs, depending on whether it is used as the optional
- argument of a |to| path command or elsewhere.
-
- If the key is not used as an argument of a |to| path command, the
- \meta{options} are simply executed.
-
- The more interesting case happens when the key is given on a |to| path
- command. In this case, several things happen:
- %
- \begin{enumerate}
- \item The |to| path is locally changed and set to an internal path
- (which you should not try to change) that consists mostly of a
- single straight line.
- \item The \meta{options} are tentatively executed with filtering
- switched on. Everything is filtered out, except for the key |pos|
- and also the styles |at start|, |very near start|, |near start|,
- |midway|, |near end|, |very near end|, and |at end|. If none of
- them is found, |midway| is used.
- \item The filtered option is used to determine a position for the
- symbol on the path. At the given position (with |pos=0|
- representing the start and |pos=1| representing the end), a node
- will be added to the path (in a manner to be described presently).
- \item This node gets \meta{options} as its option list.
- \item The node is added by virtue of a special |markings| decoration.
- This means that a |mark| command is executed that causes the node
- to be placed as a mark on the path.
- \item The marking decoration will automatically subdivide the path and
- cause a line to be drawn from the start of the path to the node's
- border (at the position that lies on a line from the node's center
- to the start of the path) and then from the node's border (at a
- position on the other side of the node) to the end of the path.
- \item The marking decoration will also take care of the case that
- multiple marks are present on a path, in this case the lines from
- and to the borders of the nodes are only between consecutive nodes.
- \item The marking decoration will also rotate the coordinate system in
- such a way that the $x$-axis points along the path. Thus, if you
- use the |transform shape| option, the node will ``point along'' the
- path.
- \item In case a node is at |pos=0| or at |pos=1| some special code will
- suppress the superfluous lines to the start or end of the path.
- \end{enumerate}
-
- The net effect of all of the above is that a node will be placed ``on the
- path'' and the path will have a ``gap'' just large enough to encompass the
- node. Another effect is that you can use this key multiple times on a path
- to add several node to a path, provided they do not overlap.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits}}]
-\begin{tikzpicture}[circuit]
- \draw (0,0) to [circuit handle symbol={draw,shape=rectangle,near start},
- circuit handle symbol={draw,shape=circle,near end}] (3,2);
- \end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits}}]
-\begin{tikzpicture}[transform shape,circuit]
- \draw (0,0) to [circuit handle symbol={draw,shape=rectangle,at start},
- circuit handle symbol={draw,shape=circle,near end}] (3,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Pointing Symbols in the Right Direction}
-
-Unlike normal nodes, which generally should not be rotated since this will make
-their text hard to read, symbols often need to be rotated. There are two ways
-of achieving such rotations:
-%
-\begin{enumerate}
- \item When you place a symbol on a |to| path, the graphic symbol is
- automatically rotated such that it ``points along the path''. Here is
- an examples that shows how the inductor shape (which looks, unrotated,
- like this: \tikz[circuit ee IEC]\node[inductor]{};) is automatically
- rotated around:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC]
- \draw (3,0) to[inductor] (1,0) to[inductor] (0,2);
-\end{codeexample}
- %
- \item Many shapes cannot be placed ``on'' a path in this way, namely
- whenever there are more than two possible inputs. Also, you may wish to
- place the nodes first, possibly using a matrix, and connect them
- afterwards. In this case, you can simply add rotations like |rotate=90|
- to the shapes to rotate them. The following four keys make this
- slightly more convenient:
- %
- \begin{key}{/tikz/point up}
- This is the same as |rotate=90|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC] \node [diode,point up] {};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/point down}
- This is the same as |rotate=-90|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC] \node [diode,point down] {};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/point left}
- This is the same as |rotate=-180|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC] \node [diode,point left] {};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/point right}
- This key has no effect.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC] \node [diode,point right] {};
-\end{codeexample}
- \end{key}
-\end{enumerate}
-
-
-\subsubsection{Info Labels}
-
-Info labels are used to add text to a circuit symbol. Unlike normal nodes like
-a rectangle, circuit symbols typically do not have text ``on'' them, but the
-text is placed next to them (like the text ``$3\,\Omega$'' next to a resistor).
-
-\tikzname\ already provides the |label| option for this purpose. The |info|
-option is built on top of this option, but it comes in some predefined variants
-that are especially useful in conjunction with circuits.
-
-\begin{key}{/tikz/info=\opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{text}}
- This key has nearly the same effect as the |label| key, only the following
- style is used additionally automatically:
- %
- \begin{stylekey}{/tikz/every info}
- Set this style to configure the styling of info labels. Since this
- key is \emph{not} used with normal labels, it provides an easy way
- of changing the way info labels look without changing other
- labels.
- \end{stylekey}
- %
- The \meta{options} and \meta{angle} are passed directly to the |label|
- command.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}[circuit ee IEC,every info/.style=red]
- \node [resistor,info=$3\Omega$] {};
-\end{tikzpicture}
-\end{codeexample}
-
- You will find a detailed discussion of the |label| option on
- page~\pageref{label-option}.
-
- Hint: To place some text \emph{on} the main node, use |center| as the
- \meta{angle}:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}[circuit ee IEC,every info/.style=red]
- \node [resistor,info=center:$3\Omega$] {};
- \node [resistor,point up,info=center:$R_1$] at (2,0) {};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/info'=\opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{text}}
- This key works exactly like the |info| key, only in case the \meta{angle}
- is missing, it defaults to |below| instead of the current value of
- |label position|, which is usually |above|. This means that when you use
- |info|, you get a label above the node, while when you use the |info'| key
- you get a label below the node. In case the node has been rotated, the
- positions of the info nodes are rotated accordingly.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}[circuit ee IEC,every info/.style=red]
- \draw (0,0) to[resistor={info={$3\Omega$},info'={$R_1$}}] (3,0)
- to[resistor={info={$4\Omega$},info'={$R_2$}}] (3,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/info sloped=\opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{text}}
- This key works like |info|, only the |transform shape| option is set when
- the label is drawn, causing it to follow the sloping of the main node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}[circuit ee IEC,every info/.style=red]
- \draw (0,0) to[resistor={info sloped={$3\Omega$}}] (3,0)
- to[resistor={info sloped={$4\Omega$}}] (3,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/info' sloped=}
- This is a combination of |info'| and |info sloped|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}[circuit ee IEC,every info/.style=red]
- \draw (0,0) to[resistor={info' sloped={$3\Omega$}}] (3,0)
- to[resistor={info' sloped={$4\Omega$}}] (3,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/circuit declare unit=\marg{name}\marg{unit}}
- This key is used to declare keys that make it easy to attach physical units
- to nodes. The idea is that instead of |info=$3\Omega$| you can write
- |ohm=3| or instead of |info'=$5\mathrm{S}$| you can write |siemens'=5|.
-
- In detail, four keys are defined, namely |/tikz/|\meta{name},
- |/tikz/|\meta{name}|'|, |/tikz/|\meta{name} |sloped|, and
- |/tikz/|\meta{name}|'| |sloped|. The arguments of all of these keys are of
- the form \opt{|[|\meta{options}|]|\meta{angle}|:|}\meta{value} and it is
- passed (slightly modified) to the corresponding key |info|, |info'|, |info|
- |sloped|, or |info'| |sloped|. The ``slight modification'' is the
- following: The text that is passed to the, say, |info| key is not
- \meta{value}, but rather |$\mathrm{|\meta{value}\meta{unit}|}$|
-
- This means that after you said |circuit declare unit={ohm}{\Omega}|, then
- |ohm=5k| will have the same effect as
- |info={[every ohm]$\mathrm{5k\Omega}$}|. Here, |every ohm| is a style that
- allows you to configure the appearance of this unit. Since the |info| key
- is used internally, by changing the |every info| style, you can change the
- appearance of all units infos.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}[circuit ee IEC,circuit declare unit={my ohm}{O}]
- \draw (0,0) to[resistor={my ohm' sloped=3}] (3,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Declaring and Using Annotations}
-
-Annotations are quite similar to info labels. The main difference is that they
-generally cause something to be drawn by default rather than some text to be
-added (although an annotation might also add some text).
-
-Annotations can be declared using the following key:
-
-\begin{key}{/tikz/circuit declare annotation=\marg{name}\marg{distance}\marg{path}}
- This key is used to declare an annotation named \meta{name}. Once declared,
- it can be used as an argument of a symbol and will add the drawing in
- \meta{path} to the symbol. In detail, the following happens:
-
-
- \textbf{The Main Keys.}
- Two keys called \meta{name} and \meta{name}|'| are defined. The second
- causes the annotation to be ``mirrored and placed on the other side'' of
- the symbol. Both of these keys may also take further keys as parameter like
- |info| keys. Whenever the \meta{name} key is used, a local scope is opened
- and in this scope the following things are done:
- %
- \begin{enumerate}
- \item The style |every| \meta{name} is executed.
- \item The following style is executed and then |arrows=->|:
- %
- \begin{stylekey}{/tikz/annotation arrow}
- This style should set the |>| key to some desirable arrow tip.
- \end{stylekey}
- \item The coordinate system is shifted such that the origin is at the
- north anchor of the symbol. (For the \meta{name}|'| key the
- coordinate system is flipped and shifted such that the origin is at
- the south anchor of the symbol.)
- \item The |label distance| is locally set to \meta{distance}.
- \item The parameter options given to the \meta{name} key are executed.
- \item The \meta{path} is executed.
- \end{enumerate}
-
-
- \textbf{Usage.}
- What all of the above amounts to is best explained by an example. Suppose
- we wish to create an annotation that looks like a little circular arrow
- (like \tikz \draw [->] (0,0) arc (-270:80:1ex);). We could then say:
- %
-\begin{codeexample}[code only]
-\tikzset{circuit declare annotation=
- {circular annotation}
- {9pt}
- {(0pt,8pt) arc (-270:80:3.5pt)}
-}
-\end{codeexample}
- %
- We can then use it like this:
- %
-\tikzset{circuit declare annotation=
- {circular annotation}
- {8pt}
- {(0pt,8pt) arc (-270:80:3.5pt)}
-}
-\begin{codeexample}[
- preamble={\usetikzlibrary{circuits.ee.IEC}}
- pre={\tikzset{circuit declare annotation=
- {circular annotation}
- {8pt}
- {(0pt,8pt) arc (-270:80:3.5pt)}
-}}]
-\tikz[circuit ee IEC]
- \draw (0,0) to [resistor={circular annotation}] (3,0);
-\end{codeexample}
- %
- Well, not very impressive since we do not see anything. This is due to the
- fact that the \meta{path} becomes part of a path that contains the symbol
- node an nothing else. This path is not drawn or filled, so we do not see
- anything. What we must do is to use an |edge| path operation:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikzset{circuit declare annotation={circular annotation}{9pt}
- {(0pt,8pt) edge[to path={arc(-270:80:3.5pt)}] ()}
-}
-\tikz[circuit ee IEC]
- \draw (0,0) to [resistor={circular annotation}] (3,0)
- to [capacitor={circular annotation'}] (3,2);
-\end{codeexample}
- %
- The \meta{distance} is important for the correct placement of additional
- |info| labels. When an annotation is present, the info labels may need to
- be moved further away from the symbol, but not always. For this reason, an
- annotation defines an additional \meta{distance} that is applied to all
- info labels given as parameters to the annotation. Here is an example, that
- shows the difference:
- %
-\tikzset{circuit declare annotation={circular annotation}{9pt}
- {(0pt,8pt) edge[to path={arc (-270:80:3.5pt)}] ()}
-}
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}
- pre={\tikzset{circuit declare annotation=
- {circular annotation}
- {8pt}
- {(0pt,8pt) arc (-270:80:3.5pt)}
-}}]
-\tikz[circuit ee IEC]
- \draw (0,0) to [resistor={circular annotation,ohm=5}] (2,0)
- to [resistor={circular annotation={ohm=5}}] (4,0);
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Theming Symbols}
-\label{section-theming-symbols}
-
-For each symbol, a certain graphical representation is chosen to actually show
-the symbol. You can modify this graphical representation in several ways:
-%
-\begin{itemize}
- \item You can select a different library and use a different |circuit ...|
- key. This will change all graphics used for the symbols.
- \item You can generally change the size of graphic symbols by setting
- |circuit size unit| to a different value or using a key like
- |small circuit symbols|.
- \item You can add options to the graphics used by symbols either globally
- by setting the |every circuit| |symbol| style or locally by setting the
- |every| \meta{name} style, where \meta{name} is the name of a symbol.
- For instance, in the following picture the symbols are ridiculously
- thick and resistors are red.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}
- [circuit ee IEC,
- every circuit symbol/.style={ultra thick},
- every resistor/.style={red}]
-
- \draw (0,0) to [inductor] ++(right:3) to [resistor] ++(up:2);
-\end{tikzpicture}
-\end{codeexample}
- %
- \item You can selectively change the graphic used for a symbol by saying
- |set resistor graphic=|.
- \item You can change one or more of the following styles:
- %
- \begin{stylekey}{/tikz/circuit symbol open (initially draw)}
- This style is used with symbols that consist of lines that surround
- some area. For instance, the IEC version of a resistor is an open
- symbol.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC,
- circuit symbol open/.style={thick,draw,fill=yellow}]
- \draw (0,0) to [inductor] ++(right:3) to [resistor] ++(up:2);
-\end{codeexample}
- \end{stylekey}
- %
- \begin{stylekey}{/tikz/circuit symbol filled (initially {draw,fill=black})}
- This style is used with symbols that are completely filled. For
- instance, the variant IEC version of an inductor is a filled, black
- rectangle.
- \end{stylekey}
- %
- \begin{stylekey}{/tikz/circuit symbol lines (initially draw)}
- This style is used with symbols that consist only of lines that do
- not surround anything. Examples are a capacitor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC,
- circuit symbol lines/.style={thick,draw=red}]
- \draw (0,0) to [capacitor] ++(right:3) to [resistor] ++(up:2);
-\end{codeexample}
- \end{stylekey}
- %
- \begin{stylekey}{/tikz/circuit symbol wires (initially draw)}
- This style is used for symbols that consist only of ``wires''. The
- difference to the previous style is that a symbol consisting of
- wires will look strange when the lines are thicker than the lines
- of normal wires, while for symbols consisting of lines (but not
- wires) it may look nice to make them thicker. An example is the
- |make contact| symbol.
-
- Compare
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC,circuit symbol lines/.style={draw,very thick}]
- \draw (0,0) to [capacitor={near start},
- make contact={near end}] (3,0);
-\end{codeexample}
- %
- to
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC,circuit symbol wires/.style={draw,very thick}]
- \draw (0,0) to [capacitor={near start},
- make contact={near end}] (3,0);
-\end{codeexample}
- \end{stylekey}
-\end{itemize}
-
-All circuit environments like |circuit logic IEC| mainly use options like
-|set and gate graphic=...| to set up the graphics used for a certain symbol. It
-turns out that graphic hidden in the ``|...|'' part is also always available as
-a separate style, whose name contains the library's initials. For instance, the
-|circuit logic IEC| option actually contains the following command:
-%
-\begin{codeexample}[code only]
- set and gate graphic = and gate IEC graphic,
-\end{codeexample}
-%
-The |and gate IEC graphic| style, in turn, is defined as follows:
-%
-\begin{codeexample}[code only]
-\tikzset{and gate IEC graphic/.style=
- {
- circuit symbol open,
- circuit symbol size=width 2.5 height 4,
- shape=and gate IEC,
- inner sep=.5ex
- }
-}
-\end{codeexample}
-
-Normally, you do not need to worry about this, since you will not need to
-access a style like |and gate IEC graphic| directly; you will only use the
-|and gate| key. However, sometimes libraries define \emph{variants} of a
-graphic; for instance, there are two variants for the resistor graphic in the
-IEC library. In this case you can set the graphic for the resistor to this
-variant (or back to the original) by saying |set resistor graphic| yourself:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}[circuit ee IEC]
- % Standard resistor
- \draw (0,2) to [resistor] (3,2);
-
- % Var resistor
- \begin{scope}[set resistor graphic=var resistor IEC graphic]
- \draw (0,1) to [resistor] (3,1);
-
- % Back to original
- \draw [set resistor graphic=resistor IEC graphic]
- (0,0) to [resistor] (3,0);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Logical Circuits}
-
-\subsubsection{Overview}
-
-A \emph{logical circuit} is a circuit that contains what we call \emph{logical
-gates} like an |and gate| or an |xor gate|. The logical libraries are intended
-to make it easy to draw such circuits.
-
-In the following, we first have a look at the different libraries that can be
-used in principle and how the symbols look like. Then we have a more detailed
-look at how the symbols are used. Finally, we discuss the implementation
-details.
-
-There are different ways of depicting logical gates, which is why there are
-different (sub-)libraries for drawing them. They provide the necessary
-graphical representations of the symbols declared in the following library:
-
-\begin{tikzlibrary}{circuits.logic}
- This library declares the logical gate symbols, but does not provide the
- symbol graphics. The library also defines the following key which, however,
- is also only used indirectly, namely by other libraries:
- %
- \begin{key}{/tikz/circuit logic}
- This style calls the keys |circuit| (which internally calls
- |every circuit|, then it defines the |inputs| key and it calls the
- |every circuit logic| key.
- %
- \begin{key}{/tikz/inputs=\meta{inputs}}
- This key is defined only inside the scope of a |circuit logic|.
- There, it has the same effect as |logic gate inputs|, described on
- page~\pageref{logic-gate-inputs}.
- \end{key}
- %
- \begin{stylekey}{/tikz/every circuit logic}
- Use this key to configure the appearance of logical circuits.
- \end{stylekey}
- \end{key}
-\end{tikzlibrary}
-
-Since the |circuits.logic| library does not define any actual graphics, you need
-to use one of the following libraries, instead:
-
-\begin{tikzlibrary}{circuits.logic.IEC}
- This library provides graphics based on gates recommended by the
- International Electrotechnical Commission. When you include this library,
- you can use the following key to set up a scope that contains a logical
- circuit where the gates are shown in this style.
-
- \begin{key}{/tikz/circuit logic IEC}
- This key calls |circuit logic| and installs the IEC-like graphics for
- the logical symbols like |and gate|.
-
- As explained in Section~\ref{section-theming-symbols}, for each graphic
- symbol of the library there is also a style that stores this particular
- appearance. These keys are called |and gate IEC graphic|,
- |or gate IEC graphic|, and so on.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.IEC}}]
-\begin{tikzpicture}[circuit logic IEC,
- every circuit symbol/.style={
- logic gate IEC symbol color=black,
- fill=blue!20,draw=blue,very thick}]
- \matrix[column sep=7mm]
- {
- \node (i0) {0}; & & \\
- & \node [and gate] (a1) {}; & \\
- \node (i1) {0}; & & \node [or gate] (o) {};\\
- & \node [nand gate] (a2) {}; & \\
- \node (i2) {1}; & & \\
- };
- \draw (i0.east) -- ++(right:3mm) |- (a1.input 1);
- \draw (i1.east) -- ++(right:3mm) |- (a1.input 2);
- \draw (i1.east) -- ++(right:3mm) |- (a2.input 1);
- \draw (i2.east) -- ++(right:3mm) |- (a2.input 2);
- \draw (a1.output) -- ++(right:3mm) |- (o.input 1);
- \draw (a2.output) -- ++(right:3mm) |- (o.input 2);
- \draw (o.output) -- ++(right:3mm);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{tikzlibrary}
-
-\begin{tikzlibrary}{circuits.logic.US}
- This library provides graphics showing ``American'' logic gates. It defines
- the following key:
-
- \begin{key}{/tikz/circuit logic US}
- This style calls |circuit logic| and installs US-like graphics for the
- logical symbols like |and gate|. For instance, it says
- %
-\begin{codeexample}[code only]
-set and gate graphic = and gate US graphic
-\end{codeexample}
-
- Here is an example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.CDH}}]
-\begin{tikzpicture}[circuit logic CDH,
- tiny circuit symbols,
- every circuit symbol/.style={
- fill=white,draw}]
- \matrix[column sep=7mm]
- {
- \node (i0) {0}; & & \\
- & \node [and gate] (a1) {}; & \\
- \node (i1) {0}; & & \node [or gate] (o) {};\\
- & \node [nand gate] (a2) {}; & \\
- \node (i2) {1}; & & \\
- };
- \draw (i0.east) -- ++(right:3mm) |- (a1.input 1);
- \draw (i1.east) -- ++(right:3mm) |- (a1.input 2);
- \draw (i1.east) -- ++(right:3mm) |- (a2.input 1);
- \draw (i2.east) -- ++(right:3mm) |- (a2.input 2);
- \draw (a1.output) -- ++(right:3mm) |- (o.input 1);
- \draw (a2.output) -- ++(right:3mm) |- (o.input 2);
- \draw (o.output) -- ++(right:3mm);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{tikzlibrary}
-
-\begin{tikzlibrary}{circuits.logic.CDH}
- This library provides graphics based on the logic symbols used in A. Croft,
- R. Davidson, and M. Hargreaves (1992), \emph{Engineering Mathematics},
- Addison-Wesley, 82--95. They are identical to the US-style symbols, except
- for the and- and nand-gates.
-
- \begin{key}{/tikz/circuit logic CDH}
- This key calls |circuit logic US| and installs the two special and- and
- nand-gates, that is, it uses |set and gate graphic| with
- |and gate CDH graphic| and likewise for nand-gates.
- \end{key}
-\end{tikzlibrary}
-
-Inside |circuit logic XYZ| scopes, you can now use the keys shown in
-Section~\ref{section-logic-symbols}. We have a more detailed look at one of
-them, all the other work the same way:
-
-\begin{key}{/tikz/and gate}
- This key should be passed to a |node| command. It will cause the node to
- ``look like'' an |and gate|, where the exact appearance of the gate is
- dictated by the which circuit environment is used. To further configure the
- appearance of the |and gate|, see Section~\ref{section-theming-symbols}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.IEC}}]
-\tikz [circuit logic IEC] \node [and gate] {$A$};
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.US}}]
-\tikz [circuit logic US]
-{
- \node [and gate,point down] {$A$};
- \node [and gate,point down,info=center:$A$] at (1,0) {};
-}
-\end{codeexample}
-
- \medskip\textbf{Inputs.}
- Multiple inputs can be specified for a logic gate (provided they support
- multiple inputs: a not gate -- also known as an inverter -- does not).
- However, there is an upper limit for the number of inputs which has been
- set to 1024, which should be \emph{way} more than would ever be needed.
-
- The following key is used to configure the inputs. It is available only
- inside a |circuit logic| environment.
-
- \begin{key}{/tikz/inputs=\meta{input list} (initially \char`\{normal,normal\char`\})}
- If a gate has $n$ inputs, the \meta{input list} should consists of $n$
- letters, each being |i| for ``inverted'' or |n| for ``normal''.
- Inverted gates will be indicated by a little circle. In any case the
- anchors for the inputs will be set up appropriately, numbered from top
- to bottom |input 1|, |input 2|, \ldots and so on. If the gate only
- supports one input the anchor is simply called |input| with no
- numerical index.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.IEC}}]
-\begin{tikzpicture}[circuit logic IEC]
- \node[and gate,inputs={inini}] (A) {};
- \foreach \a in {1,...,5}
- \draw (A.input \a -| -1,0) -- (A.input \a);
- \draw (A.output) -- ++(right:5mm);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- (This key is just a shorthand for |logic gate inputs|, described in detail
- on page~\pageref{logic-gate-inputs}. There you will also find descriptions
- of how to configure the size of the inverted circles and the way the symbol
- size increases when there are too many inputs.)
-
- \textbf{Output.}
- Every logic gate has one anchor called |output|.
-\end{key}
-
-
-\subsubsection{Symbols: The Gates}
-\label{section-logic-symbols}
-
-The following table shows which symbols are declared by the main
-|circuits.logic| library and their appearance in the different sublibraries.
-\medskip
-
-\def\gateexamples#1{%
- \texttt{#1}
- \indexkey{#1} &
- \tikz[baseline,circuit logic IEC] \node[#1,label=] {}; &
- \tikz[baseline,circuit logic US] \node[#1] {}; &
- \tikz[baseline,circuit logic CDH] \node[#1] {};
-}
-\begin{tabular}{lccc}
- \emph{Key} & \emph{Appearance inside} & \emph{Appearance inside} & \emph{Appearance inside} \\
- & |circuit logic IEC| & |circuit logic US| & |circuit logic CDH| \\
- \gateexamples{/tikz/and gate}\\
- \gateexamples{/tikz/nand gate}\\
- \gateexamples{/tikz/or gate}\\
- \gateexamples{/tikz/nor gate}\\
- \gateexamples{/tikz/xor gate}\\
- \gateexamples{/tikz/xnor gate}\\
- \gateexamples{/tikz/not gate}\\
- \gateexamples{/tikz/buffer gate}
-\end{tabular}
-
-
-\subsubsection{Implementation: The Logic Gates Shape Library}
-
-The previous sections described the \tikzname\ interface for creating logical
-circuits. In this section we take a closer look at the underlying \pgfname\
-libraries.
-
-Just as there are several \tikzname\ circuit libraries, there are two
-underlying \pgfname\ shape libraries, one for creating US-style gates and one
-for IEC-style gates. These libraries define \emph{shapes} only. It is the job
-of the circuit libraries to ``theme'' them so that they ``look nice''. However,
-in principle, you can also use these shapes directly.
-
-Let us begin with the base library that defines the handling of inputs.
-
-\begin{pgflibrary}{shapes.gates.logic}
- This library defines common keys used by all logical gate shapes.
-
- \begin{key}{/pgf/logic gate inputs=\meta{input list} (initially \char`\{normal,normal\char`\})}
- \label{logic-gate-inputs}%
- Specify the inputs for the logic gate. The keyword |inverted| indicates
- an inverted input which will mean \pgfname{} will draw a circle
- attached to the main shape of the logic gate. Any keyword that is not
- |inverted| will be treated as a ``normal'' or ``non-inverted'' input
- (however, for readability, you may wish to use |normal| or
- |non-inverted|), and \pgfname{} will not draw the circle. In both cases
- the anchors for the inputs will be set up appropriately, numbered from
- top to bottom |input 1|, |input 2|, \ldots and so on. If the gate only
- supports one input the anchor is simply called |input| with no
- numerical index.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.IEC}}]
-\begin{tikzpicture}[minimum height=0.75cm]
- \node[and gate IEC, draw, logic gate inputs={inverted, normal, inverted}]
- (A) {};
- \foreach \a in {1,...,3}
- \draw (A.input \a -| -1,0) -- (A.input \a);
- \draw (A.output) -- ([xshift=0.5cm]A.output);
-\end{tikzpicture}
-\end{codeexample}
-
- For multiple inputs it may be somewhat unwieldy to specify a long list,
- thus, the following ``shorthand'' is permitted (this is an extension of
- ideas due to Jürgen Werber and Christoph Bartoschek): Using |i| for
- inverted and |n| for normal inputs, \meta{input list} can be specified
- \emph{without the commas}. So, for example, |ini| is equivalent to
- |inverted, normal, inverted|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.US}}]
-\begin{tikzpicture}[minimum height=0.75cm]
- \node[or gate US, draw,logic gate inputs=inini] (A) {};
- \foreach \a in {1,...,5}
- \draw (A.input \a -| -1,0) -- (A.input \a);
- \draw (A.output) -- ([xshift=0.5cm]A.output);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- The height of the gate may be increased to accommodate the number of
- inputs. In fact, it depends on three variables: $n$, the number of inputs,
- $r$, the radius of the circle used to indicate an inverted input and $s$,
- the distance between the centers of the inputs. The default height is then
- calculated according to the expression $(n+1)\times\max(2r,s)$. This then
- may be increased to accommodate the node contents or any minimum size
- specifications.
-
- The radius of the inverted input circle and the distance between the
- centers of the inputs can be customized using the following keys:
-
- \begin{key}{/pgf/logic gate inverted radius=\meta{length} (initially 2pt)}
- Set the radius of the circle that is used to indicate inverted inputs.
- This is also the radius of the circle used for the inverted output of
- the |nand|, |nor|, |xnor| and |not| gates.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.CDH}}]
-\begin{tikzpicture}[minimum height=0.75cm]
- \tikzset{every node/.style={shape=nand gate CDH, draw, logic gate inputs=ii}}
- \node[logic gate inverted radius=2pt] {A};
- \node[logic gate inverted radius=4pt] at (0,-1) {B};
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/logic gate input sep=\meta{length} (initially .125cm)}
- Set the distance between the \emph{centers} of the inputs to the logic
- gate.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.IEC}}]
-\begin{tikzpicture}[minimum size=0.75cm]
- \draw [help lines] grid (3,2);
- \tikzset{every node/.style={shape=and gate IEC, draw, logic gate inputs=ini}}
- \node[logic gate input sep=0.33333cm] at (1,1)(A) {A};
- \node[logic gate input sep=0.5cm] at (3,1) (B) {B};
- \foreach \a in {1,...,3}
- \draw (A.input \a -| 0,0) -- (A.input \a)
- (B.input \a -| 2,0) -- (B.input \a);
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
-
- \pgfname{} will increase the size of the logic gate to accommodate the
- number of inputs, and the size of the inverted radius and the separation
- between the inputs. However with all shapes in this library, any increase
- in size (including any minimum size requirements) will be applied so that
- the default aspect ratio is unaltered. This means that changing the height
- will change the width and vice versa.
-\end{pgflibrary}
-
-
-\subsubsection{Implementation: The US-Style Logic Gates Shape Library}
-
-\begin{pgflibrary}{shapes.gates.logic.US}
- This library provides ``American'' logic gate shapes whose names are
- suffixed with the identifier |US|. Additionally, alternative |and| and
- |nand| gates are provided which are based on the logic symbols used in A.
- Croft, R. Davidson, and M. Hargreaves (1992), \emph{Engineering
- Mathematics}, Addison-Wesley, 82--95. These two shapes are suffixed with
- |CDH|.
-
- The ``compass point'' anchors apply to the main part of the shape and do
- not include any inverted inputs or outputs. This library provides an
- additional feature to facilitate the relative positioning of logic gates:
-
- \begin{key}{/pgf/logic gate anchors use bounding box=\meta{boolean} (initially false)}
- When set to |true| this key will ensure that the compass point anchors
- use the bounding rectangle of the main shape, which, ignore any
- inverted inputs or outputs, but includes any |outer sep|. This
- \emph{only} affects the compass point anchors and is not set on a shape
- by shape basis: whether the bounding box is used is determined by value
- of this key when the anchor is accessed.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.US}}]
-\begin{tikzpicture}[minimum height=1.5cm]
- \node[xnor gate US, draw, gray!50,line width=2pt] (A) {};
- \foreach \x/\y/\z in {false/blue/1pt, true/red/2pt}
- \foreach \a in {north, south, east, west, north east,
- south east, north west, south west}
- \draw[logic gate anchors use bounding box=\x, color=\y]
- (A.\a) circle(\z);
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
-
- The library defines a number of shapes. For each shape the allowed number
- of inputs is also shown:
- %
- \begin{itemize}
- \item |and gate US|, two or more inputs
- \item |and gate CDH|, two or more inputs
- \item |nand gate US|, two or more inputs
- \item |nand gate CDH|, two or more inputs
- \item |or gate US|, two or more inputs
- \item |nor gate US|, two or more Inputs
- \item |xor gate US|, two inputs
- \item |xnor gate US|, two inputs
- \item |not gate US|, one input
- \item |buffer gate US|, one input
- \end{itemize}
-
- In the following, we only have a detailed look at the anchors defined by
- one of them. We choose the |nand gate US| because it shows all the
- ``interesting'' anchors.
-
- \begin{shape}{nand gate US}
- This shape is a nand gate, which supports two or more inputs. If less
- than two inputs are specified an error will result. The anchors for
- this gate with two non-inverted inputs (using the normal compass point
- anchors) are shown below. Anchor |30| is an example of a border anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.US}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=nand gate US,shape example, inner sep=0cm,
- logic gate inputs={in},
- logic gate inverted radius=.5cm] {Nand Gate\vrule width1pt height2cm};
- \foreach \anchor/\placement in
- {center/above, text/above, 30/above right,
- mid/right, mid east/left, mid west/above,
- base/below, base east/below, base west/left,
- north/above, south/below, east/above, west/above,
- north east/above, south east/below, south west/below, north west/above,
- output/right, input 1/above, input 2/below}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
-
- (For the definition of the |shape example| style, see
- Section~\ref{section-libs-shapes}.)
- \end{shape}
-\end{pgflibrary}
-
-
-\subsubsection{Implementation: The IEC-Style Logic Gates Shape Library}
-
-\begin{pgflibrary}{shapes.gates.logic.IEC}
- This library provides rectangular logic gate shapes. These shapes are
- suffixed with |IEC| as they are based on gates recommended by the
- International Electrotechnical Commission.
-
- By default each gate is drawn with a symbol, $\char`\&$ for |and| and
- |nand| gates, $\geq1$ for |or| and |nor| gates, $1$ for |not| and |buffer|
- gates, and $=1$ for |xor| and |xnor| gates. These symbols are drawn
- automatically (internally they are drawn using the ``foreground'' path),
- and are not strictly speaking part of the node contents. However, the gate
- is enlarged to make sure the symbols are within the border of the node. It
- is possible to change the symbols and their position within the node using
- the following keys:
-
- \begin{key}{/pgf/and gate IEC symbol=\meta{text} (initially \char`\\char\char`\`\char`\\\char`\&)}
- Set the symbol for the |and gate|. Note that if the node is filled,
- this color will be used for the symbol, making it invisible, so it will
- be necessary set \meta{text} to something like |\color{black}\char`\&|.
- Alternatively, the |logic gate IEC symbol color| key can be used to set
- the color of all symbols simultaneously.
-
- In \tikzname, when the |use IEC style logic gates| key has been used,
- this key can be replaced by |and gate symbol|.
- \end{key}
-
- \begin{key}{/pgf/nand gate IEC symbol=\meta{text} (initially \char`\\char\char`\`\char`\\\char`\&)}
- Set the symbol for the |nand gate|. In \tikzname, when the
- |use IEC style logic gates| key has been used, this key can be replaced
- by |nand gate symbol|.
- \end{key}
-
- \begin{key}{/pgf/or gate IEC symbol=\meta{text} (initially \char`\$\char`\\geq1\char`\$)}
- Set the symbol for the |or gate|. In \tikzname, when the
- |use IEC style logic gates| key has been used, this key can be replaced
- by |or gate symbol|.
- \end{key}
-
- \begin{key}{/pgf/nor gate IEC symbol=\meta{text} (initially \char`\$\char`\\geq1\char`\$)}
- Set the symbol for the |nor gate|. In \tikzname, when the
- |use IEC style logic gates| key has been used, this key can be replaced
- by |nor gate symbol|.
- \end{key}
-
- \begin{key}{/pgf/xor gate IEC symbol=\meta{text} (initially \char`\{\char`\$=1\char`\$\char`\})}
- Set the symbol for the |xor gate|. Note the necessity for braces, as
- the symbol contains |=|. In \tikzname, when the
- |use IEC style logic gates| key has been used, this key can be replaced
- by |xor gate symbol|.
- \end{key}
-
- \begin{key}{/pgf/xnor gate IEC symbol=\meta{text} (initially \char`\{\char`\$=1\char`\$\char`\})}
- Set the symbol for the |xnor gate|. In \tikzname, when the
- |use IEC style logic gates| key has been used, this key can be replaced
- by |xnor gate symbol|.
- \end{key}
-
- \begin{key}{/pgf/not gate IEC symbol=\meta{text} (initially 1)}
- Set the symbol for the |not gate|. In \tikzname, when the
- |use IEC style logic gates| key has been used, this key can be replaced
- by |not gate symbol|.
- \end{key}
-
- \begin{key}{/pgf/buffer gate IEC symbol=\meta{text} (initially 1)}
- Set the symbol for the |buffer gate|. In \tikzname, when the
- |use IEC style logic gates| key has been used, this key can be replaced
- by |buffer gate symbol|.
- \end{key}
-
- \begin{key}{/pgf/logic gate IEC symbol align=\meta{align} (initially top)}
- Set the alignment of the logic gate symbol (in \tikzname, when the
- |use IEC style logic gates| key has been used, |IEC| can be omitted).
- The specification in \meta{align} is a comma separated list from |top|,
- |bottom|, |left| or |right|. The distance between the border of the
- node and the outer edge of the symbol is determined by the values of
- the |inner xsep| and |inner ysep|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.gates.logic.IEC}}]
-\begin{tikzpicture}[minimum size=1cm, use IEC style logic gates]
- \tikzset{every node/.style={nor gate, draw}}
- \node (A) at (0,1.5) {};
- \node [logic gate symbol align={bottom, right}] (B) at (0,0) {};
- \foreach \g in {A, B}{
- \foreach \i in {1,2}
- \draw ([xshift=-0.5cm]\g.input \i) -- (\g.input \i);
- \draw (\g.output) -- ([xshift=0.5cm]\g.output);
- }
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/logic gate IEC symbol color=\meta{color}}
- This key sets the color for all symbols simultaneously. This color can
- be overridden on a case by case basis by specifying a color when
- setting the symbol text.
- \end{key}
-
- The library defines the following shapes:
- %
- \begin{itemize}
- \item |and gate IEC|, two or more inputs
- \item |nand gate IEC|, two or more inputs
- \item |or gate IEC|, two or more inputs
- \item |nor gate IEC|, two or more inputs
- \item |xor gate IEC|, two inputs
- \item |xnor gate IEC|, two inputs
- \item |not gate IEC|, one input
- \item |buffer gate IEC|, one input
- \end{itemize}
-
- Again, we only have a look at the nand-gate in more detail:
-
- \begin{shape}{nand gate IEC}
- This shape is a nand gate. It supports two or more inputs. If less than
- two inputs are specified an error will result. The anchors for this
- gate with two inverted inputs are shown below. Anchor |30| is an
- example of a border anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.logic.IEC}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=nand gate IEC ,shape example, inner xsep=1cm, inner ysep=1cm,
- minimum height=6cm, nand gate IEC symbol=\color{black!30}\char`\&,
- logic gate inputs={in},
- logic gate inverted radius=0.65cm]
- {Nand Gate\vrule width1pt height2cm};
- \foreach \anchor/\placement in
- {center/above, text/above, 30/above right,
- mid/right, mid east/left, mid west/above,
- base/below, base east/below, base west/left,
- north/above, south/below, east/above, west/above,
- north east/above, south east/below, south west/below, north west/above,
- output/right, input 1/above, input 2/below}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- \end{shape}
-\end{pgflibrary}
-
-
-\subsection{Electrical Engineering Circuits}
-
-\subsubsection{Overview}
-
-An \emph{electrical engineering circuit} contains symbols like resistors or
-capacitors or voltage sources and annotations like the two arrows pointing
-toward an element whose behaviour is light dependent. The electrical
-engineering libraries, abbreviated ee-libraries, provide such symbols and
-annotations.
-
-Just as for logical gates, there are different ways of drawing ee-symbols.
-Currently, there is one main library for drawing circuits, which uses the
-graphics from the International Electrotechnical Commission, but you can add
-your own libs. This is why, just as for logical gates, there is a base library
-and more specific libraries.
-
-\begin{tikzlibrary}{circuits.ee}
- This library declares the ee symbols, but (mostly) does not provide the
- symbol graphics, which is left to the sublibraries. Just like the logical
- gates library, a key is defined that is normally only used internally:
- %
- \begin{key}{/tikz/circuit ee}
- This style calls the keys |circuit| (which internally calls
- |every circuit| and the following style:
- %
- \begin{stylekey}{/tikz/every circuit ee}
- Use this key to configure the appearance of logical circuits.
- \end{stylekey}
- \end{key}
-
- The library also declares some standard annotations and units.
-\end{tikzlibrary}
-
-As for logical circuits, to draw a circuit the first step is to include a
-library containing the symbols graphics. Currently, you have to include
-|circuits.ee.IEC|.
-
-\begin{tikzlibrary}{circuits.ee.IEC}
- When this library is loaded, you can use the following style:
- %
- \begin{key}{/tikz/circuit ee IEC}
- This style calls |circuit ee| and installs the IEC-like graphics for
- the logical symbols like |resistor|.
- \end{key}
-\end{tikzlibrary}
-
-Inside the |circuit ee IEC| scope, you can now use the keys for symbols, units,
-and annotations listed in the later sections. We have a more detailed look at
-one of each of them, all the others work the same way.
-
-Let us start with an example of a symbol: the resistor symbol. The other
-predefined symbols are listed in Section~\ref{section-circuits-ee-symbols} and
-later sections.
-
-\begin{key}{/tikz/resistor=\opt{\meta{options}}}
- This key should be used with a |node| path command or with the |to| path
- command.
-
- \medskip\textbf{Using the Key with Normal Nodes.}
- When used with a node, it will cause this node to ``look like'' a resistor
- (by default, in the IEC library, this is just a simple rectangle).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC]
- \node [resistor] {};
-\end{codeexample}
-
- Unlike normal nodes, a resistor node generally should not take any text (as
- in |node [resistor] {foo}|). Instead, the labeling of resistors should be
- done using the |label|, |info| and |ohm| options.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC]
- \node [resistor,ohm=5] {};
-\end{codeexample}
-
- The \meta{options} make no real sense when the |resistor| option is used
- with a normal node, you can just as well given them to the |node| itself.
- Thus, the following has the same effect as the above example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC]
- \node [resistor={ohm=5}] {};
-\end{codeexample}
-
- In a circuit, you will often wish to rotate elements. For this, the options
- |point up|, |point down|, |point left| or |point right| may be especially
- useful. They are just shorthands for appropriate rotations like
- |rotate=90|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC] {
- \node (R1) [resistor,point up,ohm=5] at (3,1) {};
- \node (R2) [resistor,ohm=10k] at (0,0) {};
- \draw (R2) -| (R1);
-}
-\end{codeexample}
-
- \medskip\textbf{Using the Key on a To Path.}
- When the |resistor| key is used on a |to| path inside a |circuit ee IEC|,
- the |circuit handle symbol| key is called internally. This has a whole
- bunch of effects:
- %
- \begin{enumerate}
- \item The path currently being constructed is cut up to make place for
- a node.
- \item This node will be a |resistor node| that is rotated so that it
- points ``along'' the path (unless an option like |shift only| or an
- extra rotation is used to change this).
- \item The \meta{options} passed to the |resistor| key are passed on to
- the node.
- \item The \meta{options} are pre-parsed to identify a |pos| key or a
- key like |at start| or |midway|. These keys are used to determine
- where on the |to| path the node will lie.
- \end{enumerate}
-
- Since the \meta{options} of the |resistor| key are passed on to the
- resistor node on the path, you can use it to add labels to the node. Here
- is a simple example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC]
- \draw (0,0) to [resistor=red] (3,0)
- to [resistor={ohm=2\mu}] (3,2);
-\end{codeexample}
-
- You can add multiple labels to a resistor and you can have multiple
- resistors (or other elements) on a single path.
-
- \medskip\textbf{Inputs, Outputs, and Anchors.}
- Like the logical gates, all ee-symbols have an |input| and an |output|
- anchor. Special-purpose-nodes may have even more anchors of this type.
- Furthermore, the ee-symbols-nodes also have four standard compass direction
- anchors.
-
- \medskip\textbf{Changing the Appearance.}
- To configure the appearance of all |resistor|s, see
- Section~\ref{section-theming-symbols}. You can use the \meta{options} to
- locally change the appearance of a single resistor.
-\end{key}
-
-Let us now have a look at an example of a unit: the Ohm unit. The other
-predefined units are listed in Section~\ref{section-circuits-units}.
-
-\begin{key}{/tikz/ohm=\meta{value}}
- This key is used to add an |info| label to a node with a special text:
- |$\mathrm{|\meta{value}|\Omega}$|. In other words, the |ohm| key can only
- be used with the options of a node and, when used, it will cause the
- \meta{value} to be placed next to the node, followed by $\Omega$. Since the
- \meta{value} is typeset inside a |\mathrm| command, when you write |ohm=5k|
- you get $\mathrm{5k\Omega}$, |ohm=5p| yields $\mathrm{5p\Omega}$, and
- |ohm=5.6\cdot 10^{2}\mu| yields $\mathrm{5.6\cdot 10^{2}\mu\Omega}$.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC] \draw (0,0) to [resistor={ohm=5M}] (0,2);
-\end{codeexample}
-
- Instead of |ohm| you can also use |ohm'|, which places the label on the
- other side.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC] \draw (0,0) to [resistor={ohm'=5M}] (0,2);
-\end{codeexample}
-
- Finally, there are also keys |ohm sloped| and |ohm' sloped| for having the
- info label rotate together with the main node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC]
- \draw (0,0) to [resistor={ohm sloped=5M}] (0,2)
- (2,0) to [resistor={ohm' sloped=6f}] (2,2);
-\end{codeexample}
-
- You can configure the appearance of an Ohm info label using the key
- |every ohm|.
-\end{key}
-
-Finally, let us have a look at an annotation: the |light emitting| annotation.
-The other predefined units are listed in
-Section~\ref{section-circuits-annotations}.
-
-\begin{key}{/tikz/light emitting=\opt{\meta{options}}}
- Like a unit, an annotation should be given as an additional option to a
- node. It causes some drawings (in this case, two parallel lines) to be
- placed next to the node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC] \draw (0,0) to [diode=light emitting] (2,0);
-\end{codeexample}
-
- The \meta{options} can be used for three different things:
- %
- \begin{enumerate}
- \item You can use keys like |red| to change the appearance of this
- annotation, locally.
- \item You can use keys like |<-| or |-latex| to change the direction
- and kinds of arrows used in the annotation.
- \item You can use info labels like |ohm=5| or |info=foo| inside the
- \meta{options}. These info labels will be added to the main node
- (not to the annotation itself), but the label distance will have
- been changed to accommodate for the space taken up by the
- annotation.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz [circuit ee IEC]
-{
- \draw (0,2) to [diode={light emitting,info=not good}] (2,2);
- \draw (0,0) to [diode={light emitting={info=better},
- info'=also good}] (2,0);
-}
-\end{codeexample}
- \end{enumerate}
-
- In addition to |light emitting| there is also a key called
- |light emitting'|, which simply places the annotation on the other side of
- the node.
-
- You can configure the appearance of annotations in three ways:
- %
- \begin{itemize}
- \item You can set the |every circuit annotation| style.
- \item You can set the |every light emitting| style.
- \item You can set the following key:
- %
- \begin{stylekey}{/tikz/annotation arrow}
- This style should set the default |>| arrow to some nice value.
- \end{stylekey}
- \end{itemize}
-\end{key}
-
-\def\eelineexample#1#2{%
- \texttt{#1}\indexkey{#1}
- &
- \tikz[baseline=-.5ex,circuit ee IEC] \draw (0,0) to [#1] (3,0);
- &
- \relax\def\temp{#2}
- \ifx\temp\empty\else
- {\tikz[baseline=-.5ex,circuit ee IEC,set #2 graphic=var #2 IEC graphic]
- \draw (0,0) to [#2] (3,0);}
- \fi \\[.2em]
-}
-\def\eeendexample#1#2{%
- \texttt{#1}\indexkey{#1}
- &
- \tikz[baseline=-.5ex,circuit ee IEC] \draw (0,0) to [#1={at end}] (1.5,0)(3,0);
- &
- \relax\def\temp{#2}
- \ifx\temp\empty\else
- {\tikz[baseline=-.5ex,circuit ee IEC,set #2 graphic=var #2 IEC graphic]
- \draw (0,0) to [#2={at end}] (1.5,0)(3,0);}
- \fi \\[.2em]
-}
-\def\unitexample#1{%
- \texttt{#1}\indexkey{#1}
- &
- \tikz [baseline,inner sep=0pt] \node[#1=1] {};\\
-}
-\def\annotationexample#1{%
- \texttt{#1}\indexkey{#1}
- &
- \tikz[baseline=-.5ex,circuit ee IEC]
- \draw (0,0) to [resistor={#1}] (2,0)
- to [diode ={#1'}] (4,0);\\
-}
-\def\empty{}
-
-
-\subsubsection{Symbols: Indicating Current Directions}
-\label{section-ee-symbols}
-\label{section-circuits-ee-symbols}
-
-There \todosp{why two labels? The first doesn't seem to be used.} are two
-symbols for indicating current directions. These symbols are defined directly
-inside |circuit ee|.
-\medskip
-
-\noindent
-\begin{tabular}{p{5cm}ll}
- \emph{Key} & \emph{Appearance}\\[.25em]
- \eelineexample{/tikz/current direction}{}
- \eelineexample{/tikz/current direction'}{}
-\end{tabular}
-
-\medskip
-The examples have been produced by (in essence)
-|\draw (0,0) to[|\meta{symbol name}|] (3,0);|.
-
-
-\subsubsection{Symbols: Basic Elements}
-
-The following table show basic symbols as they are depicted inside the
-|circuit ee IEC| environment. To install one of alternate graphics, you have to
-say |set| \meta{symbol name} |graphic=var| \meta{symbol name} |IEC graphic|.
-\medskip
-
-\noindent
-\begin{tabular}{p{5cm}ll}
- \emph{Key} & \emph{Appearance} & \emph{Alternate appearance} \\[.25em]
- \eelineexample{/tikz/resistor}{resistor}
- \eelineexample{/tikz/inductor}{inductor}
- \eelineexample{/tikz/capacitor}{}
- \eelineexample{/tikz/battery}{}
- \eelineexample{/tikz/bulb}{}
- \eelineexample{/tikz/current source}{}
- \eelineexample{/tikz/voltage source}{}
- \eelineexample{/tikz/ac source}{}
- \eelineexample{/tikz/dc source}{}
- \eeendexample{/tikz/ground}{}
-\end{tabular}
-
-
-\subsubsection{Symbols: Diodes}
-
-The following table shows diodes as they are depicted inside the
-|circuit ee IEC| environment.
-\medskip
-
-\noindent
-\begin{tabular}{p{5cm}ll}
- \emph{Key} & \emph{Appearance} & \emph{Alternate appearance} \\[.25em]
- \eelineexample{/tikz/diode}{diode}
- \eelineexample{/tikz/Zener diode}{Zener diode}
- \eelineexample{/tikz/Schottky diode}{Schottky diode}
- \eelineexample{/tikz/tunnel diode}{tunnel diode}
- \eelineexample{/tikz/backward diode}{backward diode}
- \eelineexample{/tikz/breakdown diode}{breakdown diode}
-\end{tabular}
-
-
-\subsubsection{Symbols: Contacts}
-
-The following table shows contacts as they are depicted inside the
-|circuit ee IEC| environment.
-\medskip
-
-\noindent
-\begin{tabular}{p{5cm}ll}
- \emph{Key} & \emph{Appearance} & \emph{Alternate appearance} \\[.25em]
- \eelineexample{/tikz/contact}{}
- \eelineexample{/tikz/make contact}{make contact}
- \eelineexample{/tikz/break contact}{}
-\end{tabular}
-
-
-\subsubsection{Symbols: Measurement devices}
-
-The following table shows measurement devices as they are depicted inside the
-|circuit ee IEC| environment.
-\medskip
-
-\noindent
-\begin{tabular}{p{5cm}ll}
- \emph{Key} & \emph{Appearance} \\[.25em]
- \eelineexample{/tikz/amperemeter}{}
- \eelineexample{/tikz/voltmeter}{}
- \eelineexample{/tikz/ohmmeter}{}
-\end{tabular}
-
-
-\subsubsection{Units}
-\label{section-circuits-units}
-
-The |circuits.ee| library predefines the following unit keys:
-\medskip
-
-\noindent
-\begin{tabular}{p{5cm}c}
- \emph{Key} & \emph{Appearance of $1$ unit} \\[.25em]
- \unitexample{/tikz/ampere}
- \unitexample{/tikz/volt}
- \unitexample{/tikz/ohm}
- \unitexample{/tikz/siemens}
- \unitexample{/tikz/henry}
- \unitexample{/tikz/farad}
- \unitexample{/tikz/coulomb}
- \unitexample{/tikz/voltampere}
- \unitexample{/tikz/watt}
- \unitexample{/tikz/hertz}
-\end{tabular}
-
-
-\subsubsection{Annotations}
-\label{section-circuits-annotations}
-
-The |circuits.ee.IEC| library defines the following annotations:
-\medskip
-
-\noindent
-\begin{tabular}{p{5cm}ll}
- \emph{Key} & \emph{Appearance} \\[.25em]
- \annotationexample{/tikz/light emitting}
- \annotationexample{/tikz/light dependent}
- \annotationexample{/tikz/direction info}
- \annotationexample{/tikz/adjustable}
-\end{tabular}
-\medskip
-
-The lines have been produced using, in essence,
-%
-\begin{codeexample}[code only]
-\draw (0,0) to [resistor=light emitting] (2,0) to [diode=light emitting'] (4,0);
-\end{codeexample}
-%
-and similarly for the other annotations.
-
-
-\subsubsection{Implementation: The EE-Symbols Shape Library}
-
-The \tikzname\ libraries depend on two shape libraries, which are included
-automatically. Usually, you will not need to use these shapes directly.
-
-\begin{pgflibrary}{shapes.gates.ee}
- This library defines basic shapes that can be used by all ee-circuit
- libraries. Currently, it defines the following shapes:
- %
- \begin{itemize}
- \item |rectangle ee|
- \item |circle ee|
- \item |direction ee|
- \end{itemize}
- %
- Additionally, the library defines the following arrow tip: The
- |direction ee| arrow tip is basically the same as a |triangle 45| arrow tip
- with rounded joins.
-
- \begin{tabular}{ll}
- \symarrow{direction ee}
- \end{tabular}
-
- However, unlike normal arrow tips, its size does \emph{not} depend on the
- current line width. Rather, it depends on the value of its arrow options,
- which should be set to the desired size. Thus, you should say something
- like |\pgfsetarrowoptions{direction ee}{5pt}| to set the size of the arrow.
-\end{pgflibrary}
-
-\begin{shape}{rectangle ee}
- This shape is completely identical to a normal |rectangle|, only there are
- two additional anchors: The |input| anchor is an alias for the |west|
- anchor, while the |output| anchor is an alias for the |east| anchor.
-\end{shape}
-
-\begin{shape}{circle ee}
- Like the |rectangle ee| shape, only for circles.
-\end{shape}
-
-\begin{shape}{direction ee}
- This shape is rather special. It is intended to be used to ``turn an arrow
- tip into a shape''. First, you should set the following key to the name of
- an arrow tip:
- %
- \begin{key}{/pgf/direction ee arrow=\meta{right arrow tip name}}
- The value of this key will be used for the arrow tip depicted in an
- |direction ee| shape.
- \end{key}
- %
- When a node of shape |direction ee| is created, several things happen:
- %
- \begin{enumerate}
- \item The size of the shape is computed according to the following
- rules: The width of the shape is set up so that the left border of
- the shape is at the left end of the arrow tip and the right border
- is at the right end of the arrow tip. These left and right ``ends''
- of the arrow are the tip end and the back end specified by the
- arrow itself (see Section~\ref{section-arrow-terminology} for
- details). You usually need not worry about this width setting.
-
- By comparison, the height of the arrow is given by the current
- setting of |minimum height|. Thus, this key must have been set up
- correctly to reflect the ``real'' height of the arrow tip. The
- reason is that the height of an arrow is not specified when arrows
- are declared and is, thus, not available, here.
-
- Possibly, the height computation will change in the future to
- reflect the real height of the arrow, so you should generally set
- up the |minimum height| to be the same as the real height.
- \item A straight line from left to right inside the shape's boundaries
- is added to the background path.
- \item The arrow tip, pointing right, is drawn before the background
- path.
- \end{enumerate}
- %
- The anchors of this shape are just the compass anchors, which lie on a
- rectangle whose width and height are the above-computed height and width.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}
- \pgfsetarrowoptions{direction ee}{6cm}
- \node[name=s,shape=direction ee,shape example,minimum height=0.7654*6cm] {};
- \foreach \anchor/\placement in
- {center/above, 30/above right,
- north/above, south/below, east/left, west/right,
- north east/above, south east/below, south west/below, north west/above,
- input/left,output/right}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}[direction ee arrow=angle 45]
- \node[name=s,shape=direction ee,shape example,minimum height=1.75cm] {};
- \foreach \anchor/\placement in {north/above, south/below,
- output/right, input/left}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-
-\subsubsection{Implementation: The IEC-Style EE-Symbols Shape Library}
-
-\begin{pgflibrary}{shapes.gates.ee.IEC}
- This library defines shapes for depicting ee symbols according to the IEC
- recommendations. These shapes will typically be used in conjunction with
- the graphic mechanism detailed earlier, but you can also used them
- directly.
-\end{pgflibrary}
-
-\begin{shape}{generic circle IEC}
- This shape inherits from |circle ee|, which in turn is just a normal
- |circle| with additional |input| and |output| anchors at the left and right
- ends. However, additionally, this shape allows you to specify a path that
- should be added before the background path using the following key:
- %
- \begin{key}{/pgf/generic circle IEC/before background=\meta{code}}
- When a node of shape |generic circle IEC| is created, the current
- setting of this key is used as the ``before background path''. This
- means that after the circle's background has been
- drawn/filled/whatever, the \meta{code} is executed.
-
- When the \meta{code} is executed, the coordinate system will have been
- transformed in such a way that the point $(1\mathrm{pt},0\mathrm{pt})$
- lies at the right end of the circle and $(0\mathrm{pt},1\mathrm{pt})$
- lies at the top of the circle. (More precisely, these points will lie
- exactly on the middle of the radial line.)
- \end{key}
- %
- Here is an examples of how to use this shape:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz \node [generic circle IEC,
- /pgf/generic circle IEC/before background={
- \pgfpathmoveto{\pgfpointorigin}
- \pgfpathlineto{\pgfpoint{1pt}{0pt}}
- \pgfpathlineto{\pgfpoint{0pt}{1pt}}
- \pgfpathlineto{\pgfpoint{-0.5pt}{-0.5pt}}
- \pgfusepathqstroke
- },
- draw] {Hello world};
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{generic diode IEC}
- This shape is used to depict diodes. The main shape is taken up by a
- ``right pointing'' triangle. The anchors are positioned on the border of a
- rectangle around the diode, see the below example. The diode's size is
- based on the current settings of |minimum width| and |minimum height|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}
- \node[name=s,shape=generic diode IEC,shape example,minimum size=6cm] {};
- \foreach \anchor/\placement in
- {center/above, 30/above right,
- north/above, south/below, east/left, west/right,
- north east/above, south east/below, south west/below, north west/above,
- input/left,output/right}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
-
- This shape, like the |generic circle IEC| shape, is generic in the sense
- that there is a special key that is used for the before background
- drawings:
- %
- \begin{key}{/pgf/generic diode IEC/before background=\meta{code}}
- Similarly to the |generic circle IEC| shape, when a node of shape
- |generic diode IEC| is created, the current setting of this key is used
- as the ``before background path''. When the \meta{code} is executed,
- the coordinate system will have been transformed in such a way that the
- origin is at the ``tip'' of the diode's triangle, the point
- $(0\mathrm{pt},1\mathrm{pt})$ is exactly half the diode's height above
- this origin, and the point $(1\mathrm{pt},0\mathrm{pt})$ is half the
- diode's height to the right of the origin.
-
- The idea is that you use this key to draw different kinds of diode
- endings.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz \node [minimum size=1cm,generic diode IEC,
- /pgf/generic diode IEC/before background={
- \pgfpathmoveto{\pgfqpoint{-.5pt}{-1pt}}
- \pgfpathlineto{\pgfqpoint{.5pt}{-1pt}}
- \pgfpathmoveto{\pgfqpoint{0pt}{-1pt}}
- \pgfpathlineto{\pgfqpoint{0pt}{1pt}}
- \pgfpathmoveto{\pgfqpoint{-.5pt}{1pt}}
- \pgfpathlineto{\pgfqpoint{.5pt}{1pt}}
- \pgfusepathqstroke
- },
- draw] {};
-\end{codeexample}
- \end{key}
-\end{shape}
-
-\begin{shape}{breakdown diode IEC}
- This shape is used to depict a bidirectional breakdown diode. The diode's
- size is based on the current settings of |minimum width| and
- |minimum height|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}
- \node[name=s,shape=breakdown diode IEC,shape example,minimum width=6cm,minimum height=4cm] {};
- \foreach \anchor/\placement in
- {center/above, 30/above right,
- north/above, south/below, east/left, west/right,
- north east/above, south east/below, south west/below, north west/above,
- input/left,output/right}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{var resistor IEC}
- This shape is used to depict a variant version of a resistor. Its size is
- computed as for a rectangle (thus, its size depends things like the
- |minimum height|). Then, inside this rectangle, a background path is set up
- according to the following rule: Starting from the left end, zigzag
- segments are added to the path. Each segment consists of a line at a 45
- degree angle going up to the top of the rectangle, then going down to the
- bottom, then going up to mid height of the node. As many segments as
- possible are put inside as possible. The last segment is then connected to
- the output anchor via a straight line.
-
- All of this means that, in general, the shape should be much wider than
- high.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}
- \node[name=s,shape=var resistor IEC,shape example,minimum width=7cm,minimum height=1cm] {};
- \foreach \anchor/\placement in
- {center/above, 30/above right,
- north/above, south/below, east/left, west/right,
- north east/above, south east/below, south west/below, north west/above,
- input/left,output/right}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{inductor IEC}
- This shape is used to depict an inductor, using a bumpy line. Its size is
- computed as follows: Any text and |inner sep| are ignored (and should
- normally not be given). The |minimum height| plus (twice) the |outer ysep|
- specify the distance between the |north| and |south| anchors, similarly for
- the |minimum width| plus the |outer xsep| for the |east| and |west|. The
- bumpy line is drawn starting from the lower left corner to the lower right
- corner with bumps being half-circles whose height is exactly the
- |minimum height|. The |center| of the shape is just above the |south|
- anchor, at a distance of the |outer ysep|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}
- \node[name=s,shape=inductor IEC,shape example,minimum width=7cm,minimum height=1cm] {};
- \foreach \anchor/\placement in
- {center/above, 30/above right,
- north/above, south/below, east/left, west/right,
- north east/above, south east/below, south west/below, north west/above,
- input/left,output/right}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
- Just as for a |var resistor IEC|, as many bumps as possible are added and
- the last bump is connected to the output anchor via a straight line.
-\end{shape}
-
-\begin{shape}{capacitor IEC}
- This shape is based on a |rectangle ee|. However, instead of a rectangle as
- the background path, only the ``left and right lines'' that make up the
- rectangle are drawn.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}
- \node[name=s,shape=capacitor IEC,shape example,
- minimum width=2cm,minimum height=3cm,inner sep=0pt] {};
- \foreach \anchor/\placement in
- {center/above, 30/above right,
- north/above, south/below, east/left, west/right,
- north east/above, south east/below, south west/below, north west/above,
- input/left,output/right}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{battery IEC}
- This shape is similar to a |capacitor IEC|, however, the right line is only
- half the height of the left line.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz \node[shape=battery IEC,shape example,minimum size=2cm,
- inner sep=0pt] {};
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{ground IEC}
- This shape is similar to a |batter IEC|, only three lines of different
- heights are drawn.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz \node[shape=ground IEC,shape example,minimum size=2cm,
- inner sep=0pt] {};
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{make contact IEC}
- This shape consists of a line going from the lower left corner to the upper
- right corner. The size and anchors of this shape are computed in the same
- way as for an |inductor IEC|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\begin{tikzpicture}
- \node[name=s,shape=make contact IEC,shape example,minimum width=3cm,minimum height=1cm] {};
- \foreach \anchor/\placement in
- {center/above, 30/above right,
- north/above, south/below, east/left, west/right,
- north east/above, south east/below, south west/below, north west/above,
- input/left,output/right}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{var make contact IEC}
- This shape works like |make contact IEC|, only a little circle is added to
- the path at the lower left corner. The radius of this circle is one twelfth
- of the width of the node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz \node[shape=var make contact IEC,shape example,
- minimum height=1cm,minimum width=3cm,inner sep=0pt] {};
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{break contact IEC}
- This shape depicts a contact that can be broken. It works like
- |make contact IEC|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{circuits.ee.IEC}}]
-\tikz \node[shape=break contact IEC,shape example,
- minimum height=1cm,minimum width=3cm,inner sep=0pt] {};
-\end{codeexample}
- %
-\end{shape}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-decorations.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-decorations.tex
deleted file mode 100644
index df6960e672..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-decorations.tex
+++ /dev/null
@@ -1,2180 +0,0 @@
-% Copyright 2019 by Mark Wibrow and 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{Decoration Library}
-\label{section-library-decorations}
-
-
-\subsection{Overview and Common Options}
-
-The decoration libraries define a number of (more or less useful) decorations
-that can be applied to paths. The usage of decorations is not covered in the
-present section, please consult Sections~\ref{section-tikz-decorations}, which
-explains how decorations are used in \tikzname, and
-\ref{section-base-decorations}, which explains how new decorations can be
-defined.
-
-The decorations are influenced by a number of parameters that can be set using
-the |decoration| option. These parameters are typically shared between
-different decorations. In the following, the general options are documented
-(they are defined directly in the |decoration| module), special-purpose keys
-are documented with the decoration that uses it.
-
-Since you are encouraged to use these keys to make your own decorations
-configurable, it is indicated for each key where the value is stored (so that
-you can access it). Note that some values are stored in \TeX\ dimension
-registers while others are stored in macros.
-
-\begin{key}{/pgf/decoration/amplitude=\meta{dimension} (initially 2.5pt)}
- This key determines the ``desired height'' (or amplitude) of decorations
- for which this makes sense. For instance, the initial value of |2.5pt|
- means that deforming decorations should deform a path by up to 2.5pt away
- from the original path.
-
- This key sets the \TeX-dimension |\pgfdecorationsegmentamplitude|.
-\end{key}
-
-\begin{key}{/pgf/decoration/meta-amplitude=\meta{dimension} (initially 2.5pt)}
- This key determines the amplitude for a meta-decoration.
-
- The key sets the \TeX-macro (!) |\pgfmetadecorationsegmentamplitude|.
-\end{key}
-
-\begin{key}{/pgf/decoration/segment length=\meta{dimension} (initially 10pt)}
- Many decorations are made up of small segments. This key determines the
- desired length of such segments.
-
- This key sets the \TeX-dimension |\pgfdecorationsegmentlength|.
-\end{key}
-
-\begin{key}{/pgf/decoration/meta-segment length=\meta{dimension} (initially 1cm)}
- This determined the length of the meta-segments from which a
- meta-decoration is made up.
-
- This key sets the \TeX-macro (!) |\pgfmetadecorationsegmentlength|.
-\end{key}
-
-\begin{key}{/pgf/decoration/angle=\meta{degree} (initially 45)}
- The way some decorations look like depends on a configurable angle. For
- instance, a |wave| decoration consists of arcs and the opening angle of
- these arcs is given by the |angle|.
-
- This key sets the \TeX-macro |\pgfdecorationsegmentangle|.
-\end{key}
-
-\begin{key}{/pgf/decoration/aspect=\meta{factor} (initially 0.5)}
- For some decorations there is a natural aspect ratio. For instance,
- for a |brace| decoration the aspect ratio determines where the brace
- point will be.
-
- This key sets the \TeX-macro |\pgfdecorationsegmentaspect|.
-\end{key}
-
-\begin{key}{/pgf/decoration/start radius=\meta{dimension} (initially 2.5pt)}
- For some decorations there is a natural start radius (of some circle,
- presumably).
-
- This key stores the value directly inside the key.
-\end{key}
-
-\begin{key}{/pgf/decoration/end radius=\meta{dimension} (initially 2.5pt)}
- For some decorations there is a natural end radius (of some circle,
- presumably).
-
- This key stores the value directly inside the key.
-\end{key}
-
-\begin{stylekey}{/pgf/decoration/radius=\meta{dimension}}
- Sets the start and end radius simultaneously.
-\end{stylekey}
-
-\begin{key}{/pgf/decoration/path has corners=\meta{boolean} (initially false)}
- This is a hint to the decoration code as to whether the path has corners or
- not. If a path has a sharp corner, setting this option to |true| may result
- in better rendering of the decoration because the joins of input segments
- are approached ``more carefully'' than when this key is set to false.
- However, if the path is, say, a smooth circle, setting this key to |true|
- will usually look worse. Most decorations ignore this key, anyway.
- Internally, it sets the \TeX-if |\ifpgfdecoratepathhascorners|.
-\end{key}
-
-
-\subsection{Handling ``Dimension too large'' errors}
-
-In case you should run into a ``Dimension too large error'' when using the
-|decorations| libraries, there is a pretty high chance that you can resolve
-this by using the |fpu| library in combination with
-|/pgf/fpu/install only={reciprocal}|. Please note that this key should only be
-applied locally to avoid other errors (see also at the definition of this key
-on page~\pageref{fpu-install-only}).
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings,fpu}}]
-\begin{tikzpicture}
- \begin{scope}[/pgf/fpu/install only={reciprocal}]
- \draw[postaction=decorate,decoration={
- markings,mark=at position 0.52 with {
- \draw circle[radius=2pt];
- }},
- ] plot[smooth,variable=\x,domain=-1:1] (\x*\x*\x,\x*\x);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Path Morphing Decorations}
-
-\begin{pgflibrary}{decorations.pathmorphing}
- A \emph{path morphing decoration} ``morphs'' or ``deforms'' the
- to-be-decorated path. This means that what used to be a straight line might
- afterwards be a snaking curve and have bumps. However, a line is still a
- line and path deforming decorations do not change the number of subpaths.
- For instance, if the path used to consist of two circles and an open arc,
- the path will, after the decoration process, still consist of two closed
- subpaths and one open subpath.
-\end{pgflibrary}
-
-
-\subsubsection{Decorations Producing Straight Line Paths}
-
-The following deformations use only straight lines in order to morph the paths.
-
-\begin{decoration}{lineto}
- This decoration replaces the path by straight lines. For each curve, the
- path simply goes directly from the start point to the end point. In the
- following example, the arc actually consist of two subcurves.
-
- This decoration is actually always defined when the decoration module is
- loaded, but it is documented here for consistency.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations}}]
-\begin{tikzpicture}[decoration=lineto]
- \draw [help lines] grid (3,2);
- \draw [decorate,fill=yellow!80!black]
- (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{straight zigzag}
- This (meta-)decoration decorates the path by alternating between |curveto|
- and |zigzag| decorations. It always finishes with the |curveto| decoration.
- The following parameters influence the decoration:
- %
- \begin{itemize}
- \item |amplitude| determines how much the zigzag line raises above and
- falls below a straight line to the target point.
- \item |segment length| determines the length of a complete ``up-down''
- cycle.
- \item |meta-segment length| determines the length of the |curveto| and the
- |zigzag| decorations.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}[decoration={straight zigzag,meta-segment length=1.1cm}]
- \draw [help lines] grid (3,2);
- \draw [decorate,fill=yellow!80!black]
- (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{random steps}
- This decoration consists of straight line segments. The line segments head
- towards the target, but each step is randomly shifted a little bit. The
- following parameters influence the decorations:
- %
- \begin{itemize}
- \item |segment length| determines the basic length of each step.
- \item |amplitude| The end of each step is perturbed both in $x$- and in
- $y$-direction by two values drawn uniformly from the interval
- $[-d,d]$, where $d$ is the value of |amplitude|.
- \end{itemize}
- %
-\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- [decoration={random steps,segment length=2mm}]
- \draw [help lines] grid (3,2);
- \draw [decorate,fill=yellow!80!black]
- (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{saw}
- This decoration looks like the blade of a saw. The following parameters
- influence the decoration:
- %
- \begin{itemize}
- \item |amplitude| determines how much each spike raises above the
- straight line.
- \item |segment length| determines the length each spike.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}[decoration=saw]
- \draw [help lines] grid (3,2);
- \draw [decorate,fill=yellow!80!black]
- (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{zigzag}
- This decoration looks like a zigzag line. The following parameters
- influence the decoration:
- %
- \begin{itemize}
- \item |amplitude| determines how much the zigzag line raises above and
- falls below a straight line to the target point.
- \item |segment length| determines the length of a complete ``up-down''
- cycle.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}[decoration=zigzag]
- \draw [help lines] grid (3,2);
- \draw [decorate,fill=yellow!80!black]
- (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-
-\subsubsection{Decorations Producing Curved Line Paths}
-
-\begin{decoration}{bent}
- This decoration adds a slightly bent line from the start to the target. The
- amplitude of the bend is given |amplitude| (an amplitude of zero gives a
- straight line).
- %
- \begin{itemize}
- \item |amplitude| determines the amplitude of the bend.
- \item |aspect| determines how tight the bend is. A good value is around
- |0.3|.
- \end{itemize}
- %
- Note that this decoration makes only little sense for curves. You should
- apply it only to straight lines.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}[decoration=bent]
- \draw [help lines] grid (3,2);
- \draw [decorate] (0,0) -- (3,1) -- (1.5,2) -- (0,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}[decoration={bent,aspect=.3}]
- \draw [decorate,fill=yellow!80!black] (0,0) rectangle (3.5,2);
- \node[circle,draw] (A) at (.5,.5) {A};
- \node[circle,draw] (B) at (3,1.5) {B};
- \draw[->,decorate] (A) -- (B);
- \draw[->,decorate] (B) -- (A);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{bumps}
- This decoration replaces the path by little half ellipses. The following
- parameters influence it.
- %
- \begin{itemize}
- \item |amplitude| determines the height of the half ellipse.
- \item |segment length| determines the width of the half ellipse.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}[decoration=bumps]
- \draw [help lines] grid (3,2);
- \draw [decorate,fill=yellow!80!black]
- (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{coil}
- This decoration replaces the path by a coiled line. To understand how this
- works, imagine a three-dimensional spring. The spring's axis points along
- the path toward the target. Then, we ``view'' the spring from a certain
- angle. If we look ``straight from the side'' we will see a perfect sine
- curve, if we look ``more from the front'' we will see a coil. The following
- parameters influence the decoration:
- %
- \begin{itemize}
- \item |amplitude| determines how much the coil rises above the path and
- falls below it. Thus, this is the radius of the coil.
- \item |segment length| determines the distance between two consecutive
- ``curls''. Thus, when the spring is see ``from the side'' this will
- be the wave length of the sine curve.
- \item |aspect| determines the ``viewing direction''. A value of |0|
- means ``looking from the side'' and a value of |0.5|, which is the
- default, means ``look more from the front''.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}[decoration=coil]
- \draw [help lines] grid (3,2);
- \draw [decorate,fill=yellow!80!black]
- (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- [decoration={coil,aspect=0.3,segment length=3mm,amplitude=3mm}]
- \draw [help lines] grid (3,2);
- \draw [decorate,fill=yellow!80!black]
- (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{curveto}
- This decoration simply yields a line following the original path. This
- means that (ideally) it does not change the path and follows any curves in
- the path (hence the name). In reality, due to the internals of how
- decorations are implemented, this decoration actually replaces the path by
- numerous small straight lines.
-
- This decoration is mostly useful in conjunction with meta-decorations. It
- is also actually defined in the decoration module and is always available.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}[decoration=curveto]
- \draw [help lines] grid (3,2);
- \draw [decorate,fill=yellow!80!black]
- (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{snake}
- This decoration replaces the path by a line that looks like a snake seen
- from above. More precisely, the snake is a sine wave with a ``softened''
- start and ending. The following parameters influence the snake:
- %
- \begin{itemize}
- \item |amplitude| determines the sine wave's amplitude.
- \item |segment length| determines the sine wave's wavelength.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}[decoration=snake]
- \draw [help lines] grid (3,2);
- \draw [decorate,fill=yellow!80!black]
- (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-
-\subsection{Path Replacing Decorations}
-
-\begin{pgflibrary}{decorations.pathreplacing}
- This library defines decorations that replace the to-be-decorated path by
- another path. Unlike morphing decorations, the replaced path might be quite
- different, for instance a straight line might be replaced by a set of
- circles. Note that filling a path that has been replaced using one of the
- decorations in this library typically does not fill the original area but,
- rather, the smaller area of the newly-created path segments.
-\end{pgflibrary}
-
-\begin{decoration}{border}
- This decoration adds straight lines to the path that are at a specific
- angle to the line toward the target. The idea is to add these little lines
- to indicate the ``border'' of an area. The following parameters influence
- the decoration:
- %
- \begin{itemize}
- \item |segment length| determines the distance between consecutive
- ticks.
- \item |amplitude| determines the length of the ticks.
- \item |angle| determines the angle between the ticks and the line of
- the path.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
-\begin{tikzpicture}[decoration=border]
- \draw [help lines] grid (3,2);
- \draw [postaction={decorate,draw,red}]
- (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{brace}
- This decoration replaces a straight line path by a long brace. The left and
- right end of the brace will be exactly on the start and endpoint of the
- decoration. The decoration really only makes sense for paths that are a
- straight line.
- %
- \begin{itemize}
- \item |amplitude| determines how much the brace rises above the path.
- \item |aspect| determines the fraction of the total length where the
- ``middle part'' of the brace will be.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
-\begin{tikzpicture}[decoration=brace]
- \draw [help lines] grid (3,2);
- \draw [decorate] (0,0) -- (3,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{expanding waves}
- This decoration adds arcs to the path that get bigger along the line
- towards the target. The following parameters influence the decoration:
- %
- \begin{itemize}
- \item |segment length| determines the distance between consecutive
- arcs.
- \item |angle| determines the opening angle below and above the path.
- Thus, the total opening angle is twice this angle.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
-\begin{tikzpicture}[decoration={expanding waves,angle=5}]
- \draw [help lines] grid (3,2);
- \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{moveto}
- This decoration simply jumps to the end of the path using a move-to path
- operation. It is mainly useful as |pre=moveto| or |post=moveto|
- decorations.
-
- This decoration is actually always defined when the decoration module is
- loaded, but it is documented here for consistency.
-\end{decoration}
-
-\begin{decoration}{ticks}
- This decoration replaces the path by straight lines that are orthogonal to
- the path. The following parameters influence the decoration:
- %
- \begin{itemize}
- \item |segment length| determines the distance between consecutive
- ticks.
- \item |amplitude| determines half the length of the ticks.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
-\begin{tikzpicture}[decoration=ticks]
- \draw [help lines] grid (3,2);
- \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{waves}
- This decoration replaces the path by arcs that have a constant size. The
- following parameters influence the decoration:
- %
- \begin{itemize}
- \item |segment length| determines the distance between consecutive
- arcs.
- \item |angle| determines the opening angle below and above the path.
- Thus, the total opening angle is twice this angle.
- \item |radius| determines the radius of each arc.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
-\begin{tikzpicture}[decoration={waves,radius=4mm}]
- \draw [help lines] grid (3,2);
- \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{show path construction}
- This decoration allows ``something different'' to be done for each
- \emph{type} of input segment (i.e., moveto, lineto, curveto or closepath).
- Typically, each segment will be replaced with another path, but this need
- not necessarily be the case.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
-\begin{tikzpicture}[>=stealth, every node/.style={midway, sloped, font=\tiny},
- decoration={show path construction,
- moveto code={
- \fill [red] (\tikzinputsegmentfirst) circle (2pt)
- node [fill=none, below] {moveto};},
- lineto code={
- \draw [blue,->] (\tikzinputsegmentfirst) -- (\tikzinputsegmentlast)
- node [above] {lineto};
- },
- curveto code={
- \draw [green!75!black,->] (\tikzinputsegmentfirst) .. controls
- (\tikzinputsegmentsupporta) and (\tikzinputsegmentsupportb)
- ..(\tikzinputsegmentlast) node [above] {curveto};
- },
- closepath code={
- \draw [orange,->] (\tikzinputsegmentfirst) -- (\tikzinputsegmentlast)
- node [above] {closepath};}
- }]
- \draw [help lines] grid (3,2);
- \path [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
-
- The following keys can be used to specify the code to execute for each type
- of input segment.
-
- \begin{key}{/pgf/decoration/moveto code=\meta{code} (initially \char`\{\char`\})}
- Set the code to be executed for every moveto input segment. It is
- important to remember that the transformations applied by the
- decoration automaton are turned \emph{off} when \meta{code} is
- executed.
- \end{key}
-
- \begin{key}{/pgf/decoration/lineto code=\meta{code} (initially \char`\{\char`\})}
- Set the code to be executed for every lineto input segment.
- \end{key}
-
- \begin{key}{/pgf/decoration/curveto code=\meta{code} (initially \char`\{\char`\})}
- Set the code to be executed for every curveto input segment.
- \end{key}
-
- \begin{key}{/pgf/decoration/closepath code=\meta{code} (initially \char`\{\char`\})}
- Set the code to be executed for every closepath input segment.
- \end{key}
-
- Within \meta{code} the first and last points on the current input segment
- can be accessed using |\pgfpointdecoratedinputsegmentfirst| and
- |\pgfpointdecoratedinputsegmentlast|. For curves, the control (support)
- points can be accessed using |\pgfpointdecoratedinputsegmentsupporta| and
- |\pgfpointdecoratedinputsegmentsupportb|.
-
- In \tikzname, you can use the following macros inside a \tikzname{}
- coordinate.
-
- \begin{command}{\tikzinputsegmentfirst}
- The first point on the current input segment path.
- \end{command}
-
- \begin{command}{\tikzinputsegmentlast}
- The last point on the current input segment path.
- \end{command}
-
- \begin{command}{\tikzinputsegmentsupporta}
- The first support on the curveto input segment path.
- \end{command}
-
- \begin{command}{\tikzinputsegmentsupportb}
- The second support on the curveto input segment path.
- \end{command}
- %
-{\ifpgfmanualexternalize\tikzexternaldisable\fi
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing,shapes.misc}}]
-\tikzset{
- show curve controls/.style={
- decoration={
- show path construction,
- curveto code={
- \draw [blue, dashed]
- (\tikzinputsegmentfirst) -- (\tikzinputsegmentsupporta)
- node [at end, cross out, draw, solid, red, inner sep=2pt]{};
- \draw [blue, dashed]
- (\tikzinputsegmentsupportb) -- (\tikzinputsegmentlast)
- node [at start, cross out, draw, solid, red, inner sep=2pt]{};
- }
- },decorate
- }
-}
-
-\tikzpicture
- \draw [postaction=show curve controls, thick]
- (0,2) .. controls (2.5,1.5) and (0.5,0.5) .. (3,0);
-\endtikzpicture
-\end{codeexample}
-}%
- %
-\end{decoration}
-
-
-\subsection{Marking Decorations}
-
-\subsubsection{Overview}
-
-A \emph{marking on a path} is any kind of graphic that is placed on a specific
-position on a path. Markings are useful in rather diverse situations: you can
-use them to, say, place little ``footsteps'' along a path as if someone where
-walking along the path; to place arrow tips on the middle of a path to indicate
-the ``direction'' in which something is flowing; or you can use them to place
-informative information at certain positions of a path.
-
-For historical reasons there are three different libraries for placing marks on
-a path. They differ in what kind of markings can be added to a path. We start
-with the most general and most useful of these libraries.
-
-
-\subsection{Arbitrary Markings}
-
-\begin{pgflibrary}{decorations.markings}
- Markings are arbitrary ``marks'' that can be put on a path. Marks can be
- arrow tips or nodes or even whole pictures.
-\end{pgflibrary}
-
-\begin{decoration}{markings}
- A \emph{marking} can be thought of a ``little picture'' or more precisely
- of ``some scope contents'' that is placed ``on'' a path at a certain
- position. Suppose the marking should be a simple cross. We can produce this
- with the following code:
- %
-\begin{codeexample}[code only]
-\draw (-2pt,-2pt) -- (2pt,2pt);
-\draw (2pt,-2pt) -- (-2pt,2pt);
-\end{codeexample}
- %
- If we use this code as a marking at position |2cm| on a path, then the
- following happens: \pgfname\ determines the position on the path that is
- 2cm along the path. Then is translates the coordinate system to this
- position and rotates it such that the positive $x$-axis is tangent to the
- path. Then a protective scope is created, inside which the above code is
- executed -- resulting in a little cross on the path.
-
- The |markings| decoration allows you to place one or more such markings on
- a path. The decoration destroys the input path (except in certain cases,
- detailed later), which means that it uses the path for determining
- positions on the path, but after the decoration is done this path is gone.
- You typically need to use a |postaction| to add markings.
-
- Let us start with the above example in real code:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
-\begin{tikzpicture}[decoration={
- markings,% switch on markings
- mark=% actually add a mark
- at position 2cm
- with
- {
- \draw (-2pt,-2pt) -- (2pt,2pt);
- \draw (2pt,-2pt) -- (-2pt,2pt);
- }
- }
- ]
- \draw [help lines] grid (3,2);
- \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
-
- We can also add the cross repeatedly:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
-\begin{tikzpicture}[decoration={
- markings,% switch on markings
- mark=% actually add a mark
- between positions 0 and 1 step 5mm
- with
- {
- \draw (-2pt,-2pt) -- (2pt,2pt);
- \draw (2pt,-2pt) -- (-2pt,2pt);
- }
- }
- ]
- \draw [help lines] grid (3,2);
- \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
-
- The |mark| decoration option is used to specify a marking. It comes in two
- versions:
- %
- \begin{key}{/pgf/decoration/mark=\texttt{at position }\meta{pos}\texttt{ with }\meta{code}}
- The options specifies that when a |marking| decoration is applied,
- there should be a marking at position \meta{pos} on the path whose code
- is given by \meta{code}.
-
- The \meta{pos} can have four different forms:
- %
- \begin{enumerate}
- \item It can be a non-negative dimension like |0pt| or |2cm| or
- |5cm/2|. In this case, it refers to the position along the path
- that is this far displaced from the start.
- \item It can be a negative dimension like |-1cm-2pt| or |-1sp|. In
- this case, the position is taken from the end of the path.
- Thus, |-1cm| is the position that is $-1$cm displaced from the
- end of the path.
- \item It can be a dimensionless non-negative number like |1/2| or
- |0.333+2*0.1|. In this case, the \meta{pos} is interpreted as a
- factor of the total path length. Thus, a \meta{pos} or |0.5|
- refers to the middle of the path, |0.1| is near the start, and
- so on.
- \item It can be a dimensionless negative number like |-0.1|. Then,
- again, the fraction of the path length counts ``from the end''.
- \end{enumerate}
-
- The \meta{pos} determines a position on the path. When the marking is
- applied, the (high level) coordinate system will have been transformed
- so that the origin lies at this position and the positive $x$-axis
- points along the path. For this coordinate system, the \meta{code} is
- executed. It can contain all sorts of graphic drawing commands,
- including (even named) nodes.
-
- If the position lies past the end of the path (for instance if
- \meta{pos} is set to |1.2|), the marking will not be drawn.
-
- It is possible to give the |mark| option several times, which causes
- several markings to be applied. In this case, however, it is necessary
- that the positions on the path are in increasing order. That is, it is
- not allowed (and will result in chaos) to have a marking that lies
- earlier on the path to follow a marking that is later on the path.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
-\begin{tikzpicture}[decoration={
- markings,% switch on markings
- mark=at position 1cm with \node[red]{1cm};,
- mark=at position .5 with \node[green]{mid};,
- mark=at position -1cm with {\node[blue,transform shape]{1cm from end};}}
- ]
- \draw [help lines] grid (3,2);
- \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
-
- Here is an example that shows how markings can be used to place text on
- plots:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
-\begin{tikzpicture}[domain=0:4,label/.style={postaction={
- decorate,
- decoration={
- markings,
- mark=at position .75 with \node #1;}}}]
- \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
-
- \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
- \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
-
- \draw[red,label={[above left]{$f(x)=x$}}] plot (\x,\x);
- \draw[blue,label={[below left]{$f(x)=\sin x$}}] plot (\x,{sin(\x r)});
- \draw[orange,label={[right]{$f(x)= \frac{1}{20} \mathrm e^x$}}] plot (\x,{0.05*exp(\x)});
-\end{tikzpicture}
-\end{codeexample}
-
- When the \meta{code} is being executed, two special keys will have been
- set up, whose value may be of interest:
- %
- \begin{key}{/pgf/decoration/mark info/sequence number}
- This key can only be read. Its value (which can be obtained using
- the |\pgfkeysvalueof| command) is a ``sequence number'' of the
- mark. The first mark that is added to a path has number |1|, the
- second number |2|, and so on. This key is mainly useful in
- conjunction with repeated markings (see below).
- \end{key}
- %
- \begin{key}{/pgf/decoration/mark info/distance from start}
- This key can only be read. Its value is the distance of the marking
- from the start of the path in points. For instance, if the path
- length is 100pt and the marking is in the middle of the path, the
- value of this key would be |50.0pt|.
- \end{key}
- \end{key}
-
- A second way to use the |mark| key is the following:
- %
- \begin{key}{/pgf/decoration/mark=\texttt{between positions }\meta{start pos}\texttt{ and }\meta{end pos}\texttt{ step }\meta{stepping}\texttt{ with }\meta{code}}
- This works similarly to the |at position| version of this option, only
- multiple marks are placed, starting at \meta{start pos} and then spaced
- apart by \meta{stepping}. The \meta{start pos}, the \meta{end pos}, and
- also the \meta{stepping} may all be specified in the same way as for
- the |at position| version, that is, either using units or no units and
- also using positive or negative values.
-
- Let us start with a simple example in which we place ten crosses along
- a path starting with the beginning of the path ($\meta{start pos} = 0$)
- and ending at the end ($\meta{end pos} = 1$).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
-\begin{tikzpicture}[decoration={markings,
- mark=between positions 0 and 1 step 0.1
- with { \draw (-2pt,-2pt) -- (2pt,2pt);
- \draw (2pt,-2pt) -- (-2pt,2pt); }} ]
- \draw [help lines] grid (3,2);
- \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
-
- In the next example we place arrow shapes on the path instead of
- crosses. Note the use of the |transform shape| option to ensure that
- the nodes are actually rotated.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings,shapes.arrows}}]
-\begin{tikzpicture}[decoration={markings,
- mark=between positions 0 and 1 step 1cm
- with { \node [single arrow,fill=red,
- single arrow head extend=3pt,transform shape] {};}}]
- \draw [help lines] grid (3,2);
- \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
-
- Using the key |sequence number| we can also ``number'' the nodes and
- even refer to them later on.
- %
-% FIXME: the automatic key highlighting fails here!
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
-\begin{tikzpicture}[decoration={markings,
- mark=between positions 0 and 1 step 1cm with {
- \node [draw,
- name=mark-\pgfkeysvalueof{/pgf/decoration/mark info/sequence number},
- transform shape]
- {\pgfkeysvalueof{/pgf/decoration/mark info/sequence number}};}}]
- \draw [help lines] grid (3,2);
- \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
- \draw [red,->] (mark-3) -- (mark-7);
-\end{tikzpicture}
-\end{codeexample}
-
- In the following example we use the distance info to place ``length
- information'' on a path:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
-\begin{tikzpicture}[decoration={markings,
- % Main marks
- mark=between positions 0 and 1 step 40pt with
- { \draw [help lines] (0,0) -- (0,0.5)
- node[above,font=\tiny]{
- \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; },
- mark=at position -0.1pt with
- { \draw [help lines] (0,0) -- (0,0.5)
- node[above,font=\tiny]{
- \pgfkeysvalueof{/pgf/decoration/mark info/distance from start}}; }}]
- \draw [help lines] grid (5,3);
- \draw [postaction={decorate}] (0,0) .. controls (8,3) and (0,3) .. (5,0) ;
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/reset marks}
- Since |mark| options accumulate, there needs to be a way to ``reset''
- things, so that any |mark| options set in an enclosing scope do not
- interfere. This option does exactly this. Note that when the
- \meta{code} of a marking is executed, the markings are automatically
- reset.
- \end{key}
-
- As mentioned earlier, the decoration usually destroys the path. However,
- this is no longer the case when the following key is set:
- %
- \begin{key}{/pgf/decoration/mark connection node=\meta{node name} (initially empty)}
- When this key is set to a non-empty \meta{node name} while the
- decoration is being processed, the following happens: The marking code
- should, among possibly other things, define a node named \meta{node
- name}. Then, the output path of this decoration will contain a line-to
- to ``one end'' of this node, followed by a moveto to the ``other end''
- of the node. More precisely, the first end is given by the position on
- the border of \meta{node name} that lies in the direction ``from which
- the path heads toward the node'' while the other end lies on the border
- ``where the path heads away from the node''. Furthermore, this option
- causes the decoration to end with a line-to to the end instead of a
- move-to.
-
- The net effect of all this is that when you decorate a straight line
- with one or more markings that contain just a node, the line will
- effectively connect these nodes.
-
- Here are two examples that show how this works:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
-\begin{tikzpicture}[decoration={markings,
- mark connection node=my node,
- mark=at position .5 with
- {\node [draw,blue,transform shape] (my node) {my node};}}]
- \draw [help lines] grid (3,2);
- \draw decorate { (0,0) -- (3,2) };
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
-\begin{tikzpicture}[decoration={markings,
- mark connection node=my node,
- mark=at position .25 with
- {\node [draw,red] (my node) {my node};}}]
- \draw [help lines] grid (3,2);
- \draw decorate { (0,0) -- (3,2) };
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{decoration}
-
-
-\subsubsection{Arrow Tip Markings}
-
-Frequent markings that are hard to create correctly are arrow tips. For them,
-two special commands are available when the \meta{code} of a |mark| option is
-executed. (They are only defined in this code):
-
-\begin{command}{\arrow\opt{\oarg{options}}\marg{arrow end tip}}
- This command simply draws the \meta{arrow end tip} at the origin, pointing
- right. This is exactly what you need when you want to draw an arrow tip as
- a marking.
-
- The \meta{options} can only be given when \tikzname\ is used. In this case,
- they are executed in a scope that contains the arrow tip.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
-\begin{tikzpicture}[decoration={
- markings,% switch on markings
- mark=at position 1cm with {\node[red]{1cm};},
- mark=at position .75 with {\arrow[blue,line width=2mm]{>}},
- mark=at position -1cm with {\arrowreversed[black]{stealth}}}
- ]
- \draw [help lines] grid (3,2);
- \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
-
- Here is a more useful example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings}}]
-\begin{tikzpicture}[decoration={
- markings,% switch on markings
- mark=between positions 0 and .75 step 4mm with {\arrow{stealth}},
- mark=between positions .75 and 1 step 4mm with {\arrowreversed{stealth}}}
- ]
- \draw [help lines] grid (3,2);
- \draw [postaction={decorate}] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\arrowreversed\opt{\oarg{options}}\marg{arrow end tip}}
- As above, only the arrow end tip is flipped and points in the other
- direction.
-\end{command}
-
-
-\subsubsection{Footprint Markings}
-
-\begin{pgflibrary}{decorations.footprints}
- The decorations of this library can be used to decorate a path with little
- footprints, as if someone had ``walked'' along the path.
-\end{pgflibrary}
-
-\begin{decoration}{footprints}
- The footprint decoration adds little footprints around the path. They start
- with the left foot.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
-\begin{tikzpicture}[decoration={footprints,foot length=5pt,stride length=10pt}]
- \draw [help lines] grid (3,3);
- \fill [decorate] (0,0) -- (3,2) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
- %
- You can influence the way this decoration looks using the following
- options:
- %
- \begin{key}{/pgf/decoration/foot length (initially 10pt)}
- The length or size of the footprint itself. A larger value makes the
- footprint larger, but does not change the stride length.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
-\begin{tikzpicture}[decoration={footprints,foot length=20pt}]
- \fill [decorate] (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/decoration/stride length (initially 30pt)}
- The length of strides. This is the distance between the beginnings of
- left footprints along the path.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
-\begin{tikzpicture}[decoration={footprints,stride length=50pt}]
- \fill [decorate] (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/decoration/foot sep (initially 4pt)}
- The separation in the middle between the footprints. The footprints are
- moved away from the path by half this amount.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
-\begin{tikzpicture}[decoration={footprints,foot sep=10pt}]
- \fill [decorate] (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/decoration/foot angle (initially 10)}
- Footprints are rotated by this much.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.footprints}}]
-\begin{tikzpicture}[decoration={footprints,foot angle=60}]
- \fill [decorate] (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/decoration/foot of (initially human)}
- The species whose footprints are shown. Possible values are:
-
- \def\render#1{
- \texttt{#1} &
- \tikz [baseline,decoration={footprints,foot of=#1}]
- \fill [decorate] (0,0) -- (6,0); \\[3em]
- }
- \begin{tabular}{ll}
- \emph{Species} & \emph{Result} \\[1em]
- \render{gnome}
- \render{human}
- \render{bird}
- \render{felis silvestris}
- \end{tabular}
- \end{key}
-\end{decoration}
-
-
-\subsubsection{Shape Background Markings}
-
-The third library for adding markings uses the background paths of certain
-shapes. This library is included mostly for historical reasons, using the
-|markings| library is usually preferable.
-
-\begin{pgflibrary}{decorations.shapes}
- This library defines decorations that use shapes or shape-like drawings to
- decorate a path. The following options are common options used by the
- decorations in this library:
-
- \begin{key}{/pgf/decoration/shape width=\meta{dimension} (initially 2.5pt)}
- The desired width of the shapes. For decorations that support varying
- shape sizes, this key sets both the start and end width (which can be
- overwritten using options like |shape start width|).
- \end{key}
-
- \begin{key}{/pgf/decoration/shape height=\meta{dimension} (initially 2.5pt)}
- Works like the previous key, only for the height.
- \end{key}
-
- \begin{key}{/pgf/decoration/shape size=\meta{dimension}}
- Sets the desired width and height simultaneously.
- \end{key}
-
- For the exact places and macros where these keys store the values, please
- consult the beginning of the code of the library.
-\end{pgflibrary}
-
-\begin{decoration}{crosses}
- This decoration replaces the path by (diagonal) crosses. The following
- parameters influence the decoration:
- %
- \begin{itemize}
- \item |segment length| determines the distance between (the centers of)
- consecutive crosses.
- \item |shape height| determines the height of each cross.
- \item |shape width| determines the width of each cross.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
-\begin{tikzpicture}[decoration=crosses]
- \draw [help lines] grid (3,2);
- \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{triangles}
- This decoration replaces the path by triangles that point along the path.
- The following parameters influence the decoration:
- %
- \begin{itemize}
- \item |segment length| determines the distance between consecutive
- triangles.
- \item |shape height| determines the height of the triangle side that is
- orthogonal to the path.
- \item |shape width| determines the width of the triangle.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
-\begin{tikzpicture}[decoration=triangles]
- \draw [help lines] grid (3,2);
- \draw [decorate,fill=yellow!80!black] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{shape backgrounds}
- This is a general decoration that replaces the to-be-decorated path by
- repeated copies of the background path of an arbitrary shape that has
- previously been defined using the |\pgfdeclareshape| command (that is, you
- can use any shape in the shape libraries).
-
- Please note that the background path of the shapes is used, but \emph{no
- nodes are created}. This means that \emph{you cannot have text inside the
- shapes of this path, you cannot name them, or refer to them.} Finally, this
- decoration \emph{will not work with shapes that depend strongly on the
- size of the text box (like the arrow shapes).} If any of these restrictions
- pose a problem, use the |markings| library instead.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
-\begin{tikzpicture}[decoration={shape backgrounds,shape=star,shape size=5pt}]
- \draw [help lines] grid (3,2);
- \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
-\tikzset{paint/.style={ draw=#1!50!black, fill=#1!50 },
- decorate with/.style=
- {decorate,decoration={shape backgrounds,shape=#1,shape size=2mm}}}
-\begin{tikzpicture}
- \draw [decorate with=dart, paint=red] (0,1.5) -- (3,1.5);
- \draw [decorate with=diamond, paint=green] (0,1) -- (3,1);
- \draw [decorate with=rectangle, paint=blue] (0,0.5) -- (3,0.5);
- \draw [decorate with=circle, paint=yellow] (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
-
- All shapes are positioned by the anchor that is specified via the |anchor|
- decoration option:
-
- \begin{key}{/pgf/decoration/anchor=\meta{anchor} (initially center)}
- The anchor used to position the shape backgrounds.
- \end{key}
-
- A shape background path is added at the start point of the path and, if the
- distance between the shapes is appropriate, at the end point of the path.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
-\begin{tikzpicture}[decoration={
- shape backgrounds,shape=regular polygon,shape size=4mm}]
- \draw [help lines] grid (3,2);
- \draw [thick] (0,0) -- (2,2) (1,0) -- (3,0);
- \draw [red, decorate, decoration={shape sep=.5cm}] (1,0) -- (3,0);
- \draw [blue, decorate, decoration={shape sep=.5cm}] (0,0) -- (2,2);
-\end{tikzpicture}
-\end{codeexample}
-
- Keys for customizing specific shapes can be specified (e.g., |star points|,
- |cloud puffs|, |kite angles|, and so on). The size of the shape is
- ``enforced'' using transformations. This means that the shape is typeset
- with an empty text box and some default size values, resulting in an
- initial shape. This shape is then rescaled using coordinate transformations
- so that it has the desired size (which may vary as we travel along the
- to-be-decorated path). This means that settings involving angles and
- distances may not appear entirely accurate. More general options such as
- |inner sep| and |minimum size| will be ignored, but transformations can be
- applied to each segment as described below.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
-\tikzset{
- paint/.style={draw=#1!50!black, fill=#1!50},
- my star/.style={decorate,decoration={shape backgrounds,shape=star},
- star points=#1}
-}
-\begin{tikzpicture}[decoration={shape sep=.5cm, shape size=.5cm}]
- \draw [my star=9, paint=red] (0,1.5) -- (3,1.5);
- \draw [my star=5, paint=blue] (0,.75) -- (3,.75);
- \draw [my star=5, paint=yellow, shape border rotate=30] (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
-
- There are various keys to control the drawing of the shape decoration.
-
- \begin{key}{/pgf/decoration/shape=\meta{shape name} (initially circle)}
- The shape whose background path is used.
- \end{key}
-
- \begin{key}{/pgf/decoration/shape sep=\meta{spacing} (initially {.25cm, between centers})}
- Set the spacing between the shapes on the decorations path. This can be
- just a distance on its own, but the additional keywords
- |between centers|, and |between borders| (which must be preceded by a
- comma), specify that the distance is between the center anchors of the
- shapes or between the edges of the \emph{boundaries} of the shape
- borders.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.symbols}}]
-\begin{tikzpicture}[
- decoration={shape backgrounds,shape size=.5cm,shape=signal},
- signal from=west, signal to=east,
- paint/.style={decorate, draw=#1!50!black, fill=#1!50}]
- \draw [help lines] grid (3,2);
- \draw [paint=red, decoration={shape sep=.5cm}]
- (0,2) -- (3,2);
- \draw [paint=green, decoration={shape sep={1cm, between centers}}]
- (0,1) -- (3,1);
- \draw [paint=blue, decoration={shape sep={1cm, between borders}}]
- (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/shape evenly spread=\meta{number}}
- This key overrides the |shape sep| key and forces the decoration to fit
- \meta{number} shapes evenly across the path. If \meta{number} is less
- than |1|, then no shapes will be used. If \meta{number} equals |1|,
- then one shape is put in the middle of the path. The additional
- keywords |by centers| (the default, if no keyword is specified) and
- |by borders| can be used (both preceded by a comma), to specify how the
- distance between shapes is determined. These keywords will only have a
- noticeable effect if the shapes sizes differ over time.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
-\tikzset{
- paint/.style={draw=#1!50!black, fill=#1!50},
- spreading/.style={
- decorate,decoration={shape backgrounds, shape=rectangle,
- shape start size=4mm,shape end size=1mm,shape evenly spread={#1}}}
-}
-\begin{tikzpicture}
- \fill [paint=green,spreading={5, by borders},
- decoration={shape scaled}] (0,2) -- (3,2);
- \fill [paint=blue,spreading={5, by centers},
- decoration={shape scaled}] (0,1.5) -- (3,1.5);
- \fill [paint=red, spreading=5] (0,1) -- (3,1);
- \fill [paint=orange, spreading=4] (0,.5) -- (3,.5);
- \fill [paint=gray, spreading=1] (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/shape sloped=\opt{\meta{boolean}} (initially true)}
- By default, shapes are rotated to the slope of the decorations path. If
- \meta{boolean} is the value |false|, then this rotation is turned off.
- Internally this sets the \TeX-if |\ifpgfshapedecorationsloped|
- accordingly.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes,shapes.geometric}}]
-\tikzset{
- paint/.style={draw=#1!50!black, fill=#1!50}
-}
-\begin{tikzpicture}[decoration={
- shape width=.65cm, shape height=.45cm,
- shape=isosceles triangle, shape sep=.75cm,
- shape backgrounds}]
- \draw [help lines] grid (3,2);
- \draw [paint=red,decorate] (0,0) -- (2,2);
- \draw [paint=blue,decorate,decoration={shape sloped=false}]
- (1,0) -- (3,2);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- It is possible to scale the width and height of the shapes along the length
- of the decorations path. The shapes are scaled between the starting size
- and the ending size. The following keys customize the way the decoration
- shapes are scaled:
-
- \begin{key}{/pgf/decoration/shape scaled=\meta{boolean} (initially false)}
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
-\tikzset{
- bigger/.style={decoration={shape start size=.125cm, shape end size=.5cm}},
- smaller/.style={decoration={shape start size=.5cm, shape end size=.125cm}},
- decoration={shape backgrounds,
- shape sep={.25cm, between borders},shape scaled}
-}
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \fill [decorate, bigger, red!50] (0,1) -- (3,2);
- \fill [decorate, smaller, blue!50] (0,0) -- (3,1);
-\end{tikzpicture}
-\end{codeexample}
-
- If this key is set to false (which is the default), then only the start
- width and height are used. Note that the keys |shape width| and
- |shape height| set the start and end height simultaneously.
- \end{key}
-
- \begin{key}{/pgf/decoration/shape start width=\meta{length} (initially 2.5pt)}
- The starting width of the shape.
- \end{key}%
-
- \begin{key}{/pgf/decoration/shape start height=\meta{length} (initially 2.5pt)}
- The starting height of the shape.
- \end{key}%
-
- \begin{stylekey}{/pgf/decoration/shape start size=\meta{length}}
- Sets both the start height and start width simultaneously.
- \end{stylekey}%
-
- \begin{key}{/pgf/decoration/shape end width=\meta{length} (initially 2.5pt)}
- The recommended ending width of the shape. Note that this is the width
- that a shape will take only if it is drawn exactly at the end of the
- path.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
-\tikzset{
- bigger/.style={decoration={shape start size=.25cm, shape end size=1cm}},
- smaller/.style={decoration={shape start size=1cm, shape end size=.25cm}},
- decoration={shape backgrounds,
- shape sep={.25cm, between borders},shape scaled}
-}
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \fill [decorate,bigger,
- decoration={shape sep={.25cm, between borders}}, blue!50]
- (0,1.5) -- (3,1.5);
- \fill [decorate,smaller,
- decoration={shape sep={1cm, between centers}}, red!50]
- (0,.5) -- (3,.5);
- \draw [gray, dotted] (0,1.625) -- (3,2) (0,1.375) -- (3,1)
- (0,1) -- (3,.625) (0,0) -- (3,.375);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/shape end height=\meta{length}}
- The recommended ending height of the shape.
- \end{key}
-
- \begin{stylekey}{/pgf/decoration/shape end size=\meta{length}}
- Set both the end height and end width simultaneously.
- \end{stylekey}
-\end{decoration}
-
-
-\subsection{Text Decorations}
-
-\begin{pgflibrary}{decorations.text}
- The decoration in this library decorates the path with some text. This can
- be used to draw text that follows a curve.
-\end{pgflibrary}
-
-\begin{decoration}{text along path}
- This decoration decorates the path with text. This drawing of the text is a
- ``side effect'' of the decoration. The to-be-decorated path is only used to
- determine where the characters should be put and it is thrown away after
- the decoration is done. This is why no line is shown in the following
- example.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\catcode`\|12
-\begin{tikzpicture}[decoration={text along path,
- text={Some long text along a ridiculously long curve that}}]
- \draw [help lines] grid (3,2);
- \draw [decorate] (0,0) -- (3,1) arc (0:180:1.5 and 1);
-\end{tikzpicture}
-\end{codeexample}
-
- \pgfname{} ``does its best'' to typeset the text, however you should note
- the following points:
- %
- \begin{itemize}
- \item Each character in the text is typeset in a separate |\hbox|. This
- means that if you want fancy things like kerning or ligatures you
- will have to manually annotate the characters in the decoration
- text within a group, for example, |W{\kern-1ptA}TER|.
- \item Each character is positioned using the center of its baseline. To
- move the text vertically (relative to the path), the additional
- transform key should be used.
- \item No attempt is made to ensure characters do not overlap when the
- angle between segments is considerably less than 180$^\circ$ (this
- is tricky to do in \TeX{} without a huge processing overhead). In
- general this should not be too much of a problem, but, once again,
- kerning can be used in most cases to overcome any undesirable
- effects.
- \item It is only possible to typeset text in math mode under
- considerable restrictions. Math mode is entered and exited using
- any character of category code 3 (e.g., in plain \TeX{} this is |$|). %$
- Math subscripts and superscripts need to be contained within
- braces (e.g., |{^y_i}|) as do commands like |\times| or |\cdot|.
- However, even modestly complex mathematical typesetting is
- unlikely to be successful along a path (or even desirable).
- \item Some inaccuracies in positioning may be particularly apparent at
- input segment boundaries. This can (unfortunately) only be solved
- on a case-by-case basis by individually kerning the offending
- characters within a group.
- \end{itemize}
-
- The following keys are used by the |text| decoration:
- %
- \begin{key}{/pgf/decoration/text=\meta{text} (initially \normalfont empty)}
- Sets the text to typeset along the curve. Consecutive spaces are
- ignored, so |\ | (or |\space| in \LaTeX) should be used to insert
- multiple spaces. It is possible to format the text using normal
- formatting commands, such as |\it|, |\bf| and |\color|, within
- customizable delimiters. Initially these delimiters are both
- {\tt\char`\|} (however, care will be needed regarding the category
- codes of delimiters -- see below).
- %
-{\catcode`\|12
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\catcode`\|12
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \path [decorate,decoration={text along path,
- text={a big |\color{green}|green|| juicy apple.}}]
- (0,0) .. controls (0,2) and (3,0) .. (3,2);
-\end{tikzpicture}
-\end{codeexample}
-}
- %
- By following the first delimiter with |+|, the formatting commands are
- added to any existing formatting.
- %
-{\catcode`\|12
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \path [decorate,decoration={text along path,
- text={a |\large|big |+\bf\color{red}|red|| juicy apple.}}]
- (0,0) .. controls (0,2) and (3,0) .. (3,2);
-\end{tikzpicture}
-\end{codeexample}
-}
-
- Internally, the text is stored in the macro |\pgfdecorationtext|. Any
- characters that have not been typeset when the end of the path has been
- reached will be stored in |\pgfdecorationrestoftext|.
- \end{key}
-
-{\catcode`\|12
- \begin{key}{/pgf/decoration/text format delimiters=\marg{before}\marg{after} (initially \char`\{|\char`\}\char`\{\char`\})}
- \catcode`\|13
-
- Set the characters that the text decoration will use to parse
- formatting commands. If \meta{after} is empty, then \meta{before} will
- be used for both delimiters. In general you should stick to characters
- whose category codes are |11| or |12|. As |+| is used to indicate that
- the specified format commands are added to any existing ones, you
- should avoid using |+| as a delimiter.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \path [decorate, decoration={text along path,text format delimiters={[}{]},
- text={A big [\color{red}]red[] and [\color{green}]green[] apple.}}]
- (0,0) .. controls (0,2) and (3,0) .. (3,2);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-}
-
- \begin{key}{/pgf/decoration/text color=\meta{color} (initially black)}
- The color of the text.
- \end{key}
-
- \begin{key}{/pgf/decoration/reverse path=\meta{boolean} (initially false)}
- This key reverses the path. This is especially useful for typesetting
- text along different sides of curves.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \draw [gray, ->]
- [postaction={decoration={text along path,
- text={a big juicy apple}, text color=red}, decorate}]
- [postaction={decoration={text along path,
- text={a big juicy apple}, text color=blue, reverse path}, decorate}]
- (3,0) .. controls (3,2) and (0,2) .. (0,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/decoration/text align={\ttfamily\char`\{}\meta{alignment options}{\ttfamily\char`\}}}
- This changes the key path to |/pgf/decoration/text align| and executes
- \meta{alignment options}.
- \end{key}
-
- \begin{key}{/pgf/decoration/text align/align=\meta{alignment} (initially left)}
- Aligns the text according to \meta{alignment}, which should be one of
- |left|, |right|, or |center|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}
-\draw [help lines] grid (3,2);
-\draw [red, dashed]
-[postaction={decoration={text along path, text={a big juicy apple},
- text align={align=right}}, decorate}]
-(0,0) .. controls (0,2) and (3,2) .. (3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{stylekey}{/pgf/decoration/text align/left}
- Aligns the text to the left end of the path.
- \end{stylekey}
-
- \begin{stylekey}{/pgf/decoration/text align/right}
- Aligns the text to the right end of the path.
- \end{stylekey}
-
- \begin{stylekey}{/pgf/decoration/text align/center}
- Aligns the text to the center of the path.
- \end{stylekey}
-
- \begin{key}{/pgf/decoration/text align/left indent=\meta{length} (initially 0pt)}
- Specifies a distance which the automaton should move along before it
- starts typesetting the text.
- \end{key}
-
- \begin{key}{/pgf/decoration/text align/right indent=\meta{length} (initially 0pt)}
- Specifies a distance before the end of the path, where the automaton
- should stop typesetting the text.
- \end{key}
-
- \begin{key}{/pgf/decoration/text align/fit to path=\meta{boolean} (initially false)}
- This key makes the decoration automaton try to fit the text to the
- length of the path. The automaton shifts forward by a small amount
- between each character in order to fit the text to the path. If,
- however, the length of the text is longer than the length of the path
- (i.e., the automaton would have to shift \emph{backwards} between
- characters) this key will have no effect.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \draw [red, dashed]
- [postaction={decoration={text along path, text={a big juicy apple},
- text align=fit to path}, decorate}]
- (0,0) .. controls (0,2) and (3,2) .. (3,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/decoration/text align/fit to path stretching spaces=\meta{boolean} (initially false)}
- This key works like the previous key except the automaton shifts
- forward only for space characters (including |\space|, but
- \emph{excluding} |\ |).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \draw [red, dashed]
- [postaction={decoration={text along path, text={a big juicy apple},
- text align={fit to path stretching spaces}}, decorate}]
- (0,0) .. controls (0,2) and (3,2) .. (3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{decoration}
-
-\begin{decoration}{text effects along path}
- This decoration is similar to the |text along path| decoration except that
- each character is inserted into the picture as a \tikzname\ node, and node
- options (such as |text|, |scale| and |opacity|) can be used to create `text
- effects'.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text,math}}]
-\bfseries\large
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!}, text align=center,
- text effects/.cd,
- character count=\i, character total=\n,
- characters={evaluate={\c=\i/\n*100;}, text along path, text=red!\c!orange},
- character widths={text along path, xslant=0, yscale=1}}]
-
-\path [postaction={decorate}, preaction={decorate,
- text effects={characters/.append={yscale=-1.5, opacity=0.5,
- text=gray, xslant=(\i/\n-0.5)*3}}}]
- (0,0) .. controls ++(2,1) and ++(-2,-1) .. (3,4);
-\end{tikzpicture}
-\end{codeexample}
-
- There are some important differences between this decoration and the
- |text along path| decoration:
- %
- \begin{itemize}
- \item formatting (e.g., font and color) cannot be specified in the
- decoration text. They can only be specified using the keys
- described below.
- \item as a consequence of using the \tikzname\ node options, this
- decoration is only available in \tikzname.
- \item due to the number of computations involved, this is quite a slow
- decoration.
- \end{itemize}
-
- The following keys are shared with the |text along path| decoration:
-
- \begin{key}{/pgf/decoration/text=\marg{text}}
- Set the text this decoration will use. Braces can be used to group
- multiple characters together, or commands that should not be expanded
- until they are typeset, for example |gr{\"o}{\ss}eren|. You should
- \emph{not} use the formatting delimiters or math mode characters that
- the |text along path| decoration supports.
- \end{key}
-
- \begin{key}{/pgf/decoration/text align=\meta{align}}
- This sets the alignment of the text along the path. The \meta{align}
- argument should be |left|, |right| or |center|. Spreading the text out,
- or stretching the spaces between words is \emph{not} supported.
- \end{key}
-
- The decoration text can be thought of as consisting of \emph{characters}
- arranged in to sequences of \emph{letters} to make \emph{words} which are
- separated by a \emph{word separator}. This, however, does not mean that you
- are limited to using only natural language as the decoration text.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={000-001-010-011-100-101-110-111},
- text effects/.cd,
- path from text,
- word separator=-,
- every letter/.style={shape=rectangle, fill=blue!20, draw=blue!40}}]
-
-\path [decorate] (0,0);
-\end{tikzpicture}
-\end{codeexample}
-
- In addition, it is possible to replace characters with \tikzname\ code:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={000-001-010-011-100-101-110-111}, text align=center,
- text effects/.cd,
- word separator=-,
- replace characters=0 with {\fill [purple] circle [radius=2pt]; },
- replace characters=1 with {\fill [orange] circle [radius=2pt]; },
- replace characters=- with {\path circle [radius=2pt]; },
- every letter/.style={shape=rectangle, fill=blue!20, draw=blue!40}}]
-
-\path [decorate] (0,0) .. controls ++(2,0) and ++(-2,0) .. (3,4);
-\end{tikzpicture}
-\end{codeexample}
-
- There are many keys and styles that can be used to add effects to the
- decoration text. Many of these keys have the parent path
- |/pgf/decoration/text effects/|, but for convenience, these keys can be
- accessed using the following key:
-
- \begin{key}{/tikz/text effects=\marg{options}}
- Execute every option in \marg{options} with the key path for each option
- temporarily set to |/pgf/decoration/text effects/|.
- \end{key}
-
- The following keys can be used to customise the
- appearance of text in the |text effects along path|
- decoration.
-
- \begin{stylekey}{/pgf/decoration/text effects/every character}
- Set the effects that will be applied to every character in the
- decoration text. The effects will typically be \tikzname\ node options.
- Initially, this style is empty so the decoration simply positions nodes
- at the appropriate position along the path. In order to make the text
- `follow the path' like the |text along path| decoration the following
- key can be added to the |every character| style.
- \end{stylekey}
-
- \begin{stylekey}{/pgf/decoration/text effects/text along path}
- This style automatically sets the \tikzname\ keys |transform shape| (to
- make the character slope with the path), |anchor=baseline| (to make the
- baseline of the characters `sit' on the path) and |inner xsep=0pt| (to
- horizontally fit each node to the character it contains, reducing the
- spacing between characters).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!}}]
-
-\path [draw=red, dotted, postaction={decorate}]
- (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
-\path [draw=blue, dotted, yshift=1cm, postaction={decorate},
- text effects={text along path}]
- (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
-\end{tikzpicture}
-\end{codeexample}
- \end{stylekey}
-
- \begin{key}{/pgf/decoration/text effects/characters=\marg{effects}}
- Shorthand for the |every character|.
- \end{key}
-
- \begin{stylekey}{/pgf/decoration/text effects/character \meta{number}}
- Specify additional effects for the character \meta{number}.
- \end{stylekey}
-
- \begin{stylekey}{/pgf/decoration/text effects/every letter}
- Specify additional effects for every letter (i.e., every character that
- isn't the word separator) in the decoration text.
- \end{stylekey}
-
- \begin{stylekey}{/pgf/decoration/text effects/letter \meta{number}}
- Specify the effects for letter \meta{number} in \emph{every} word.
- \end{stylekey}
-
-
-\begin{stylekey}{/pgf/decoration/text effects/every first letter}
- Specify additional effects for the first letter in \emph{every} word.
-\end{stylekey}
-
-\begin{stylekey}{/pgf/decoration/text effects/every last letter}
- Specify additional effects for the last letter in \emph{every} word.
-\end{stylekey}
-
-\begin{stylekey}{/pgf/decoration/text effects/every word}
- Specify additional effects for every word in the decoration text.
-\end{stylekey}
-
-\begin{stylekey}{/pgf/decoration/text effects/word \meta{number}}
- Specify additional effects for word \meta{number} in the decoration text.
-\end{stylekey}
-
-\begin{stylekey}{/pgf/decoration/text effects/word \meta{m} letter \meta{n}}
- Specify additional effects for letter \meta{n} in word \meta{m} in the
- decoration text.
-\end{stylekey}
-
-\begin{stylekey}{/pgf/decoration/text effects/every word separator}
- Specify additional effects for every character that is a word separator.
-\end{stylekey}
-
-\begin{key}{/pgf/decoration/text effects/word separator=\meta{character} (initially space)}
- Specify the character that is to be used as the word separator. This
- \emph{must} be a single character such as |a| or |-| or the special value
- |space| (which should be used to indicate that spaces should be used as the
- separator).
-\end{key}
-
- By default, the width for each character is calculated according to the
- bounding box of the node in which it is contained. However, if the node is
- rotated or slanted, or has a substantial |inner sep|, this bounding box
- will be quite big. The following key enables different effects to be
- applied to the node that is used to calculate the width.
-
- \begin{stylekey}{/pgf/decoration/text effects/every character width}
- This style is applied to the (invisible) nodes used for calculating the
- width of a character node.
- \end{stylekey}
-
- \begin{key}{/pgf/decoration/text effects/character widths=\marg{effects}}
- Shorthand for the |every character width| style.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!}, text align=center,
- text effects/.cd,
- character count=\i,
- characters={xslant=0.5, text along path, name=c-\i}}]
-
-\path [decorate] (0,0) -- (3,2);
-\path [decorate,
- text effects={character widths={inner xsep=0pt, xslant=0}}]
- (0,1) -- (3,3);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- It is possible to parameterize effects, perhaps for doing calculations, or
- labelling nodes based on the number of the character in the decoration
- text. To access the number of the character, and the total number of
- characters the following keys can be used. However, these keys should
- \emph{not} be used inside the style keys given above.
-
- \begin{key}{/pgf/decoration/text effects/character count=\meta{macro}}
- Store the number of the character being typeset in \meta{macro}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- path from text,
- character count=\i, every word separator/.style={fill=red!30},
- characters={text along path, shape=circle, fill=gray!50}}]
-
-\path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/character total=\meta{macro}}
- Store the total number of the characters in the decoration text in
- \meta{macro}. This key can be used with the |character count| key to
- produce some quite pleasing effects:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text,math}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- character count=\i, character total=\n,
- characters={text along path, evaluate={\c=\i/\n*100;},
- text=orange!\c!blue, scale=\i/\n+0.5}}]
-
-\path [decorate]
- (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/letter count=\meta{macro}}
- Store the number of letter being typeset (i.e., the position of the
- character in the word) in \meta{macro}. Numbering starts at |1| and the
- character acting as a word separator is numbered |0|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- path from text, letter count=\i, every word separator/.style={fill=red!30},
- characters={text along path, shape=circle, fill=gray!50}}]
-
-\path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/text/effetcs/letter total=\meta{macro}}
- Store the number of letters in the current word in \meta{macro}. When
- the character is the word separator, this value is |0|.
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/word count=\meta{macro}}
- Store the number of words in the decoration text in \meta{macro}.
- Numbering starts at |1|. When the character is the word separator,
- \meta{macro} takes the number of the previous word. If the decoration
- text starts with a word separator \meta{macro} will be |0|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- path from text, word count=\i, every word separator/.style={fill=red!30},
- characters={text along path, shape=circle, fill=gray!50}}]
-
- \path [decorate, text effects={characters/.append={label=above:\footnotesize\i}}] (0,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/word total=\meta{macro}}
- Store the total number of words in the decoration text in \meta{macro}.
- \end{key}
-
- It is also possible to apply effects to specific characters such as
- coloring every instance of the character |a|, or changing the font of every
- |T| in the decoration text:
-
- \begin{key}{/pgf/decoration/text effects/style characters=\marg{characters} with \marg{effects}}
- This key enables \meta{effects} to be applied to every character in the
- decoration text that is specified in \meta{characters}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={Falsches {\"U}ben von Xylophonmusik qu{\"a}lt jeden gr{\"o}{\ss}eren Zwerg},
- text effects/.cd,
- path from text,
- style characters=aeiou{\"U}{\"a}{\"o} with {text=blue},
- characters={text along path}}]
-
-\path [decorate] (0,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/path from text=\opt{\marg{true or false}} (default true)}
- When this key is set to |true| and the decorated path consists only of
- a single point, the decoration will calculate the width of the
- decoration text using all the specified parameters as if the decorated
- path was actually a straight line starting from the given point. This
- `virtual' straight line is then decorated with the text.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- path from text,
- character count=\i, character total=\n,
- characters={text along path, scale=\i/\n+0.5}}]
-
-\path [decorate] (0,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/path from text angle=\meta{angle}}
- When used in conjunction with the |path from text| key, the straight
- line that is used as the decorated path is rotated by \meta{angle}
- around the starting point.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- path from text, path from text angle=60,
- character count=\i, character total=\n,
- characters={text along path, scale=\i/\n+0.5}}]
-
-\path [decorate] (0,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/fit text to path=\opt{\meta{true or false}} (default true)}
- This key will make the decoration increase the space between characters
- so that the entire path is used by the decoration.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/every character/.style={text along path}}]
-
-\path [draw=gray, postaction={decorate}, rotate=90]
- (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
-\path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm,
- text effects={fit text to path}]
- (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/scale text to path=\opt{\meta{true or false}} (default true)}
- This key will make the decoration scale the text so that the entire
- path is used by the decoration.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/every character/.style={text along path}}]
-
-\path [draw=gray, postaction={decorate}, rotate=90]
- (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
-\path [draw=gray, postaction={decorate}, rotate=90, yshift=-1cm,
- text effects={scale text to path}]
- (0,0) .. controls ++(2,0) and ++(-1,0) .. (5,-1);
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/reverse text}
- Reverse the order of the characters in the decoration text. This may be
- useful if using `right-to-left` languages. Unfortunately, any leading
- `soft' spaces in the original text will be lost.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- path from text, path from text angle=60,
- reverse text,
- character count=\i, character total=\n,
- characters={text along path, scale=\i/\n+0.5}}]
-
-\path [decorate] (0,0) .. controls ++(1,0) and ++(-1,0) .. (3,2);
-\end{tikzpicture}
-\end{codeexample}
-
- It is important to note that the |reverse text| key reverses the text
- \emph{before} doing anything else. This means that the numbering of
- characters, letters and words will still be in the normal order, so any
- parameterized effects will have to take this into account.
- Alternatively, to get the numbering to follow the reversed text, it is
- possible to reverse the path and then invert the scale:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- path from text, path from text angle=60,
- character count=\i, character total=\n,
- characters={text along path, scale=\i/\n+0.5}}]
-
-\path [decorate, text effects={reverse text}] (0,0);
-\path [blue, decorate, decoration={reverse path},
- text effects={characters/.append={scale=-1}}] (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/group letters}
- Group sequences of letters together so they are treated as a single
- `character'.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- path from text, path from text angle=60,
- every word separator/.style={fill=none},
- character count=\i, character total=\n,
- characters={text along path, fill=gray!50, scale=\i/\n+0.5}}]
-
-\path [decorate] (0,0);
-\path [decorate, text effects={group letters,
- characters/.append={fill=red!20}}]
- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- The order in which the |reverse text| and |group letters| keys are applied
- is important:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- path from text, path from text angle=60,
- every word separator/.style={fill=none},
- character count=\i, character total=\n,
- characters={text along path, fill=gray!50, scale=\i/\n+0.5}}]
-
-\path [decorate, text effects={reverse text, group letters}] (0,0);
-\path [decorate, text effects={group letters, reverse text,
- characters/.append={fill=red!20}}] (1,0);
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{key}{/pgf/decoration/text effects/repeat text=\opt{\meta{times}}}
- Usually, when the decoration runs out of text, it simply stops. This
- key will make the decoration repeat the decoration text for the
- specified number of \meta{times}. If no value is given the text will be
- repeated until the path is finished. There are two points to remember
- however. Firstly the numbering of characters, letters and words will be
- restarted each time the text is repeated. Secondly, the options for
- alignment, scaling or fitting the text to the path, fitting the path to
- the text, and so on, are computed using the decoration text before the
- decoration starts. If any of these options are given the behavior of
- the |repeat text| key is undefined, but typically it will be ignored.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!\ },
- text effects/.cd,
- repeat text,
- character count=\m, character total=\n,
- characters={text along path, scale=0.5+\m/\n/2}}]
-
-\path [draw=gray, ultra thin, postaction=decorate]
- (180:2) \foreach \a in {0,...,12}{ arc (180-\a*90:90-\a*90:1.5-\a/10) };
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/character command=\meta{macro}}
- This key specifies a command that is executed when each character is
- placed in the node. The \meta{macro} should be an ordinary \TeX\ macro
- which takes one argument. The argument will be a macro which when
- expanded will contain the current character.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\def\mycommand#1{#1$_\n$}
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- path from text, path from text angle=60, group letters,
- word count=\n,
- every word/.style={character command=\mycommand},
- characters={text along path}}]
-
-\path [decorate] (0,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/decoration/text effects/replace characters=\meta{characters} with \marg{code}}
- Replace the node for each character in \meta{characters} with
- \meta{code}. The \meta{code} can be thought of as describing a little
- picture or marking which will be used instead of the character node.
- The origin will be the current point along the decoration path. Any
- transformations associated with the \meta{characters} (e.g., applied
- with the |every character| or |every letter| styles) will also be
- applied to \meta{code}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text effects along path,
- text={text effects along path!},
- text effects/.cd,
- path from text, path from text angle=60,
- replace characters=e with {\fill [red!20] (0,1mm) circle [radius=1mm];},
- replace characters=a with {\fill [black!20] (0,1mm) circle [radius=1mm];},
- character count=\i, character total=\n,
- characters={text along path, scale=\i/\n+0.5}}]
-
-\path [decorate] (0,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{decoration}
-
-
-\subsection{Fractal Decorations}
-
-\begin{pgflibrary}{decorations.fractals}
- The decorations of this library can be used to create fractal lines. To use
- them, you typically have to apply the decoration repeatedly to an
- originally straight path.
-\end{pgflibrary}
-
-\begin{decoration}{Koch curve type 1}
- This decoration replaces a straight line by a ``rectangular bump''. By
- repeatedly applying this replacement, different levels of the Koch curve
- fractal can be created. Its Hausdorff dimension is $\log 5/\log 3$.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
-\begin{tikzpicture}[decoration=Koch curve type 1]
- \draw decorate{ (0,0) -- (3,0) };
- \draw decorate{ decorate{ (0,-1.5) -- (3,-1.5) }};
- \draw decorate{ decorate{ decorate{ (0,-3) -- (3,-3) }}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{Koch curve type 2}
- This decoration replaces a straight line by a ``rectangular sine''. Its
- Hausdorff dimension is $3/2$.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
-\begin{tikzpicture}[decoration=Koch curve type 2]
- \draw decorate{ (0,0) -- (3,0) };
- \draw decorate{ decorate{ (0,-2) -- (3,-2) }};
- \draw decorate{ decorate{ decorate{ (0,-4) -- (3,-4) }}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{Koch snowflake}
- This decoration replaces a straight line by a ``line with a spike''. The
- Hausdorff dimension of Koch's snowflake's is $\log 4/\log 3$.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
-\begin{tikzpicture}[decoration=Koch snowflake]
- \draw decorate{ (0,0) -- (3,0) };
- \draw decorate{ decorate{ (0,-1) -- (3,-1) }};
- \draw decorate{ decorate{ decorate{ (0,-2) -- (3,-2) }}};
- \draw decorate{ decorate{ decorate{ decorate{ (0,-3) -- (3,-3) }}}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
-
-\begin{decoration}{Cantor set}
- This decoration replaces a straight line by a ``line with a gap in the
- middle''. The Hausdorff dimension of the Cantor set is $\log 2/\log 3$.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
-\begin{tikzpicture}[decoration=Cantor set,very thick]
- \draw decorate{ (0,0) -- (3,0) };
- \draw decorate{ decorate{ (0,-.5) -- (3,-.5) }};
- \draw decorate{ decorate{ decorate{ (0,-1) -- (3,-1) }}};
- \draw decorate{ decorate{ decorate{ decorate{ (0,-1.5) -- (3,-1.5) }}}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{decoration}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-edges.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-edges.tex
deleted file mode 100644
index 51332af0cc..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-edges.tex
+++ /dev/null
@@ -1,330 +0,0 @@
-% 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{To Path Library}
-\label{library-to-paths}
-
-\begin{tikzlibrary}{topaths}
- This library provides predefined to paths for use with the |to| path
- operation. After loading this package, you can say for instance |to [loop]|
- to add a loop to a node.
-
- This library is loaded automatically by \tikzname, so you do not need to
- load it yourself.
-\end{tikzlibrary}
-
-
-\subsection{Straight Lines}
-
-The following style installs a to path that is simply a straight line from the
-start coordinate to the target coordinate.
-
-\begin{key}{/tikz/line to}
- Causes a straight line to be added to the path upon a |to| or an |edge|
- operation.
- %
-\begin{codeexample}[]
-\tikz {\draw (0,0) to[line to] (1,0);}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Move-Tos}
-
-The following style installs a to path that simply ``jumps'' to the target
-coordinate.
-
-\begin{key}{/tikz/move to}
- Causes a move to be added to the path upon a |to| or an |edge| operation.
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) to[line to] (1,0)
- to[move to] (2,0) to[line to] (3,0);
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Curves}
-
-The |curve to| style causes the to path to be set to a curve. The exact way
-this curve looks can be influenced via a number of options.
-
-\begin{key}{/tikz/curve to}
- Specifies that the |to path| should be a curve. This curve will leave the
- start coordinate at a certain angle, which can be specified using the |out|
- option. It reaches the target coordinate also at a certain angle, which is
- specified using the |in| option. The control points of the curve are at a
- certain distance that is computed in different ways, depending on which
- options are set.
-
- All of the following options implicitly cause the |curve to| style to be
- installed.
-
- \begin{key}{/tikz/out=\meta{angle}}
- The angle at which the curve leaves the start coordinate. If the start
- coordinate is a node, the start coordinate is the point on the border
- of the node at the given \meta{angle}. The control point will, thus,
- lie at a certain distance in the direction \meta{angle} from the start
- coordinate.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[out=45,in=135]
- \draw (0,0) to (1,0)
- (0,0) to (2,0)
- (0,0) to (3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/in=\meta{angle}}
- The angle at which the curve reaches the target coordinate.
- \end{key}
-
- \begin{key}{/tikz/relative=\meta{true or false} (default true)}
- This option tells \tikzname\ whether the |in| and |out| angles should
- be considered absolute or relative. Absolute means that an |out| angle
- of 30$^\circ$ means that the curve leaves the start coordinate at an
- angle of 30$^\circ$ relative to the paper (unless, of course, further
- transformations have been installed). A \emph{relative} angle is, by
- comparison, measured relative to a straight line from the start
- coordinate to the target coordinate. Thus, a relative angle of
- 30$^\circ$ means that the curve will bend to the left from the line
- going straight from the start to the target. For the target, the
- relative coordinate is measured in the same manner, namely relative to
- the line going from the start to the target. Thus, an angle of
- 150$^\circ$ means that the curve will reach target coming slightly from
- the left.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[out=45,in=135,relative]
- \draw (0,0) to (1,0)
- to (2,1)
- to (2,2);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[out=90,in=90,relative]
- \node [circle,draw] (a) at (0,0) {a};
- \node [circle,draw] (b) at (1,1) {b};
- \node [circle,draw] (c) at (2,2) {c};
-
- \path (a) edge (b)
- edge (c);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/bend left=\meta{angle} (default \normalfont last value)}
- This option sets |out=|\meta{angle}|,in=|$180-\meta{angle}$|,relative|.
- If no \meta{angle} is given, the last given |bend left| or |bend right|
- angle is used.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{automata,positioning}}]
-\begin{tikzpicture}[shorten >=1pt,node distance=2cm,on grid]
- \node[state,initial] (q_0) {$q_0$};
- \node[state] (q_1) [right=of q_0] {$q_1$};
- \node[state,accepting](q_2) [right=of q_1] {$q_2$};
-
- \path[->] (q_0) edge node [above] {0} (q_1)
- edge [loop above] node {1} ()
- edge [bend left] node [above] {1} (q_2)
- edge [bend right] node [below] {0} (q_2)
- (q_1) edge node [above] {1} (q_2);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- \foreach \angle in {0,45,...,315}
- \node[rectangle,draw=black!50] (\angle) at (\angle:2) {\angle};
-
- \foreach \from/\to in {0/45,45/90,90/135,135/180,
- 180/225,225/270,270/315,315/0}
- \path (\from) edge [->,bend right=22,looseness=0.8] (\to)
- edge [<-,bend left=22,looseness=0.8] (\to);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/bend right=\meta{angle} (default \normalfont last value)}
- Works like the |bend left| option, only the bend is to the other side.
- \end{key}
-
- \begin{key}{/tikz/bend angle=\meta{angle}}
- Sets the angle to be used by the |bend left| or |bend right|, but
- without actually selecting the |curve to| or the |relative| option.
- This is useful for globally specifying a |bend angle| for a whole
- picture.
- \end{key}
-
- \begin{key}{/tikz/looseness=\meta{number} (initially 1)}
- This number specifies how ``loose'' the curve will be. In detail, the
- following happens: \tikzname\ computes the distance between the start
- and the target coordinate (if the start and/or target coordinate are
- nodes, the distance is computed between the points on their border).
- This distance is then multiplied by a fixed factor and also by the
- factor \meta{number}. The resulting distance, let us call it $d$, is
- then used as the distance of the control points from the start and
- target coordinates.
-
- The fixed factor has been chosen in such a way that if \meta{number} is
- |1|, if the |in| and |out| angles differ by 90$\circ$, then a quarter
- circle results:
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) to [out=0,in=-90] (1,1);
-\tikz \draw (0,0) to [out=0,in=-90,looseness=0.5] (1,1);
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/out looseness=\meta{number}}
- Specifies the looseness factor for the out distance only.
- \end{key}
-
- \begin{key}{/tikz/in looseness=\meta{number}}
- Specifies the looseness factor for the in distance only.
- \end{key}
- %
- \begin{key}{/tikz/min distance=\meta{distance}}
- If the computed distance for the start and target coordinates are below
- \meta{distance}, then \meta{distance} is used instead.
- \end{key}
- %
- \begin{key}{/tikz/max distance=\meta{distance}}
- If the computed distance for the start and target coordinates are above
- \meta{distance}, then \meta{distance} is used instead.
- \end{key}
- %
- \begin{key}{/tikz/out min distance=\meta{distance}}
- The minimum distance set only for the start coordinate.
- \end{key}
- %
- \begin{key}{/tikz/out max distance=\meta{distance}}
- The maximum distance set only for the start coordinate.
- \end{key}
- %
- \begin{key}{/tikz/in min distance=\meta{distance}}
- The minimum distance set only for the target coordinate.
- \end{key}
- %
- \begin{key}{/tikz/in max distance=\meta{distance}}
- The maximum distance set only for the target coordinate.
- \end{key}
- %
- \begin{key}{/tikz/distance=\meta{distance}}
- Set the minimum and maximum distance to the same value \meta{distance}.
- Note that this causes any computed distance $d$ to be ignored and
- \meta{distance} to be used instead.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[out=45,in=135,distance=1cm]
- \draw (0,0) to (1,0)
- (0,0) to (2,0)
- (0,0) to (3,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
- %
- \begin{key}{/tikz/out distance=\meta{distance}}
- Sets the minimum and maximum out distance.
- \end{key}
- %
- \begin{key}{/tikz/in distance=\meta{distance}}
- Sets the minimum and maximum in distance.
- \end{key}
- %
- \begin{key}{/tikz/out control=\meta{coordinate}}
- This option causes the \meta{coordinate} to be used as the start
- control point. All computations of $d$ are ignored. You can use a
- coordinate like |+(1,0)| to specify a point relative to the start
- coordinate.
- \end{key}
- %
- \begin{key}{/tikz/in control=\meta{coordinate}}
- This option causes the \meta{coordinate} to be used as the target
- control point. You can use a coordinate like |+(1,0)| to specify
- a point relative to the \emph{end} coordinate.
- \end{key}
- %
- \begin{key}{/tikz/controls=\meta{coordinate}| and |\meta{coordinate}}
- This option causes the \meta{coordinate}s to be used as control points.
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) to [controls=+(90:1) and +(90:1)] (3,0);
-\end{codeexample}
- \end{key}
-\end{key}
-
-
-\subsection{Loops}
-
-\begin{key}{/tikz/loop}
- This key is similar to the |curve to| key, but differs in the following
- ways: First, the actual target coordinate is ignored and the start
- coordinate is used as the target coordinate. Thus, it is allowed not to
- provide any target coordinate, which can be useful with unnamed nodes.
- Second, the |looseness| is set to |8| and the |min distance| to |5mm|.
- These settings result in rather nice loops when the opening angle
- (difference between |in| and |out|) is 30$^\circ$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node [circle,draw] {a} edge [in=30,out=60,loop] ();
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{stylekey}{/tikz/loop above}
- Sets the |loop| style and sets in and out angles such that loop is above
- the node. Furthermore, the |above| option is set, which causes a node label
- to be placed at the correct position.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node [circle,draw] {a} edge [loop above] node {x} ();
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/loop below}
- Works like the previous option.
-\end{stylekey}
-%
-\begin{stylekey}{/tikz/loop left}
- Works like the previous option.
-\end{stylekey}
-%
-\begin{stylekey}{/tikz/loop right}
- Works like the previous option.
-\end{stylekey}
-%
-\begin{stylekey}{/tikz/every loop (initially {->,shorten >=1pt})}
- This style is installed at the beginning of every loop.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[every loop/.style={}]
- \draw (0,0) to [loop above] () to [loop right] ()
- to [loop below] () to [loop left] ();
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-er.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-er.tex
deleted file mode 100644
index 27470015fd..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-er.tex
+++ /dev/null
@@ -1,155 +0,0 @@
-% 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{Entity-Relationship Diagram Drawing Library}
-
-\begin{tikzlibrary}{er}
- This packages provides styles for drawing entity-relationship diagrams.
-\end{tikzlibrary}
-
-This library is intended to help you in creating E/R-diagrams. It defines only
-few new styles, but using the style |entity| instead of saying |rectangle,draw|
-makes the code more expressive.
-
-
-\subsection{Entities}
-
-The package defines a simple style for drawing entities:
-
-\begin{stylekey}{/tikz/entity}
- This style is to be used with nodes that represent entity types. It causes
- the node's shape to be set to a rectangle that is drawn and whose minimum
- size and width are set to sensible values.
-
- Note that this style is called |entity| despite the fact that it is to be
- used for nodes representing entity \emph{types} (the difference between an
- entity and an entity type is the same as the difference between an object
- and a class in object-oriented programming). If this bothers you, feel free
- to define a style |entity type| instead.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{er,positioning}}]
-\begin{tikzpicture}
- \node[entity] (sheep) {Sheep};
- \node[entity] (genome) [right=of sheep] {Genome};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/every entity}
- This style is evoked by the style |entity|. To change the appearance of
- entities, you can change this style.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{er,positioning}}]
-\begin{tikzpicture}
- [every entity/.style={draw=blue!50,fill=blue!20,thick}]
- \node[entity] (sheep) {Sheep};
- \node[entity] (genome) [right=of sheep] {Genome};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsection{Relationships}
-
-Relationships are drawn using styles that are very similar to the styles for
-entities.
-
-\begin{stylekey}{/tikz/relationship}
- This style works like |entity|, only it is to be used for relationships.
- Again, |relationship|s are actually relationship types.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{er}}]
-\begin{tikzpicture}
- \node[entity] (sheep) at (0,0) {Sheep};
- \node[entity] (genome) at (2,0) {Genome};
- \node[relationship] at (1,1.5) {has}
- edge (sheep)
- edge (genome);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/every relationship}
- Works like |every entity|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{er}}]
-\begin{tikzpicture}
- [every entity/.style={fill=blue!20,draw=blue,thick},
- every relationship/.style={fill=orange!20,draw=orange,thick,aspect=1.5}]
- \node[entity] (sheep) at (0,0) {Sheep};
- \node[entity] (genome) at (2,0) {Genome};
- \node[relationship] at (1,1.5) {has}
- edge (sheep)
- edge (genome);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsection{Attributes}
-
-\begin{stylekey}{/tikz/attribute}
- This style is used to indicate that a node is an attribute. To connect an
- attribute to its entity, you can use, for example, the |child| command or
- the |pin| option.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{er}}]
-\begin{tikzpicture}
- \node[entity] (sheep) {Sheep}
- child {node[attribute] {name}}
- child {node[attribute] {color}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{er}}]
-\begin{tikzpicture}[every pin edge/.style=draw]
- \node[entity,pin={[attribute]60:name},pin={[attribute]120:color}] {Sheep};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/key attribute}
- This style is intended for key attributes. By default, the will cause the
- attribute to be typeset in italics. Typically, underlining is used instead,
- but that looks ugly and it is difficult to implement in \TeX.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/every attribute}
- This style is used with every attribute, and therefore also for every key
- attribute.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{er}}]
-\begin{tikzpicture}
- [text depth=1pt,
- every attribute/.style={fill=black!20,draw=black},
- every entity/.style={fill=blue!20,draw=blue,thick},
- every relationship/.style={fill=orange!20,draw=orange,thick,aspect=1.5}]
-
- \node[entity] (sheep) at (0,0) {Sheep}
- child {node [key attribute] {name}};
- \node[entity] (genome) at (2,0) {Genome};
- \node[relationship] at (1,1.5) {has}
- edge (sheep)
- edge (genome);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-external.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-external.tex
deleted file mode 100644
index ee3a890518..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-external.tex
+++ /dev/null
@@ -1,1227 +0,0 @@
-% Copyright 2019 by Christian Feuersaenger
-%
-% 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{Externalization Library}
-\label{section-libs-external}
-
-{
-\pgfkeys{
- /pdflinks/search key prefixes in/.add={/tikz/external/,}{}
-}
-{\noindent {\emph{by Christian Feuersänger}}}
-
-\begin{tikzlibrary}{external}
- This library provides a high-level automatic or semi-automatic export
- feature for \tikzname\ pictures. Its purpose is to convert each picture to
- a separate \pdf\ without changing the document as such.
-
- It also externalizes |\label| information (and other aux file related
- stuff) using auxiliary files.
-\end{tikzlibrary}
-
-
-\subsection{Overview}
-
-There are several reasons why external images for at least some pictures are of
-interest:
-%
-\begin{enumerate}
- \item Larger picture require a considerable amount of time, which is
- necessary for every compilation. However, only few images will change
- from run to run. It can simply save time to export finished images and
- include them as final graphics.
- \item It may be desirable to have final images for some graphics, for
- example to include them in third--party programs or to communicate them
- electronically.
- \item It may be necessary to typeset a file in environments where \pgfname\
- and \tikzname\ are not available. In this case, external images are the
- only way to ensure compatibility.
-\end{enumerate}
-%
-The purpose of this library is to provide a way to export any \tikzname-picture
-to separate \pdf\ (or \eps) images without changing the main document. It is
-actually a simple user interface to the |\beginpgfgraphicnamed| $\dotsc$
-|\endpgfgraphicnamed| framework of \pgfname\ which is discussed in
-section~\ref{section-external}.
-
-
-\subsection{Requirements}
-
-For most users, the library does not need special attention since requirements
-are met anyway. It collects all tokens between |\begin{tikzpicture}| and the
-next following |\end{tikzpicture}| and replaces them by the appropriate
-graphics or it takes steps to generate such an image.
-%For Con\TeX t and plain \TeX\ users, the appropriate begin and end picture
-%statements apply.
-
-It can't expand macros during this step, so the only requirement is that every
-picture's end is directly reachable from its beginning, without further macro
-expansion. Furthermore, the library assumes that all \LaTeX\ pictures are ended
-with |\end{tikzpicture}|.
-%In Con\TeX t, the end command is assumed to be |\stoptikzpicture| and for plain
-%\TeX\ it is |\endtikzpicture|.
-
-The library always searches for the \emph{next} picture's end,
-|\end{tikzpicture}|. As a consequence, you can't use nested pictures directly.
-You \emph{can} nest pictures, but you have to avoid that the nested picture's
-|\end| command is found before the outer |\end| command (for example using
-bracing constructs or by writing the nested picture into a separate macro
-call).
-
-Consider using the |\tikzexternaldisable| method in case you'd like to skip
-selected pictures which do not meet the requirements.
-
-
-\subsection{A Word About Con\TeX t And Plain \TeX}
-
-Currently, the basic layer backend |\beginpgfgraphicnamed| $\dotsc$
-|\endpgfgraphicnamed| relies on \LaTeX\ only, so externalization is currently
-only supported for \LaTeX.
-%The library comes in three different versions, one for \LaTeX, one for Con\TeX
-%t and one for plain \TeX. For reasons of simplicity, examples in this manual
-%only refer to \LaTeX\ (especially |pdflatex|).
-
-
-\subsection{Externalizing Graphics}
-
-After loading the library, a call to |\tikzexternalize| is necessary to
-activate the externalization.
-%
-\begin{codeexample}[code only]
-\documentclass{article}
-% main document, called main.tex
-\usepackage{tikz}
-
-\usetikzlibrary{external}
-\tikzexternalize % activate!
-
-\begin{document}
-\begin{tikzpicture}
- \node {root}
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-
-A simple image is \tikz \fill (0,0) circle(5pt);.
-\end{document}
-\end{codeexample}
-
-The method works as follows: if the document is typeset normally, the library
-searches for replacement images for every picture. Filenames are generated
-automatically in the default configuration. In our case, the two file names
-will be |main-figure0| and |main-figure1|. If they exist, those images are
-simply included and the pictures as such are not processed. If graphics files
-do not exist, steps are taken to generate the missing ones. Since (currently)
-only one output file can be set, each missing image needs to be generated by a
-separate run of \LaTeX\ in which the |\jobname| is set to the desired image
-file name. In the default configuration |mode=convert with system call|, these
-commands are issued automatically by using the |\write18| method to call system
-commands. It is also possible to output every required file name or to generate
-a |makefile|; users will need to issue the required commands manually (or with
-|make|). The probably most comfortable way is to use the default configuration
-with
-%
-\begin{codeexample}[code only, tikz syntax=false]
-pdflatex -shell-escape main
-\end{codeexample}
-%
-\noindent which authorizes |pdflatex| to call itself recursively to generate
-the images. When it finishes, all images are generated and the document already
-includes them.
-
-From this point on, successive runs of \LaTeX\ will use the final graphics
-files, the pictures won't be used anymore.
-Section~\ref{section-libs-external-nopgf} contains details about how to submit
-such a file to environments where \pgfname\ is not available.
-
-\begin{command}{\tikzexternalize\oarg{optional arguments}}
- This command activates the externalization. It installs commands to replace
- every \tikzname-picture. It needs to be called before |\begin{document}|
- because it may need to install its separate shipout routine.
-
- The \meta{optional arguments} can be any of the keys described below.
-
- Note that the generation/modification of auxiliary files like |.aux|,
- |.toc| etc.\ is usually suppressed while a single image is externalized
- (details for |\label| support follow).
-
- It is also possible to write |\tikzexternalize|\marg{main job name} if the
- argument is delimited by curly braces. This case is mainly for backwards
- compatibility and is no longer necessary. Since it might be useful in rare
- circumstances, it is documented in section~\ref{sec:external:detail}.
-
- A detailed description about the process of externalization is provided in
- section~\ref{sec:external:detail}.
-
- \begin{command}{\tikzexternalrealjob}
- After the library is loaded, this macro will \emph{always} contain the
- correct main job's name (in the example above, it is |main|). It is to
- be used instead of |\jobname| when the externalization is in effect.
- \end{command}
- %
- \begin{command}{\pgfactualjobname}
- Once |\tikzexternalize| has been called, |\pgfactualjobname| contains
- the name of the currently generated output file (which may be |main| or
- |main-figure0| or |main-figure1| in our example above).
- \end{command}
- %
- \begin{command}{\jobname}
- The value of |\jobname| is one of |\tikzexternalrealjob| or
- |\pgfactualjobname|, depending on the configuration. In short: if
- auxiliary file support (|\label| and |\ref|) is activated,
- |\jobname=\tikzexternalrealjob| (since that's the base file name of
- auxiliary files).
- \end{command}
-\end{command}
-
-\begin{key}{/tikz/external/system call=\marg{template}}
-\label{extlib:systemcall:option}
- A template string used to generate system calls. Inside of \marg{template},
- the macro |\image| can be used as placeholder for the image which is about
- to be generated while |\texsource| contains the main file name (in truth,
- it contains |\input|\marg{main file name}, but that doesn't matter).
-
- The default depends on the value of |\pgfsysdriver|. For
- |pgfsys-pdftex.def|, it is
- %
-\begin{codeexample}[code only]
-\tikzset{external/system call={pdflatex \tikzexternalcheckshellescape -halt-on-error
- -interaction=batchmode -jobname "\image" "\texsource"}}
-\end{codeexample}
- %
- \noindent where \declareandlabel{\tikzexternalcheckshellescape} inserts the
- value of the configuration key |shell escape| if and only if the current
- document has been typeset with |-shell-escape|\footnote{Note that this is
- always true for the default configuration. This security consideration
- applies mainly for \texttt{mode=list and make} which will also work
- \emph{without} shell escapes.}.
-
- Other drivers result in slightly different calls. There is support for
- |lualatex|, |xelatex|, and |dvips|. The precise values are written to the
- |.log| file as soon as you attempt to compile a document.
-
- The argument \marg{template} will be expanded using |\edef|, so any control
- sequences will be expanded. During this evaluation, `|\\|' will result in a
- normal backslash, `|\|'. Furthermore, double quotes `|"|', single quotes
- `|'|', semicolons and dashes `|-|' will be made to normal characters if any
- package uses them as macros. This ensures compatibility with the |german|
- package, for example.
-\end{key}
-
-\begin{key}{/tikz/external/shell escape=\marg{command-line arg} (initially -shell-escape)}
- Contains the command line option for |latex| which enables the |\write18|
- feature. For \TeX-Live, this is |-shell-escape|. For MiK\TeX, you should
- use |\tikzexternalize[shell escape=-enable-write18]|.
-\end{key}
-
-
-\subsubsection{Support for Labels and References In External Files}
-
-The |external| library comes with extra support for |\label| and |\ref| (and
-other commands which usually store information in the |.aux| file) inside an
-external files.
-
-In particular, it supports the two use-cases
-%
-\begin{enumerate}
- \item[a)] |\ref| to something in the main document inside an externalized
- graphics or
- \item[b)] |\label| in the externalized graphics which is referenced in the
- main document.
-\end{enumerate}
-
-The only restriction is that you need to compile your document multiple times
-(as usual for references).
-
-\paragraph{NOTE:}
-support for a) is unavailable for versions up to and including \pgfname\ 3.0.1.
-
-\begin{key}{/tikz/external/aux in dpth=\marg{boolean} (initially true)}
- Allows to enable or disable the feature which handles references and labels
- as part of image externalization. Disabling it will safe one |\newwrite|
- command, i.e.\ a write register.
-
- Also see the |disable dependency files| feature.
-
- Here are some implementation details on how references within/from external
- graphics work for those who would like to know the details:
-
- For point a), a |\ref| inside of an externalized graphics works by reading
- the main document's |.aux| file. To this end, the standard
- |mode=convert with system call| detects such references and reschedules the
- externalization to |\end{document}.|\footnote{Note that this requires the
- \texttt{atveryend} package. The purpose to reschedule the externalization
- is to access the main job's aux file, but only after it has been written
- completely.} Other values of |mode| require just one attempt to externalize
- the picture.
-
- Note that |\pageref| is not supported (sorry).
-
- Point b) works as follows: a |\label| inside of an externalized graphics
- causes the |external| library to generate separate auxiliary files for every
- external image. These files are called \meta{imagename}|.dpth|. The
- extension |.dpth| indicates that the file also contains the image's depth
- (the |baseline| key of \tikzname). Furthermore, anything which would have
- been written to an |.aux| file will be redirected to the |.dpth| file --
- but only things which occur inside of the externalized |tikzpicture|
- environment. When the main document loads the image, it will copy the
- |.dpth| file into the main |.aux| file. Then, successive compilations of
- the main document contain the external |\label| information. In other
- words, a |\label| in an external graphics needs the following work flow:
- %
- \begin{enumerate}
- \item The external graphics needs to be generated together with its
- |.dpth| (usually automatically by \tikzname).
- \item The main document includes the external graphics and copies the
- |.dpth| content into its main |.aux| file.
- \item The main document needs to be translated once again to re-read
- its |.aux| file\footnote{Note that it is not possible to activate
- the content of an auxiliary file after \texttt{\textbackslash
- begin\{document\}} in \LaTeX.}.
- \end{enumerate}
-
- This does also work if a |\label|/|\ref| combination is implemented itsself
- by a |tikzpicture| (a feature offered by |pgfplots|).
-\end{key}
-
-
-\subsubsection{Customizing the Generated File Names}
-
-The default filename for externalized graphics is `\meta{real file
-name}|-figure_|\meta{number}' where \meta{number} ranges from $0$ to whatever
-is required. However, there are a couple of ways to change the generated
-filenames:
-%
-\begin{itemize}
- \item Changing the overall file name using a |prefix|,
- \item Changing the file name for a single figure using
- |\tikzsetnextfilename|,
- \item Changing the file name for a restricted set of figures using
- |figure name|.
-\end{itemize}
-
-\begin{key}{/tikz/external/prefix=\marg{file name prefix} (initially empty)}
- A shortcut for |\tikzsetexternalprefix|\marg{file name prefix}, see below.
-\end{key}
-
-\begin{command}{\tikzsetexternalprefix\marg{file name prefix}}
- Assigns a common prefix used by all file names. For example,
- %
-\begin{codeexample}[code only]
-\tikzsetexternalprefix{figures/}
-\end{codeexample}
- %
- will prepend |figures/| to every external graphics file name.
-
- Please note that |\tikzsetexternalprefix| is the \emph{only} way to assign
- a prefix in case you want to prepare your document for environments where
- \pgfname\ is not installed (see section~\ref{section-libs-external-nopgf}).
-\end{command}
-
-\begin{command}{\tikzsetnextfilename\marg{file name}}
- Sets the file name for the \emph{next} \tikzname\ picture or |\tikz| short
- command. It will \emph{only} be used for the next picture.
-
- Pictures for which no explicit file name has been set (or the next file
- name is empty) will get automatically generated file names.
-
- Please note that |prefix| will still be prepended to \marg{file name}.
- %
-\begin{codeexample}[code only]
-\documentclass{article}
-% main document, called main.tex
-\usepackage{tikz}
-
-\usetikzlibrary{external}
-\tikzexternalize[prefix=figures/] % activate
-
-\begin{document}
-
-\tikzsetnextfilename{trees}
-\begin{tikzpicture} % will be written to 'figures/trees.pdf'
- \node {root}
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-
-\tikzsetnextfilename{simple}
-A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'figures/simple.pdf'
-
-\begin{tikzpicture} % will be written to 'figures/main-figure0.pdf'
- \draw[help lines] (0,0) grid (5,5);
-\end{tikzpicture}
-\end{document}
-\end{codeexample}
- %
-\begin{codeexample}[code only, tikz syntax=false]
-pdflatex -shell-escape main
-\end{codeexample}
- %
-\end{command}
-
-\begin{key}{/tikz/external/figure name=\marg{name}}
- Same as |\tikzsetfigurename|\marg{name}.
-\end{key}
-
-\begin{command}{\tikzsetfigurename\marg{name}}
- Changes the names of \emph{all} following figures. It is possible to change
- |figure name| during the document either using
- |\tikzset{external/figure name|=\marg{name}|}| or with this command. A
- unique counter will be used for each different \marg{name}, and each
- counter will start at $0$.
-
- The value of |prefix| will be applied after |figure name| has been
- evaluated.
- %
-\begin{codeexample}[code only]
-\documentclass{article}
-% main document, called main.tex
-\usepackage{tikz}
-
-\usetikzlibrary{external}
-\tikzexternalize % activate
-
-\begin{document}
-
-\begin{tikzpicture} % will be written to 'main-figure0.pdf'
- \node {root}
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-
-{
- \tikzsetfigurename{subset_}
- A simple image is \tikz \fill (0,0) circle(5pt);. % will be written to 'subset_0.pdf'
-
- \begin{tikzpicture} % will be written to 'subset_1.pdf'
- \draw[help lines] (0,0) grid (5,5);
- \end{tikzpicture}
-}% here, the old file name will be restored:
-
-\begin{tikzpicture} % will be written to 'main-figure1.pdf'
- \draw (0,0) -- (5,5);
-\end{tikzpicture}
-\end{document}
-\end{codeexample}
- %
- The scope of |figure name| ends with the next closing brace.
-
- Remark: Use |\tikzset{external/figure name/.add={prefix_}{_suffix_}}| to
- add a |prefix_| and a |_suffix_| to the actual value of |figure name|.
-\end{command}
-
-\begin{command}{\tikzappendtofigurename\marg{suffix}}
- Appends \meta{suffix} to the actual value of |figure name|.
-
- It is a shortcut for |\tikzset{external/figure name/.add={}|\marg{suffix}|}|
- (a shortcut which is also supported if \tikzname\ is not installed, see
- below).
-\end{command}
-
-
-\subsubsection{Remaking Figures or Skipping Figures}
-
-\begin{command}{\tikzpicturedependsonfile\marg{file name}}
- Adds a dependency for the \emph{next} picture which is about to be
- externalized. If the command is invoked within a picture environment, it
- adds a dependency for the surrounding picture. Dependencies are written
- into \meta{target file}|.dep| in the format
-
- \meta{target file}|.\tikzexternalimgextension: |\meta{file name}.
-
- The effect is that if \meta{file name} changes, the external graphics
- associated with the picture shall be remade.
-
- This command uses the contents of
- \declareandlabel{\tikzexternalimgextension} to check for graphics. If you
- encounter difficulties with image extensions, consider redefining this
- macro (after |\tikzexternalize|).
-
- \paragraph{Limitations:}
- this command is currently only supported for |mode=list and make| and the
- generated |makefile|.
-\end{command}
-
-\begin{command}{\tikzexternalfiledependsonfile\marg{external graphics}\marg{file name}}
- A variant of |\tikzpicturedependsonfile| which adds a dependency for an
- \meta{external graphics}. The argument \meta{external graphics} must be the
- path as it would have been generated by the |external| library, i.e.\ without
- file extension but including any prefixes.
-\end{command}
-
-\begin{key}{/tikz/external/disable dependency files}
- Allows to (irreversibly) disable the generation of file dependencies.
- Disabling it will safe one |\newwrite| command, i.e.\ a write register.
- Note that the write register is only allocated if the feature has been used
- at all. This key needs to be provided as argument to |\tikzexternalize| (or
- it needs to be set before calling |\tikzexternalize|).
-
- Also see the |aux in dpth| key.
-\end{key}
-
-\begin{key}{/tikz/external/force remake=\marg{boolean} (default true)}
- A boolean which is used to customize the up-to-date checks of all following
- figures. Every up-to-date check will fail, resulting in automatic
- regeneration of every following figure.
- %
-\begin{codeexample}[code only]
-\tikzset{external/force remake}
-\begin{tikzpicture}
- \draw (0,0) circle(5pt);
-\end{tikzpicture}
-\end{codeexample}
- %
- You can also use |force remake| inside of a local \TeX\ group to remake
- only selected pictures. The example
- %
-\begin{codeexample}[code only]
-\tikz \draw (0,0) -- (1,1);
-
-{
-\tikzset{external/force remake}
-\begin{tikzpicture}
- \draw (0,0) circle(5pt);
-\end{tikzpicture}
-}
-
-\tikz \draw (0,0) -- (1,1);
-\end{codeexample}
- will only apply |force remake| to the second figure.
-
- Up-to-date checks are applied for |mode=convert with system call| and the
- makefile generated by |mode=list and make|.
-\end{key}
-
-\begin{key}{/tikz/external/remake next=\marg{boolean} (default true)}
- A variant of |force remake| which applies only to the next image.
-\end{key}
-
-\begin{key}{/tikz/external/export next=\marg{boolean} (default true)}
- A boolean which can be used to disable the export mechanism for single pictures.
-\end{key}
-
-\begin{key}{/tikz/external/export=\marg{boolean} (initially true)}
- A boolean which can be used to disable the export mechanism for all
- pictures inside of the current \TeX-scope.
- %
-\begin{codeexample}[code only]
-\begin{document}
-\begin{tikzpicture} % will be exported
- ...
-\end{tikzpicture}
-
-{
-\tikzset{external/export=false}
-\begin{tikzpicture} % won't be exported
- ...
-\end{tikzpicture}
-...
-}
-
-\begin{tikzpicture} % will be exported
- ...
-\end{tikzpicture}
-\end{document}
-\end{codeexample}
- %
- For \LaTeX, the feature lasts until the next |\end|\marg{$\cdot$} (this
- holds for every call to |\tikzset|).
-\end{key}
-
-\begin{key}{/tikz/external/up to date check=\marg{choice} (initially md5)}
- The |external| lib has to decide when some existing figure is up-to-date.
- In such a case, it can be used without remaking it. Outdated pictures will
- be remade.
-
- The key |up to date check| allows to choose among a couple of heuristics
- which are supposed to catch the most important reasons to remake a figure.
-
- The |up to date check| can be overrule by any of the |force remake| or
- |remake next| keys: if one of them is true, the figure is not up-to-date.
-
- The choice \declare{simple} is based on the existence of the file: the file
- is up-to-date if and only if it exists.
-
- The choice \declare{md5} generates an MD5 checksum of the picture for which
- the up-to-date check is running. The MD5 is compared against the MD5 of the
- previous run, which, in turn, will be written into an extra file with the
- extension |.md5|. This file will be modified if and only if the MD5
- comparison indicates a difference. The MD5 computation is based on the
- pdf\TeX\ method |\pdfmdfivesum|. If it is unavailable for some reason, the
- choice |diff| will be used instead.
-
- The choice \declare{diff} is the same as MD5 -- except that it compares the
- picture content as-is instead of a hash. The |.md5| file will be used to
- compare an old version with the current one -- but its content is some
- ``normalized'' version of the picture for internal use.
-
- \paragraph{Attention:}
- the content--based strategies |md5| and |diff| operate on the picture
- content -- and only on the picture content. Here, ``picture content'' only
- includes the top--level tokens; no expansion is applied and no included
- files are part of the strategies. If you change preamble styles, you have
- to rebuild the figures manually (for example by deleting the generated
- graphics files). If you have include files, consider using
- |\tikzpicturedependsonfile| and its variants. Since this key provides
- heuristics, you should always remake your figures before you finally
- publish your document. Example: Suppose we have the following picture which
- depends on a command |\mycommand|:
- %
-\begin{codeexample}[code only]
-\def\mycommand{My comment}
-
-\begin{tikzpicture}
-
-\node at (0,0) {\mycommand};
-
-\end{tikzpicture}
-\end{codeexample}
- %
- What happens if you change ``My comment'' to ``My super comment''? Well,
- |external| will \emph{not} pick it up; you will need to handle this
- manually. However, if you modify anything between |\begin{tikzpicture}| and
- |\end{tikzpicture}|, the |external| library \emph{will} pick it up and
- regenerate the picture.
-
- The |up to date check| is applied for |mode=convert with system call| and
- |mode=list and make|.
-\end{key}
-
-\begin{command}{\tikzexternaldisable}
- Allows to disable the complete externalization. While |export next| will
- still collect the contents of picture environments, this command uninstalls
- the hooks for the |external| library completely. Thus, nested picture
- environments or environments where |\end{tikzpicture}| is not directly
- reachable won't produce compilation failures -- although it is not possible
- to externalize them automatically.
-
- The externalization remains disabled until the end of the next \TeX\ group
- (or environment) or until the next call to |\tikzexternalenable|.
-\end{command}
-
-\begin{command}{\tikzexternalenable}
- Re-enables a previously running externalization after |\tikzexternaldisable|.
-\end{command}
-
-
-\subsubsection{Customizing the Externalization}
-
-\begin{key}{/tikz/external/figure list=\marg{boolean} (initially true)}
- A boolean which configures whether a figure list shall be generated. A
- figure list is an output file named \marg{jobname}|.figlist| which is
- filled with file names of each figure, one per line.
-
- This file is not used by \TeX\ anymore, its purpose is to issue the
- required conversion commands |pdflatex -jobname |\marg{picture file name}
- \marg{main file} manually (or in a script). See
- section~\ref{sec:external:detail} for the details about the expected system
- call (or activate |mode=convert with system call| and inspect your log
- file).
- %
-\begin{codeexample}[code only]
-\documentclass{article}
-% main document, called main.tex
-\usepackage{tikz}
-
-\usetikzlibrary{external}
-\tikzexternalize[
- mode=graphics if exists,
- figure list=true,
- prefix=figures/]
-
-\begin{document}
-
-\tikzsetnextfilename{trees}
-\begin{tikzpicture}
- \node {root}
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-
-\tikzsetnextfilename{simple}
-A simple image is \tikz \fill (0,0) circle(5pt);.
-
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (5,5);
-\end{tikzpicture}
-\end{document}
-\end{codeexample}
-
-\begin{codeexample}[code only, tikz syntax=false]
-pdflatex main
-\end{codeexample}
- %
- generates |main.figlist| containing
- %
-\begin{codeexample}[code only, tikz syntax=false]
-figures/trees
-figures/simple
-figures/main-figure0
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/external/mode=\marg{choice} (initially convert with system call)}
- Configures what to do with \tikzname\ pictures (unless we are currently
- externalizing one particular image, in that case, these modes are ignored).
-
- The preconfigured mode |convert with system call| checks whether external
- graphics files are up-to-date and includes them if that is the case. Any
- picture which is not up-to-date will be generated automatically using a
- system call. The system call can be configured using the |system call|
- template. The up-to-date check is applied according to the
- |up to date check| key. As soon as |convert with system call| is set, the
- |figure list| will be disabled -- such a file is not required. In case you
- still need or want it, you can enable it after setting |mode|.
-
- Please note that system calls may be disabled for security reasons. For
- pdflatex, they can be enabled using
- %
-\begin{codeexample}[code only, tikz syntax=false]
-pdflatex -shell-escape
-\end{codeexample}
- %
- while other \TeX\ variants may need other switches. The feature is
- sometimes called |\write18|.
-
- The choice |only graphics| always tries to replace pictures with external
- graphics. It is an error if the graphics file does not exist.
-
- The choice |no graphics| (or, equivalently, |only pictures|) typesets
- \tikzname\ pictures without checking for external graphics.
-
- A mixture is |graphics if exists|, it checks whether a suitable graphics
- file exists and includes it if that is the case. If it does not exist, the
- picture is typeset using \TeX.
-
- Mode |list only| skips every \tikzname\ picture; it only generates the file
- \marg{main file}|.figlist| containing file names for every picture, the
- contents of any picture environment is thrown away and a replacement text
- is shown. This implies |figure list=true|. See also the |list and make|
- mode which includes available graphics.
-
- The mode |list and make| is similar to |list only|: it generates the same
- file \marg{main file}|.figlist|, but any images which exist already are
- included as graphics instead of ignoring them. Furthermore, this mode
- generates an additional file: \marg{main file}.makefile. This allows to use
- a work flow like
- %
-\begin{codeexample}[code only, tikz syntax=false]
-% step 1: generate main.makefile:
-pdflatex main
-% step 2: generate ALL graphics on 2 processors:
-make -j 2 -f main.makefile
-% step 3: include the graphics:
-pdflatex main
-\end{codeexample}
- %
- \noindent This last make method is optional: |list and make| just assumes
- that images are generated somehow (not necessarily with the generated
- makefile). The generated makefile allows parallel externalization of
- graphics on multi-core systems and it supports any file dependencies
- configured with |\tikzpicturedependsonfile|. Furthermore, it respects the
- |force remake| and |remake next| keys.
-\end{key}
-
-\begin{key}{/tikz/external/verbose IO=\marg{boolean} (initially true)}
- A boolean which configures whether I/O operations shall be listed in the
- logfile.
-\end{key}
-
-\begin{key}{/tikz/external/verbose optimize=\marg{boolean} (initially true)}
- A boolean which configures whether optimization operations shall be listed
- in the logfile.
-\end{key}
-
-\begin{key}{/tikz/external/verbose=\marg{boolean} (initially true)}
- Sets all verbosity flags to \meta{boolean}.
-\end{key}
-
-\begin{key}{/tikz/external/optimize=\marg{boolean} (initially true)}
- Configures whether the conversion process shall be optimized. This affects
- only the case when |\jobname| differs from the main file name, i.e.\ when
- single pictures are converted.
-
- In that case, the main file is compiled as usual -- but everything except
- the selected picture is thrown away. If optimization is enabled, all other
- pictures won't be processed at all. Furthermore, expensive commands which
- do not contribute to the selected picture will be thrown away as well.
-
- The default implementation discards |\includegraphics| commands which are
- \emph{not} inside of the selected picture to reduce conversion time.
-
- It is possible to add commands which shall be optimized away, see below.
-\end{key}
-
-\begin{key}{/tikz/external/optimize command away=\meta{\textbackslash command}\marg{required argument count}}
- Installs commands to optimize \meta{\textbackslash command} away. As is
- described above, optimization applies to the case when single pictures are
- converted: one usually doesn't need to process (probably expensive)
- commands which do not contribute to the selected picture.
-
- The argument \marg{required argument count} is either empty or a
- non-negative integer between $0$ and $9$. It denotes the number of
- arguments which should be consumed after \meta{\textbackslash command}. In
- any case, one argument in square brackets after the command will be
- recognized as well. To be more precise, the following cases for arguments
- of \meta{\textbackslash command} are supported:
- %
- \begin{enumerate}
- \item If \marg{required argument count} is empty (the default),
- \meta{\textbackslash command} may take one optional argument in
- square brackets and one in curly braces (which is also optional).
- \item If \marg{required argument count} is not empty,
- \marg{\textbackslash command} may take one optional argument in
- square brackets. Furthermore, it expects exactly \marg{required
- argument count} following arguments.
- \end{enumerate}
-
- Example:
- %
-\begin{codeexample}[code only]
-\tikzset{external/optimize command away=\includegraphics}
-\end{codeexample}
-
-\begin{codeexample}[code only]
-\newcommand{\myExpensiveMacro}[1]{Very expensive!}
-
-\tikzset{external/optimize command away=\myExpensiveMacro}
-\end{codeexample}
-
-\begin{codeexample}[code only]
-\newcommand{\myExpensiveMacroWithThreeArgs}[3]{Very expensive!}
-
-\tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{3}}
-\end{codeexample}
-
-\begin{codeexample}[code only]
-% A command with optional argument:
-\newcommand{\aFurtherExample}[3][]{Very expensive!}
-
-% consume only two arguments: the first optional one will be processed
-% anyway:
-\tikzset{external/optimize command away={\myExpensiveMacroWithThreeArgs}{2}}
-\end{codeexample}
- %
- The argument \meta{\textbackslash command} must be the name of a single
- macro. Any occurrence of this macro, together with its arguments, will be
- removed.
- %
-\begin{codeexample}[code only]
-\begin{tikzpicture}
- % this picture is currently converted!
-\end{tikzpicture}
-
-This here is outside of the converted picture and contains \myExpensiveMacro. It will be discarded.
-
-This call: \myExpensiveMacro[argument=value]{Argument} as well.
-And this here: \myExpensiveMacro{Argument} also.
-\end{codeexample}
-
- The default is to optimize |\includegraphics| away.
-
- This key is actually a style which sets the |optimize/install| and
- |optimize/restore| keys.
-\end{key}
-
-\begin{key}{/tikz/external/optimize/install}
- A command key which contains code to install optimizations. You can append
- code here (or clear the macro) if you need to modify the optimization.
-\end{key}
-
-\begin{key}{/tikz/external/optimize/restore}
- A command key which contains code to undo optimizations. You can append
- code here (or clear the macro) if you need to modify the optimization.
-\end{key}
-
-\begin{key}{/tikz/external/only named=\marg{boolean} (initially false)}
- If enabled, only pictures for which file names have been set explicitly
- using |\tikzsetnextfilename| will be considered, no file names will be
- generated automatically.
-\end{key}
-
-\begin{key}{/pgf/images/include external (initially \textbackslash pgfimage\{\#1\})}
-\index{External Graphics!Bounding Box Issues}
- This command key constitutes the public interface to exchange the
- |\includegraphics| command used for the image inclusion. If can be
- overwritten using |include external/.code=|\marg{\TeX\ code}.
-
- Its description can be found in the corresponding basic layer documentation
- on page~\pageref{pgf:includeexternalkey}.
-
- Just one example here: you can use
- %
-\begin{codeexample}[code only]
-\pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}}
-\end{codeexample}
- %
- to manually change the viewport (bounding box) for included graphics.
-
- Another example (of probably limited use) is
- %
-\begin{codeexample}[code only]
-\pgfkeys{/pgf/images/include external/.code={\href{file:#1}{\pgfimage{#1}}}}
-\end{codeexample}
- %
- \noindent which will generate a clickable hyperlink around the image.
- Clicking on it opens the single exported file\footnote{This requires all
- external graphics files in the same base directory as the main |.pdf|
- file.}.
-
- If you want to limit the effects of this key to just one externalized
- figure, use
- %
-\begin{codeexample}[code only]
-{
- \pgfkeys{/pgf/images/include external/.code={\includegraphics[viewport=0 0 211.28 175.686]{#1}}}
- \begin{tikzpicture}
- ...
- \end{tikzpicture}
-}% this brace ends the effect of `include external'
-\end{codeexample}
- %
-\end{key}
-
-\begin{command}{\tikzifexternalizing\marg{true code}\marg{false code}}
- This command can be used to check whether an image is currently written to
- its separate graphics file (if the ``grab'' procedure is running). If so,
- the \marg{true code} will be executed. If not, that means if the main
- document is being typeset normally, the \marg{false code} will be invoked.
-
- This command must be used \emph{after} |\tikzexternalize|.
-\end{command}
-
-\begin{command}{\tikzifexternalizingnext\marg{true code}\marg{false code}}
- Like |\tikzifexternalizing|, but this variant also checks if the next
- following figure is the one which is about to be written to its separate
- graphics file.
-\end{command}
-
-
-\subsubsection{Details About The Process}
-\label{sec:external:detail}
-
-The standard run |pdflatex |\meta{main document} causes the |external| library
-to check every occurrence of |\begin{tikzpicture}| and every |\tikz| short
-command. If it finds a picture which shall be exported, it queries the
-respective file name and checks whether the file exists already. If so, it
-includes the external graphics. If not, it requires an externalization which
-can be done automatically (the default), semi-automatically (with
-|mode=list and make|) or manually (by issuing the requires system calls
-somehow).
-
-The library can detect whether it runs in ``conversion mode'', i.e.\ if it
-should only process a single image. To do so, it checks whether the internal
-macro \declareandlabel{\tikzexternalrealjob} exists. If so, its contents is
-assumed to be \meta{main document} (without the suffix |.tex|). Usually, this
-macro is set by the conversion system call,
-%
-\begin{codeexample}[code only, tikz syntax=false]
-pdflatex -jobname "main-figure0" "\def\tikzexternalrealjob{main}\input{main}"
-\end{codeexample}
-%
-\noindent where |main-figure0| is the picture we are currently externalizing
-and |main.tex| is the main document.
-
-As soon as ``conversion mode'' has been detected, \pgfname\ changes the output
-routine. The complete file |main.tex| is processed as normal, but only the part
-of the desired picture will be written to the output file, in our case
-|main-figure0.pdf|. The rest of the document is silently thrown away. Of
-course, such a conversion process is quite expensive since we need to do it for
-every picture. Since everything except the current picture is thrown away, the
-library skips all other pictures. Furthermore, any |\includegraphics| commands
-which are outside of the converted \tikzname-picture will be skipped as well.
-Thus, the conversion process should be much faster than typesetting the
-complete document, but it still requires its time. Eventually, the call
-|\input{main}| returns and the picture is ready. From this point on, the
-external graphics will be used.
-
-There is another possibility to communicate \meta{main document} to the
-subprocess performing the externalization: namely to write
-`|\tikzexternalize{main}|' into the document. In this case, the conversion
-system call will be
-%
-\begin{codeexample}[code only, tikz syntax=false]
-pdflatex -jobname "main-figure0" "main"
-\end{codeexample}
-%
-\noindent and the contents of |\tikzexternalrealjob| is set automatically. This
-case is detected by |\tikzexternalize|, and the |system call| is updated
-automatically (by patching its |\texsource| template argument). It is not
-necessary to change the |system call| manually.
-
-The sequence in which system calls are performed and the decision whether they
-are issued automatically is governed by the |mode| key, consult its
-documentation for details.
-
-
-\subsection{Using External Graphics Without \textmd{\pgfname}\ Installed}
-\label{section-libs-external-nopgf}
-
-Given that every picture has been exported correctly, one may want to compile a
-file without \pgfname\ and \tikzname\ installed. \tikzname\ comes with a
-minimal package which contains just enough commands to replace every
-|tikzpicture| environment and the |\tikz| short command with the appropriate
-external graphics. It can be found at
-%
-\begin{codeexample}[code only, tikz syntax=false]
-latex/pgf/utilities/tikzexternal.sty
-\end{codeexample}
-%
-\noindent and needs to be used instead of |\usepackage{tikz}|. So, we comment
-|\usepackage{tikz}| and |\usetikzlibrary{external}|, load packages |graphicx|
-and |tikzexternal|, and finally our example from the beginning becomes
-%
-\begin{codeexample}[code only]
-\documentclass{article}
-% main document, called main.tex
-%\usepackage{tikz}
-
-\usepackage{graphicx}
-\usepackage{tikzexternal}
-
-%\usetikzlibrary{external}
-\tikzexternalize
-
-\begin{document}
-\begin{tikzpicture}
- \node {root}
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-
-A simple image is \tikz \fill (0,0) circle(5pt);.
-
-Furthermore, we might want to draw \tikz[baseline]\draw (0,-1) rectangle (1,1);
-\end{document}
-\end{codeexample}
-%
-\noindent where the following files are necessary to compile the document:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-tikzexternal.sty
-main.tex
-main-figure0.pdf
-main-figure1.pdf
-main-figure2.pdf
-\end{codeexample}
-%
-\noindent If there are any `|.dpth|' files, for example |main-figure2.dpth|,
-these files are also required. They contain information for the \tikzname\
-|baseline| option (or |\label|s inside external graphics).
-
-Just copy the |.sty| file into the directory of your |main.tex| file and use it
-as part of your document.
-
-Please keep in mind, that only |tikzpicture| environments and |\tikz| short
-images are available within the externalization framework. Additionally, calls
-to |\tikzset| and |\pgfkeys| won't lead to compilation errors because they are
-simply ignored. But since |pgfkeys| is not available, any option supplied to
-|\tikzexternalize| is \emph{ignored}.
-
-\paragraph{Attention:}
-Since the simple replacement |\usepackage{tikzexternal}| doesn't support the
-key--value interface, you \emph{need} to use |\tikzsetexternalprefix| instead
-of the |prefix| option and |\tikzsetfigurename| instead of the |figure name|
-option since |\tikzset| is not available in such a context.
-
-\paragraph{Remark:}
-Some of the features of this library are mainly useful to improve the speed of
-successive document compilations. In other words: you can't use all features in
-this context, keep it simple.
-
-
-\subsection{\texttt{eps} Graphics Export}
-
-It is also possible to use \eps\ graphics instead of \pdf\ files. There are
-different ways to produce them, for example to use |pdflatex| and call
-|pdftops -eps |\marg{pdf file} \marg{eps file} afterwards. You could add this
-command to the |system call| option.
-
-Alternatively, you can use |latex| and |dvips| for image conversion as is
-explained for the |system call| option, see
-page~\pageref{extlib:systemcall:option}. See the documentation for the basic
-level externalization in section~\ref{section-external} for restrictions of
-other drivers.
-
-
-\subsection{Bitmap Graphics Export}
-
-Occasionally, you may have an extremely large graphics which takes long times
-to render. It might be interesting to generate a bitmap (raster) image, which
-displays much faster (for example in a presentation). I have used this feature
-to speed-up the display of large shadings.
-
-The |external| library can be customized to export bitmap images -- with the
-help of external programs. Due to the dependence of external programs, you may
-need to adjust these commands manually. For example, on my computer, the
-ImageMagick Suite is installed which comes with the |convert| tool. Together
-with |pdflatex|, I can define the following style:
-%
-\begin{codeexample}[code only]
-\tikzset{
- % Defines a custom style which generates BOTH, .pdf and .png export
- % but prefers the .png on inclusion.
- %
- % This style is not pre-defined, you may need to copy-paste and
- % adjust it.
- png export/.style={
- external/system call/.add=
- {}
- {; convert -density 300 -transparent white "\image.pdf" "\image.png"},
- %
- /pgf/images/external info,
- /pgf/images/include external/.code={%
- \includegraphics
- [width=\pgfexternalwidth,height=\pgfexternalheight]
- {##1.png}%
- },
- }
-}
-\end{codeexample}
-%
-\noindent The example above defines a new style called `|png export|' which,
-when it is set with |\tikzset{png export}| somewhere in the document, modifies
-the configuration for both file generation and file input. The file generation
-is modified by appending the ImageMagick command to |system call| (separated by
-`|;|' as usual on Linux). This is, in principle, enough to generate a |.png|
-file. The |include external| command is overwritten such that it uses the
-|.png| file instead of the |.pdf| file (which exists as well in the
-configuration above). But since a |.png| file can have a much higher resolution
-than the desired image dimensions, we have to add |width| and |height|
-explicitly. Usually, the |external| library does not provide size information
-(it is unnecessary for |.pdf| or |.eps| since these formats have their bounding
-box information). To enable size information, the style uses the
-|external info| key, which, in turn, provides the |\pgfexternalwidth| and
-|\pgfexternalheight| commands.
-
-Now we can use |\tikzset{png export}| either document-wide or just for one
-particular image. The configuration remains in effect until the end of the
-current environment (or until the next closing curly brace `|}|').
-
-\begin{key}{/pgf/images/external info=\marg{boolean} (initially false)}
- If this key is activated, the size for any externalized image will be
- stored explicitly into the associated |.dpth| file.
-
- When the file is included by |\pgfincludeexternalgraphics| (or
- automatically by the |external| library), the width is available as
- \declareandlabel{\pgfexternalwidth} and the height as
- \declareandlabel{\pgfexternalheight}.
-\end{key}
-
-
-\subsection{Compatibility Issues}
-
-\subsubsection{References In External Pictures}
-
-It is allowed if a picture contains references, for example
-|\tikz \node {Reference to \ref{a:label}};|.
-
-There is just one issue: if the main job is currently compiling, its |.aux|
-file is not in its final state (even worse: it may not be readable at all). The
-picture externalization, however, needs the main |.aux| file to query any
-references.
-
-Thus, you \emph{will} need to invoke
-|pdflatex -jobname |\meta{image}| |\meta{mainfile} \emph{manually}
-for any image which contains references.
-
-This problem arises only for |mode=convert with system call|. In this case,
-the |external| library creates a special |\jobname.auxlock| file to check
-whether the main |.aux| file is currently usable.
-
-
-\subsubsection{Compatibility With Other Libraries or Packages}
-
-The |external| library has the following compatibility issues:
-%
-\begin{enumerate}
- \item The |external| library comes with special support for
- |\usetikzlibrary{fadings}|: the |fadings| library may define local
- pictures which would be externalized (although they shouldn't). There
- is special handling to suppress this bug if |\tikzexternalize| is
- called \emph{after} |\usetikzlibrary{fadings}| or if all fadings are
- defined \emph{before} |\tikzexternalize|.
- \item Problems have been reported when using |\tikzexternalize| (or the
- basic layer externalization) together with |\usepackage{glossary}|.
- This problem disappears if |\tikzexternalize| is called \emph{before}
- |\usepackage{glossary}|.
- \item Problems with |\usepackage{pdfpages}| and |\usepackage{vmargin}|: The
- |external| library replaces the current shipout routine of \TeX\ during
- its externalization. This might raise problems with other packages
- which also manipulate the shipout routine (like the mentioned ones). To
- fix those problems, use
- %
-\begin{codeexample}[code only]
-
-\usetikzlibrary{external}
-
-\tikzifexternalizing{%
- % don't include package XYZ here
-}{%
- \usepackage{pdfpages}
- \usepackage{vmargin}
- ...
-}%
-\end{codeexample}
- %
- This uses the requested packages for the main document, but not for the
- single, exported graphics.
-\end{enumerate}
-
-In general, the |\tikzifexternalizing| feature might be used to solve package
-conflicts and the |\tikzexternaldisable| and |\tikzexternalenable| features can
-be used to solve problems with single pictures.
-
-
-\subsubsection{Compatibility With Bounding Box Restrictions}
-
-Bounding box restrictions provide no problem when used with \eps\ graphics.
-However, they pose problems for |pdflatex|, so you may need to use the
-|latex|/|dvips| combination if you use bounding box restrictions and
-externalization. Currently, the only possibility for bounding box restrictions
-and |pdflatex| is to use a combination of |trim left|/|trim right|/|baseline|:
-these keys do not \emph{really} truncate the bounding box, they only store
-horizontal and vertical shifts (also see the |trim lowlevel| key in this
-context).
-
-
-\subsubsection{Interoperability With The Basic Layer Externalization}
-
-This library is fully compatible with
-|\beginpgfgraphicnamed|$\dotsc$|\endpgfgraphicnamed| environments. However, you
-will need to use the |export next=false| key to avoid conflicts:
-%
-\begin{codeexample}[code only]
-\beginpgfgraphicnamed{picture4}
-\tikzset{external/export next=false}
-\begin{tikzpicture}
- \draw (0,0) -- (4,4);
-\end{tikzpicture}
-\endpgfgraphicnamed
-\end{codeexample}
-%
-Please keep in mind that file prefixes do not apply to the basic layer.
-}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fadings.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fadings.tex
deleted file mode 100644
index 3b0784e441..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fadings.tex
+++ /dev/null
@@ -1,51 +0,0 @@
-% Copyright 2018 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{Fading Library}
-\label{section-library-fadings}
-
-\begin{pgflibrary}{fadings}
- The package defines a number of fadings, see
- Section~\ref{section-tikz-transparency} for an introduction. The
- \tikzname\ version defines special \tikzname\ commands for creating
- fadings. These commands are explained in
- Section~\ref{section-tikz-transparency}.
-\end{pgflibrary}
-
-\newcommand\fadingindex[1]{%
- \index{#1@\protect\texttt{#1} fading}%
- \index{Fadings!#1@\protect\texttt{#1}}%
- \texttt{#1}&
- \begin{tikzpicture}[baseline=5mm-.5ex]
- \fill [black!20] (0,0) rectangle (1,1);
- \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (1,1);
-
- \fill [path fading=#1,blue] (0,0) rectangle (1,1);
- \end{tikzpicture} \\[4.5mm]
-}
-
-\noindent
-\begin{tabular}{ll}
- \emph{Fading name} & \emph{Example (solid blue faded on checkerboard)} \\[1mm]
- \fadingindex{west}
- \fadingindex{east}
- \fadingindex{north}
- \fadingindex{south}
- \fadingindex{circle with fuzzy edge 10 percent}
- \fadingindex{circle with fuzzy edge 15 percent}
- \fadingindex{circle with fuzzy edge 20 percent}
- \fadingindex{fuzzy ring 15 percent}
-\end{tabular}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fit.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fit.tex
deleted file mode 100644
index f5189a3cb1..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fit.tex
+++ /dev/null
@@ -1,161 +0,0 @@
-% 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{Fitting Library}
-\label{section-library-fit}
-
-\begin{tikzlibrary}{fit}
- The library defines (currently only two) options for fitting a node so that
- it contains a set of coordinates.
-\end{tikzlibrary}
-
-When you load this library, the following options become available:
-
-\begin{key}{/tikz/fit=\meta{coordinates or nodes}}
- This option must be given to a |node| path command. The \meta{coordinates
- or nodes} should be a sequence of \tikzname\ coordinates or node names,
- one directly after the other without commas (like with the
- |plot coordinates| path operation). Examples are |(1,0) (2,2)| or
- |(a) (1,0) (b)|, where |a| and |b| are nodes.
-
- For this sequence of coordinates, a minimal bounding box is computed that
- encompasses all the listed \meta{coordinates or nodes}. For coordinates in
- the list, the bounding box is guaranteed to contain this coordinate, for
- nodes it is guaranteed to contain the |east|, |west|, |north| and |south|
- anchors of the node. In principle (the details will be explained in a
- moment), things are now set up such that the text box of the node will be
- exactly this bounding box.
-
- Here is an example: We fit several points in a rectangular node. By setting
- the |inner sep| to zero, we see exactly the text box of the node. Then we
- fit these points again in a circular node. Note how the circle encompasses
- exactly the same bounding box.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fit}}]
-\begin{tikzpicture}[inner sep=0pt,thick,
- dot/.style={fill=blue,circle,minimum size=3pt}]
- \draw[help lines] (0,0) grid (3,2);
- \node[dot] (a) at (1,1) {};
- \node[dot] (b) at (2,2) {};
- \node[dot] (c) at (1,2) {};
- \node[dot] (d) at (1.25,0.25) {};
- \node[dot] (e) at (1.75,1.5) {};
-
- \node[draw=red, fit=(a) (b) (c) (d) (e)] {box};
- \node[draw,circle,fit=(a) (b) (c) (d) (e)] {};
-\end{tikzpicture}
-\end{codeexample}
-
- Every time the |fit| option is used, the following style is also applied to
- the node:
- %
- \begin{stylekey}{/tikz/every fit (initially \normalfont empty)}
- Set this style to change the appearance of a node that uses the |fit|
- option.
- \end{stylekey}
-
- The exact effects of the |fit| option are the following:
- %
- \begin{enumerate}
- \item A minimal bounding box containing all coordinates is computed.
- Note that if a coordinate like |(a)| is used that contains a node
- name, this has the same effect as explicitly providing the
- |(a.north)| and |(a.south)| and |(a.west)| and |(a.east)|. If you
- wish to refer only to the center of the |a| node, use |(a.center)|
- instead.
- \item The |text width| option is set to the width of this bounding box.
- \item The |align=center| option is set.
- \item The |anchor| is set to |center|.
- \item The |at| position of the node is set to the center of the
- computed bounding box.
- \item After the node has been typeset, its height and depth are
- adjusted such that they add up to the height of the computed
- bounding box and such that the text of the node is vertically
- centered inside the box.
- \end{enumerate}
- %
- The above means that, generally speaking, if the node contains text like
- |box| in the above example, it will be centered inside the box. It will be
- difficult to put the text elsewhere, in particular, changing the |anchor|
- of the node will not have the desired effect. Instead, what you should do
- is to create a node with the |fit| option that does not contain any text,
- give it a name, and then use normal nodes to add text at the desired
- positions. Alternatively, consider using the |label| or |pin| options.
-
- Suppose, for instance, that in the above example we want the word ``box''
- to appear inside the box, but at its top. This can be achieved as follows:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fit}}]
-\begin{tikzpicture}[inner sep=0pt,thick,
- dot/.style={fill=blue,circle,minimum size=3pt}]
- \draw[help lines] (0,0) grid (3,2);
- \node[dot] (a) at (1,1) {};
- \node[dot] (b) at (2,2) {};
- \node[dot] (c) at (1,2) {};
- \node[dot] (d) at (1.25,0.25) {};
- \node[dot] (e) at (1.75,1.5) {};
-
- \node[draw=red,fit=(a) (b) (c) (d) (e)] (fit) {};
- \node[below] at (fit.north) {box};
-\end{tikzpicture}
-\end{codeexample}
-
- Here is a real-life example that uses fitting:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fit,shapes.geometric}}]
-\begin{tikzpicture}
- [vertex/.style={minimum size=2pt,fill,draw,circle},
- open/.style={fill=none},
- sibling distance=1.5cm,level distance=.75cm,
- every fit/.style={ellipse,draw,inner sep=-2pt},
- leaf/.style={label={[name=#1]below:$#1$}},auto]
-
- \node [vertex] (root) {}
- child { node [vertex,open] {}
- child { node [vertex,open] {}
- child { node [vertex] (b's parent) {}
- child { node [vertex] {}
- child { node [vertex,leaf=d] {} }
- child { node [vertex,leaf=e] {} } }
- child { node [vertex,leaf=b] {} } }
- child { node [vertex,leaf=a] {} } }
- child { node [coordinate] {}
- child[missing]
- child { node [vertex] (f's parent) {}
- child { node [vertex,leaf=c] {} }
- child { node [vertex,leaf=f] {} } } }
- edge from parent node {$\rho$} };
-
- \node [fit=(d) (e) (b) (b's parent),label=above left:$F^{(b,R)}$] {};
- \node [fit=(c) (f) (f's parent),label=above right:$F^{(c,R)}$] {};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/rotate fit=\meta{angle} (initially 0)}
- This key fits \meta{coordinates or nodes} inside a node that is rotated by
- \meta{angle}. As a side effect, it also sets the |/tikz/rotate| key.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fit}}]
-\begin{tikzpicture}[inner sep=0pt,thick,
- dot/.style={fill=blue,circle,minimum size=3pt}]
- \draw[help lines] (0,0) grid (3,2);
- \node[dot] (a) at (1,1) {};
- \node[dot] (b) at (2,2) {};
- \node[dot] (c) at (1,2) {};
- \node[dot] (d) at (1.25,0.25) {};
- \node[dot] (e) at (1.75,1.5) {};
- \node[draw, fit=(a) (b) (c) (d) (e)] {};
- \node[draw=red, rotate fit=30, fit=(a) (b) (c) (d) (e)] {};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fixedpoint.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fixedpoint.tex
deleted file mode 100644
index 37d20d13a3..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fixedpoint.tex
+++ /dev/null
@@ -1,120 +0,0 @@
-% Copyright 2019 by Mark Wibrow
-%
-% 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{Fixed Point Arithmetic Library}
-
-\begin{pgflibrary}{fixedpointarithmetic}
- This library provides an interface to the \LaTeX{} package |fp| for fixed
- point arithmetic. In addition to loading this library you must ensure |fp|
- is loaded, otherwise errors will occur.
-\end{pgflibrary}
-
-
-\subsection{Overview}
-
-Whilst the mathematical engine that comes with \pgfname{} is reasonably fast
-and flexible when it comes to parsing, the accuracy tends to be fairly low,
-particularly for expressions involving many operations chained together. In
-addition the range of values that can be computed is very small:
-$\pm16383.99999$. Conversely, the |fp| package has a reasonably high accuracy,
-and can perform computations over a wide range of values (approximately
-$\pm9.999\times10^{17}$), but is comparatively slow and not very flexible,
-particularly regarding parsing.
-
-This library enables the combination of the two: the flexible parser of the
-\pgfname{} mathematical engine with the evaluation accuracy of |fp|. There are,
-however, a number of important points to bear in mind:
-%
-\begin{itemize}
- \item Whilst |fp| supports very large numbers, \pgfname{} and \tikzname{}
- do not. It is possible to calculate the result of |2^20| or
- |1.2e10+3.4e10|, but it is not possible to use these results in
- pictures directly without some ``extra work''.
- \item The \pgfname{} mathematical engine will still be used to evaluate
- lengths, such as |10pt| or |3em|, so it is not possible for an length
- to exceed the range of values supported by \TeX-dimensions
- ($\pm16383.99999$pt), even though the resulting expression is within
- the range of |fp|. So, for example, one can calculate |3cm*10000|, but
- not |3*10000cm|.
- \item Not all of the functions listed in Section~\ref{pgfmath-syntax}, have
- been mapped onto |fp| equivalents. Of those that have been, it is not
- guaranteed that functions will perform in the same way as they do in
- \pgfname. Reference should be made to the documentation for |fp|.
- \item In \pgfname, trigonometric functions such as |sin| and |cos| assume
- arguments are in degrees, and functions such as |asin| and |acos|
- return results in degrees. Although |fp| uses radians for such
- functions, \pgfname{} automatically converts arguments from degrees to
- radians, and converts results from radians to degrees, to ensure
- everything ``works properly''.
- \item The overall speed will actually be slower than using \pgfname{}
- mathematical engine. The calculating power of |fp| comes at the cost of
- an increased processing time.
-\end{itemize}
-
-
-\subsection{Using Fixed Point Arithmetic in PGF and \tikzname}
-
-The following key is provided to use |fp| in \pgfname{} and \tikzname:
-
-\begin{key}{/pgf/fixed point arithmetic=\meta{options}}
-\keyalias{tikz}
- This key will set the key path to |/pgf/fixed point|, and execute
- \meta{options}. Then it will install the necessary commands so that the
- \pgfname{} parser will use |fp| to perform calculations. The best way to
- use this key is as an argument to a scope or picture. This means that |fp|
- does not always have to be used, and \pgfname{} can use its own
- mathematical engine at other times, which can lead to a significant
- reduction in the time for a document to compile.
-\end{key}
-
-Currently there are only a few keys key supported for \meta{options}:
-
-\begin{key}{/pgf/fixed point/scale results=\meta{factor}}
- As noted above, |fp| can process a far greater range of numbers than
- \pgfname{} and \tikzname{}. In order to use results from |fp| in a
- |{pgfpicture}| or a |{tikzpicture}| they need to be scaled. When this key
- is used \pgfname{} will scale results of any evaluation by \meta{factor}.
- However, as it is not desirable for every part of every expression to be
- scaled, scaling will only take place if a special prefix |*| is used. If
- |*| is used at the beginning of an expression the evaluation of the
- expression will evaluated and then multiplied by \meta{factor}.
- %
-\begin{codeexample}[preamble={\usepgflibrary{fixedpointarithmetic}}]
-\begin{tikzpicture}[fixed point arithmetic={scale results=10^-6}]
-\draw [help lines] grid (3,2);
-\draw (0,0) -- (2,2);
-\draw [red, line width=4pt] (*1.0e6,0) -- (*3.0e6,*2.0e6);
-\end{tikzpicture}
-\end{codeexample}
-
- A special case of scaling involves plots of data containing large numbers
- from files. It is possible to ``pre-process'' a file, typically using the
- application that generates the data, to either precede the relevant column
- with |*| or to perform the scaling as part of the calculation process.
- However, it may be desirable for the data in a plot to appear in a table as
- well, so, two files would be required, one pre-processed for plotting, and
- one not. This extra work may be undesirable so the following keys are
- provided:
-
- \begin{key}{/pgf/fixed point/scale file plot x=\meta{factor}}
- This key will scale the first column of data read from a file before it
- is plotted. It is independent of the |scale results| key.
- \end{key}
-
- \begin{key}{/pgf/fixed point/scale file plot y=\meta{factor}}
- This key will scale the second column of data read from a file before
- it is plotted.
- \end{key}
-
- \begin{key}{/pgf/fixed point/scale file plot z=\meta{factor}}
- This key will scale the third column of data read from a file before it
- is plotted.
- \end{key}
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-folding.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-folding.tex
deleted file mode 100644
index a979470333..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-folding.tex
+++ /dev/null
@@ -1,255 +0,0 @@
-% 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{Paper-Folding Diagrams Library}
-\label{section-calender-folding}
-
-\begin{tikzlibrary}{folding}
- This library defines pic types for creating paper-folding diagrams. Many
- thanks to Nico van Cleemput for providing most of the code.
-\end{tikzlibrary}
-
-Here is a big example that produces a diagram for a calendar:
-%
-\begin{codeexample}[
- leave comments,
- preamble={\usetikzlibrary{calendar,folding}},
-]
-\sffamily\scriptsize
-\tikz \pic [
- transform shape,
- every calendar/.style={
- at={(-8ex,4ex)},
- week list,
- month label above centered,
- month text=\bfseries\textcolor{red}{\%mt} \%y0,
- if={(Sunday) [black!50]}
- },
- folding line length=2.5cm,
- face 1={ \calendar [dates=\the\year-01-01 to \the\year-01-last];},
- face 2={ \calendar [dates=\the\year-02-01 to \the\year-02-last];},
- face 3={ \calendar [dates=\the\year-03-01 to \the\year-03-last];},
- face 4={ \calendar [dates=\the\year-04-01 to \the\year-04-last];},
- face 5={ \calendar [dates=\the\year-05-01 to \the\year-05-last];},
- face 6={ \calendar [dates=\the\year-06-01 to \the\year-06-last];},
- face 7={ \calendar [dates=\the\year-07-01 to \the\year-07-last];},
- face 8={ \calendar [dates=\the\year-08-01 to \the\year-08-last];},
- face 9={ \calendar [dates=\the\year-09-01 to \the\year-09-last];},
- face 10={\calendar [dates=\the\year-10-01 to \the\year-10-last];},
- face 11={\calendar [dates=\the\year-11-01 to \the\year-11-last];},
- face 12={\calendar [dates=\the\year-12-01 to \the\year-12-last];}
-] {dodecahedron folding};
-\end{codeexample}
-
-The foldings are sorted by number of faces.
-
-\begin{pictype}{tetrahedron folding}{}
- This pic type draws a folding diagram for a tetrahedron. The following keys
- influence the pic:
- %
- \begin{key}{/tikz/folding line length=\meta{dimension}}
- Sets the length of the base line for folding. For the dodecahedron this
- is the length of all the sides of the pentagons.
- \end{key}
- %
- \begin{key}{/tikz/face 1=\meta{code}}
- The \meta{code} is executed for the first face of the dodecahedron.
- When it is executed, the coordinate system will have been shifted and
- rotated such that it lies at the middle of the first face of the
- dodecahedron.
- \end{key}
- %
- \begin{key}{/tikz/face 2=\meta{code}}
- Same as |face 1|, but for the second face.
- \end{key}
- %
- \begin{key}{/tikz/face 3=\meta{code}}
- \end{key}
- %
- \begin{key}{/tikz/face 4=\meta{code}}
- \end{key}
- %
- There are further similar options for more faces (for commands shown
- later).
-
- Here is a simple example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic [
- transform shape,
- folding line length=6mm,
- face 1={ \node[red] {1};},
- face 2={ \node {2};},
- face 3={ \node {3};},
- face 4={ \node {4};}
-] {tetrahedron folding};
-\end{codeexample}
-
- The appearance of the cut and folding lines can be influenced using the
- following styles:
- %
- \begin{stylekey}{/tikz/every cut (initially \normalfont empty)}
- Executed for every line that should be cut using scissors.
- \end{stylekey}
- %
- \begin{stylekey}{/tikz/every fold (initially help lines)}
- Executed for every line that should be folded.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic[
- every cut/.style=red,
- every fold/.style=dotted,
- folding line length=6mm
-] { tetrahedron folding };
-\end{codeexample}
- \end{stylekey}
-
- There is one style that is mainly useful for the present documentation:
- %
- \begin{stylekey}{/tikz/numbered faces}
- Sets |face |\meta{i} to |\node {|\meta{i}|};| for all~$i$.
- \end{stylekey}
-\end{pictype}
-
-\begin{pictype}{tetrahedron truncated folding}{}
- A folding of a truncated tetrahedron.
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { tetrahedron truncated folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{cube folding}{}
- A folding of a cube.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { cube folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{cube truncated folding}{}
- A folding of a truncated cube.
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { cube truncated folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{octahedron folding}{}
- A folding of an octahedron.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { octahedron folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{octahedron folding}{}
- A folding of a truncated octahedron.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { octahedron truncated folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{dodecahedron folding}{}
- A folding of a dodecahedron.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { dodecahedron folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{dodecahedron' folding}{}
- This is an alternative folding of a dodecahedron.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { dodecahedron' folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{cuboctahedron folding}{}
- A folding of a cuboctahedron.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { cuboctahedron folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{cuboctahedron truncated folding}{}
- A folding of a truncated cuboctahedron.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { cuboctahedron truncated folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{icosahedron folding}{}
- A folding of an icosahedron.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { icosahedron folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{rhombicuboctahedron folding}{}
- A folding of an rhombicuboctahedron.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { rhombicuboctahedron folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{snub cube folding}{}
- A folding of a snub cube.
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { snub cube folding };
-\end{codeexample}
- %
-\end{pictype}
-
-\begin{pictype}{icosidodecahedron folding}{}
- A folding of an icosidodecahedron.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{folding}}]
-\tikz \pic [folding line length=6mm, numbered faces, transform shape]
- { icosidodecahedron folding };
-\end{codeexample}
- %
-\end{pictype}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fpu.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fpu.tex
deleted file mode 100644
index 6c0f62f5f5..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-fpu.tex
+++ /dev/null
@@ -1,714 +0,0 @@
-% Copyright 2019 by Christian Feuersaenger
-%
-% 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{Floating Point Unit Library}
-\label{pgfmath-floatunit}
-\label{section-library-fpu}
-
-{\noindent {\emph{by Christian Feuersänger}}}
-
-\begingroup
-\pgfqkeys{/pgf/number format}{sci}
-\pgfkeys{/pgf/fpu}
-
-\begin{pgflibrary}{fpu}
- The floating point unit (fpu) allows the full data range of scientific
- computing for use in \pgfname. Its core is the \pgfname\ math routines for
- mantissa operations, leading to a reasonable trade-of between speed and
- accuracy. It does not require any third-party packages or external
- programs.
-\end{pgflibrary}
-
-
-\subsection{Overview}
-
-The fpu provides a replacement set of math commands which can be installed in
-isolated placed to achieve large data ranges at reasonable accuracy. It
-provides at least%
- \footnote{To be more precise, the FPU's exponent is currently a 32-bit
- integer. That means it supports a significantly larger data range than an
- IEEE double precision number -- but if a future \TeX\ version may provide
- low-level access to doubles, this may change.}%
-the IEEE double precision data range, $\pgfmathprintnumber{-1e+324}, \dotsc,
-\pgfmathprintnumber{+1e324}$. The absolute smallest number bigger than zero is
-$\pgfmathprintnumber{1e-324}$. The FPU's relative precision is at least
-$\pgfmathprintnumber{1e-4}$ although operations like addition have a relative
-precision of $\pgfmathprintnumber{1e-6}$.
-
-Note that the library has not really been tested together with any drawing
-operations. It should be used to work with arbitrary input data which is then
-transformed somehow into \pgfname\ precision. This, in turn, can be processed
-by \pgfname.
-
-
-\subsection{Usage}
-
-\begin{key}{/pgf/fpu=\marg{boolean} (default true)}
- This key installs or uninstalls the FPU. The installation exchanges any
- routines of the standard math parser with those of the FPU: |\pgfmathadd|
- will be replaced with |\pgfmathfloatadd| and so on. Furthermore, any number
- will be parsed with |\pgfmathfloatparsenumber|.
- %
-\begin{codeexample}[preamble={\usepgflibrary{fpu}}]
-\pgfkeys{/pgf/fpu}
-\pgfmathparse{1+1}\pgfmathresult
-\end{codeexample}
- %
- \noindent The FPU uses a low-level number representation consisting of
- flags, mantissa and exponent%
- \footnote{Users should \emph{always} use high
- level routines to manipulate floating point numbers as the format may
- change in a future release.}.%
- To avoid unnecessary format conversions, |\pgfmathresult| will usually
- contain such a cryptic number. Depending on the context, the result may
- need to be converted into something which is suitable for \pgfname\
- processing (like coordinates) or may need to be typeset. The FPU provides
- such methods as well.
-
-%--------------------------------------------------
-% TODOsp: codeexamples: Why is this example commented?
-% \begin{codeexample}[preamble={\usepgflibrary{fpu}}]
-% \begin{tikzpicture}
-% \fill[red,fpu,/pgf/fpu/scale results=1e-10] (*1.234e10,*1e10) -- (*2e10,*2e10);
-% \end{tikzpicture}
-% \end{codeexample}
-%--------------------------------------------------
-
- Use |fpu=false| to deactivate the FPU. This will restore any change. Please
- note that this is not necessary if the FPU is used inside of a \TeX\ group
- -- it will be deactivated afterwards anyway.
-
- It does not hurt to call |fpu=true| or |fpu=false| multiple times.
-
- Please note that if the |fixedpointarithmetic| library of \pgfname\ will
- be activated after the FPU, the FPU will be deactivated automatically.
-\end{key}
-
-\begin{key}{/pgf/fpu/output format=\mchoice{float,sci,fixed} (initially float)}
- This key allows to change the number format in which the FPU assigns
- |\pgfmathresult|.
-
- The predefined choice |float| uses the low-level format used by the FPU.
- This is useful for further processing inside of any library.
- %
-\begin{codeexample}[preamble={\usepgflibrary{fpu}}]
-\pgfkeys{/pgf/fpu,/pgf/fpu/output format=float}
-\pgfmathparse{exp(50)*42}\pgfmathresult
-\end{codeexample}
-
- The choice |sci| returns numbers in the format
- \meta{mantissa}|e|\meta{exponent}. It provides almost no computational
- overhead.
- %
-\begin{codeexample}[preamble={\usepgflibrary{fpu}}]
-\pgfkeys{/pgf/fpu,/pgf/fpu/output format=sci}
-\pgfmathparse{4.22e-8^-2}\pgfmathresult
-\end{codeexample}
-
- The choice |fixed| returns normal fixed point numbers and provides the
- highest compatibility with the \pgfname\ engine. It is activated
- automatically in case the FPU scales results.
- %
-\begin{codeexample}[preamble={\usepgflibrary{fpu}}]
-\pgfkeys{/pgf/fpu,/pgf/fpu/output format=fixed}
-\pgfmathparse{sqrt(1e-12)}\pgfmathresult
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/fpu/scale results=\marg{scale}}
- A feature which allows semi-automatic result scaling. Setting this key has
- two effects: first, the output format for \emph{any} computation will be
- set to |fixed| (assuming results will be processed by \pgfname's kernel).
- Second, any expression which starts with a star, |*|, will be multiplied
- with \meta{scale}.
-\end{key}
-
-\begin{keylist}{
- /pgf/fpu/scale file plot x=\marg{scale},%
- /pgf/fpu/scale file plot y=\marg{scale},%
- /pgf/fpu/scale file plot z=\marg{scale}%
-}
- These keys will patch \pgfname's |plot file| command to automatically scale
- single coordinates by \meta{scale}.
-
- The initial setting does not scale |plot file|.
-\end{keylist}
-
-\begin{command}{\pgflibraryfpuifactive\marg{true-code}\marg{false-code}}
- This command can be used to execute either \meta{true-code} or
- \meta{false-code}, depending on whether the FPU has been activated or not.
-\end{command}
-
-\begin{key}{/pgf/fpu/install only=\marg{list of names}}
- \label{fpu-install-only}
- Unfortunately, the FPU is currently incompatible with drawing operations.
- However, it can still be useful to replace single definitions with FPU
- counterparts to avoid errors of the kind |Dimension too large| which tend
- to happen when transformation matrices are inverted.
-
- This key allows to specify a list of definitions to be pulled into the
- current scope. \emph{Note that there is no reverse operation to uninstall
- these definitions at the moment}, so it is advisable to do this in a group.
- Conveniently, \tikzname{} paths form an implicit group, so you can use this
- key on a path as well.
-
- You have to be aware of the limitations that the FPU imposes. It will not
- magically give \TeX{} better precision, but it will avoid overflow or
- underflow situations for large or small operands by rescaling them. In the
- following example, in the first case the FPU variant performs much better
- than the normal variant, however, in the second case where a rescaling
- would not in fact be needed the rescaling introduces a small round-off
- error.
- %
-\begin{codeexample}[
- preamble={\usepgflibrary{fpu}},
- pre={\pgfkeys{/pgf/fpu=false}},
-]
-\begingroup
-\pgfkeys{/pgf/fpu/install only={divide}}
-\pgfmathparse{12.34/0.001234}\pgfmathresult (good)
-\pgfmathparse{12/4}\pgfmathresult (bad)
-\endgroup
-\end{codeexample}
- %
- This key is introduced in \pgfname v3.1.6 and marked stable since \pgfname
- v3.1.8.
-\end{key}
-
-
-\subsection{Comparison to the fixed point arithmetics library}
-
-There are other ways to increase the data range and/or the precision of
-\pgfname's math parser. One of them is the |fp| package, preferable combined
-with \pgfname's |fixedpointarithmetic| library. The differences between the FPU
-and |fp| are:
-%
-\begin{itemize}
- \item The FPU supports at least the complete IEEE double precision number
- range, while |fp| covers only numbers of magnitude
- $\pm\pgfmathprintnumber{1e17}$.
- \item The FPU has a uniform relative precision of about 4--5 correct
- digits. The fixed point library has an absolute precision which may
- perform good in many cases -- but will fail at the ends of the data
- range (as every fixed point routines does).
- \item The FPU has potential to be faster than |fp| as it has access to fast
- mantissa operations using \pgfname's math capabilities (which use \TeX\
- registers).
-\end{itemize}
-
-
-\subsection{Command Reference and Programmer's Manual}
-
-\subsubsection{Creating and Converting Floats}
-
-\begin{command}{\pgfmathfloatparsenumber\marg{x}}
- Reads a number of arbitrary magnitude and precision and stores its result
- into |\pgfmathresult| as floating point number $m \cdot 10^e$ with mantissa
- and exponent base~$10$.
-
- The algorithm and the storage format is purely text-based. The number is
- stored as a triple of flags, a positive mantissa and an exponent, such as
- %
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{2}
-\pgfmathresult
-\end{codeexample}
- %
- Please do not rely on the low-level representation here, use
- |\pgfmathfloattomacro| (and its variants) and |\pgfmathfloatcreate| if you
- want to work with these components.
-
- The flags encoded in |\pgfmathresult| are represented as a digit where
- `$0$' stands for the number $\pm 0\cdot 10^0$, `$1$' stands for a positive
- sign, `$2$' means a negative sign, `$3$' stands for `not a number', `$4$'
- means $+\infty$ and `$5$' stands for $-\infty$.
-
- The mantissa is a normalized real number $m \in \mathbb{R}$, $1 \le m <
- 10$. It always contains a period and at least one digit after the period.
- The exponent is an integer.
-
- Examples:
- %
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{0}
-\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
-Flags: \F; Mantissa \M; Exponent \E.
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{0.2}
-\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
-Flags: \F; Mantissa \M; Exponent \E.
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{42}
-\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
-Flags: \F; Mantissa \M; Exponent \E.
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{20.5E+2}
-\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
-Flags: \F; Mantissa \M; Exponent \E.
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{1e6}
-\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
-Flags: \F; Mantissa \M; Exponent \E.
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{5.21513e-11}
-\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
-Flags: \F; Mantissa \M; Exponent \E.
-\end{codeexample}
- %
- The argument \meta{x} may be given in fixed point format or the scientific
- ``e'' (or ``E'') notation. The scientific notation does not necessarily
- need to be normalized. The supported exponent range is (currently) only
- limited by the \TeX-integer range (which uses 31 bit integer numbers).
-\end{command}
-
-\begin{key}{/pgf/fpu/handlers/empty number=\marg{input}\marg{unreadable part}}
- This command key is invoked in case an empty string is parsed inside of
- |\pgfmathfloatparsenumber|. You can overwrite it to assign a replacement
- |\pgfmathresult| (in float!).
-
- The initial setting is to invoke |invalid number|, see below.
-\end{key}
-
-\begin{key}{/pgf/fpu/handlers/invalid number=\marg{input}\marg{unreadable part}}
- This command key is invoked in case an invalid string is parsed inside of
- |\pgfmathfloatparsenumber|. You can overwrite it to assign a replacement
- |\pgfmathresult| (in float!).
-
- The initial setting is to generate an error message.
-\end{key}
-
-\begin{key}{/pgf/fpu/handlers/wrong lowlevel format=\marg{input}\marg{unreadable part}}
- This command key is invoked whenever |\pgfmathfloattoregisters| or its
- variants encounter something which is not a properly formatted low-level
- floating point number. As for |invalid number|, this key may assign a new
- |\pgfmathresult| (in floating point) which will be used instead of the
- offending \meta{input}.
-
- The initial setting is to generate an error message.
-\end{key}
-
-\begin{command}{\pgfmathfloatqparsenumber\marg{x}}
- The same as |\pgfmathfloatparsenumber|, but does not perform sanity checking.
-\end{command}
-
-\begin{command}{\pgfmathfloattofixed{\marg{x}}}
- Converts a number in floating point representation to a fixed point number.
- It is a counterpart to |\pgfmathfloatparsenumber|. The algorithm is purely
- text based and defines |\pgfmathresult| as a string sequence which
- represents the floating point number \meta{x} as a fixed point number (of
- arbitrary precision).
- %
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{0.00052}
-\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
-Flags: \F; Mantissa \M; Exponent \E
-$\to$
-\pgfmathfloattofixed{\pgfmathresult}
-\pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{123.456e4}
-\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
-Flags: \F; Mantissa \M; Exponent \E
-$\to$
-\pgfmathfloattofixed{\pgfmathresult}
-\pgfmathresult
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathfloattoint\marg{x}}
- Converts a number from low-level floating point representation to an
- integer (by truncating the fractional part).
- %
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{123456}
-\pgfmathfloattoint{\pgfmathresult}
-\pgfmathresult
-\end{codeexample}
-
- See also |\pgfmathfloatint| which returns the result as float.
-\end{command}
-
-\begin{command}{\pgfmathfloattosci\marg{float}}
- Converts a number from low-level floating point representation to
- scientific format, $1.234e4$. The result will be assigned to the macro
- |\pgfmathresult|.
-\end{command}
-
-\begin{command}{\pgfmathfloatvalueof\marg{float}}
- Expands a number from low-level floating point representation to scientific
- format, $1.234e4$.
-
- Use |\pgfmathfloatvalueof| in contexts where only expandable macros are
- allowed.
-\end{command}
-
-\begin{command}{\pgfmathfloatcreate{\marg{flags}}{\marg{mantissa}}{\marg{exponent}}}
- Defines |\pgfmathresult| as the floating point number encoded by
- \meta{flags}, \meta{mantissa} and \meta{exponent}.
-
- All arguments are characters and will be expanded using |\edef|.
- %
-\begin{codeexample}[]
-\pgfmathfloatcreate{1}{1.0}{327}
-\pgfmathfloattomacro{\pgfmathresult}{\F}{\M}{\E}
-Flags: \F; Mantissa \M; Exponent \E
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathfloatifflags\marg{floating point number}\marg{flag}\marg{true-code}\marg{false-code}}
- Invokes \meta{true-code} if the flag of \meta{floating point number} equals
- \meta{flag} and \meta{false-code} otherwise.
-
- The argument \meta{flag} can be one of
- %
- \begin{description}
- \item[0] to test for zero,
- \item[1] to test for positive numbers,
- \item[+] to test for positive numbers,
- \item[2] to test for negative numbers,
- \item[-] to test for negative numbers,
- \item[3] for ``not-a-number'',
- \item[4] for $+\infty$,
- \item[5] for $-\infty$.
- \end{description}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fpu}}]
-\pgfmathfloatparsenumber{42}
-\pgfmathfloatifflags{\pgfmathresult}{0}{It's zero!}{It's not zero!}
-\pgfmathfloatifflags{\pgfmathresult}{1}{It's positive!}{It's not positive!}
-\pgfmathfloatifflags{\pgfmathresult}{2}{It's negative!}{It's not negative!}
-
-% or, equivalently
-\pgfmathfloatifflags{\pgfmathresult}{+}{It's positive!}{It's not positive!}
-\pgfmathfloatifflags{\pgfmathresult}{-}{It's negative!}{It's not negative!}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathfloattomacro{\marg{x}}{\marg{flagsmacro}}{\marg{mantissamacro}}{\marg{exponentmacro}}}
- Extracts the flags of a floating point number \meta{x} to
- \meta{flagsmacro}, the mantissa to \meta{mantissamacro} and the exponent to
- \meta{exponentmacro}.
-\end{command}
-
-\begin{command}{\pgfmathfloattoregisters{\marg{x}}{\marg{flagscount}}{\marg{mantissadimen}}{\marg{exponentcount}}}
- Takes a floating point number \meta{x} as input and writes flags to count
- register \meta{flagscount}, mantissa to dimen register \meta{mantissadimen}
- and exponent to count register \meta{exponentcount}.
-
- Please note that this method rounds the mantissa to \TeX-precision.
-\end{command}
-
-\begin{command}{\pgfmathfloattoregisterstok{\marg{x}}{\marg{flagscount}}{\marg{mantissatoks}}{\marg{exponentcount}}}
- A variant of |\pgfmathfloattoregisters| which writes the mantissa into a
- token register. It maintains the full input precision.
-\end{command}
-
-\begin{command}{\pgfmathfloatgetflags{\marg{x}}{\marg{flagscount}}}
- Extracts the flags of \meta{x} into the count register \meta{flagscount}.
-\end{command}
-
-\begin{command}{\pgfmathfloatgetflagstomacro{\marg{x}}{\marg{macro}}}
- Extracts the flags of \meta{x} into the macro \meta{macro}.
-\end{command}
-
-\begin{command}{\pgfmathfloatgetmantissa{\marg{x}}{\marg{mantissadimen}}}
- Extracts the mantissa of \meta{x} into the dimen register
- \meta{mantissadimen}.
-\end{command}
-
-\begin{command}{\pgfmathfloatgetmantissatok{\marg{x}}{\marg{mantissatoks}}}
- Extracts the mantissa of \meta{x} into the token register
- \meta{mantissatoks}.
-\end{command}
-
-\begin{command}{\pgfmathfloatgetexponent{\marg{x}}{\marg{exponentcount}}}
- Extracts the exponent of \meta{x} into the count register
- \meta{exponentcount}.
-\end{command}
-
-
-\subsubsection{Symbolic Rounding Operations}
-
-Commands in this section constitute the basic level implementations of the
-rounding routines. They work symbolically, i.e.\ they operate on text, not on
-numbers and allow arbitrarily large numbers.
-
-\begin{command}{\pgfmathroundto{\marg{x}}}
- Rounds a fixed point number to prescribed precision and writes the result
- to |\pgfmathresult|.
-
- The desired precision can be configured with
- |/pgf/number format/precision|, see section~\ref{pgfmath-numberprinting}.
- This section does also contain application examples.
-
- Any trailing zeros after the period are discarded. The algorithm is purely
- text based and allows to deal with precisions beyond \TeX's fixed point
- support.
-
- As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| will
- be set to true if and only if the resulting mantissa has a period.
- Furthermore, |\ifpgfmathfloatroundmayneedrenormalize| will be set to true
- if and only if the rounding result's floating point representation would
- have a larger exponent than \meta{x}.
- %
-\begin{codeexample}[]
-\pgfmathroundto{1}
-\pgfmathresult
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfmathroundto{4.685}
-\pgfmathresult
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfmathroundto{19999.9996}
-\pgfmathresult
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathroundtozerofill{\marg{x}}}
- A variant of |\pgfmathroundto| which always uses a fixed number of digits
- behind the period. It fills missing digits with zeros.
- %
-\begin{codeexample}[]
-\pgfmathroundtozerofill{1}
-\pgfmathresult
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfmathroundto{4.685}
-\pgfmathresult
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfmathroundtozerofill{19999.9996}
-\pgfmathresult
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathfloatround{\marg{x}}}
- Rounds a normalized floating point number to a prescribed precision and
- writes the result to |\pgfmathresult|.
-
- The desired precision can be configured with
- |/pgf/number format/precision|, see section~\ref{pgfmath-numberprinting}.
-
- This method employs |\pgfmathroundto| to round the mantissa and applies
- renormalization if necessary.
-
- As a side effect, the global boolean |\ifpgfmathfloatroundhasperiod| will
- be set to true if and only if the resulting mantissa has a period.
- %
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{52.5864}
-\pgfmathfloatround{\pgfmathresult}
-\pgfmathfloattosci{\pgfmathresult}
-\pgfmathresult
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{9.995}
-\pgfmathfloatround{\pgfmathresult}
-\pgfmathfloattosci{\pgfmathresult}
-\pgfmathresult
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathfloatroundzerofill{\marg{x}}}
- A variant of |\pgfmathfloatround| produces always the same number of digits
- after the period (it includes zeros if necessary).
- %
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{52.5864}
-\pgfmathfloatroundzerofill{\pgfmathresult}
-\pgfmathfloattosci{\pgfmathresult}
-\pgfmathresult
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfmathfloatparsenumber{9.995}
-\pgfmathfloatroundzerofill{\pgfmathresult}
-\pgfmathfloattosci{\pgfmathresult}
-\pgfmathresult
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Math Operations Commands}
-
-This section describes some of the replacement commands in more detail.
-
-Please note that these commands can be used even if the |fpu| as such has not
-been activated -- it is sufficient to load the library.
-
-\begin{command}{\pgfmathfloat\meta{op}}
- Methods of this form constitute the replacement operations where \meta{op}
- can be any of the well-known math operations.
-
- Thus, \declareandlabel{\pgfmathfloatadd} is the counterpart for
- |\pgfmathadd| and so on. The semantics and number of arguments is the same,
- but all input and output arguments are \emph{expected} to be floating point
- numbers.
-\end{command}
-
-\begin{command}{\pgfmathfloattoextentedprecision{\marg{x}}}
- Renormalizes \meta{x} to extended precision mantissa, meaning $100 \le m <
- 1000$ instead of $1 \le m < 10$.
-
- The ``extended precision'' means we have higher accuracy when we apply
- pgfmath operations to mantissas.
-
- The input argument is expected to be a normalized floating point number;
- the output argument is a non-normalized floating point number (well,
- normalized to extended precision).
-
- The operation is supposed to be very fast.
-\end{command}
-
-\begin{command}{\pgfmathfloatsetextprecision\marg{shift}}
- Sets the precision used inside of |\pgfmathfloattoextentedprecision| to
- \meta{shift}.
-
- The different choices are
-
- \begin{tabular}{llrll}
- 0 & normalization to & $0$ & $\le m < 1$ & (disable extended precision) \\
- 1 & normalization to & $10$ & $\le m < 100$ & \\
- 2 & normalization to & $100$ & $\le m < 1000$ & (default of |\pgfmathfloattoextentedprecision|) \\
- 3 & normalization to & $1000$ & $\le m < 10000$ & \\
- \end{tabular}
-\end{command}
-
-\begin{command}{\pgfmathfloatlessthan{\marg{x}}{\marg{y}}}
- Defines |\pgfmathresult| as $1.0$ if $\meta{x} < \meta{y}$, but $0.0$
- otherwise. It also sets the global \TeX-boolean |\pgfmathfloatcomparison|
- accordingly. The arguments \meta{x} and \meta{y} are expected to be numbers
- which have already been processed by |\pgfmathfloatparsenumber|. Arithmetic
- is carried out using \TeX-registers for exponent- and mantissa comparison.
-\end{command}
-
-\begin{command}{\pgfmathfloatmultiplyfixed\marg{float}\marg{fixed}}
- Defines |\pgfmathresult| to be $\meta{float} \cdot \meta{fixed}$ where
- \meta{float} is a floating point number and \meta{fixed} is a fixed point
- number. The computation is performed in floating point arithmetics, that
- means we compute $m \cdot \meta{fixed}$ and renormalize the result where
- $m$ is the mantissa of \meta{float}.
-
- This operation renormalizes \meta{float} with
- |\pgfmathfloattoextentedprecision| before the operation, that means it is
- intended for relatively small arguments of \meta{fixed}. The result is a
- floating point number.
-\end{command}
-
-\begin{command}{\pgfmathfloatifapproxequalrel\marg{a}\marg{b}\marg{true-code}\marg{false-code}}
- Computes the relative error between \meta{a} and \meta{b} (assuming
- \meta{b}$\neq 0$) and invokes \meta{true-code} if the relative error is
- below |/pgf/fpu/rel thresh| and \meta{false-code} if that is not the case.
-
- The input arguments will be parsed with |\pgfmathfloatparsenumber|.
-
- \begin{key}{/pgf/fpu/rel thresh=\marg{number} (initially 1e-4)}
- A threshold used by |\pgfmathfloatifapproxequalrel| to decide whether
- numbers are approximately equal.
- \end{key}
-\end{command}
-
-\begin{command}{\pgfmathfloatshift{\marg{x}}{\marg{num}}}
- Defines |\pgfmathresult| to be $\meta{x} \cdot 10^{\meta{num}}$. The
- operation is an arithmetic shift base ten and modifies only the exponent of
- \meta{x}. The argument \meta{num} is expected to be a (positive or
- negative) integer.
-\end{command}
-
-\begin{command}{\pgfmathfloatabserror\marg{x}\marg{y}}
- Defines |\pgfmathresult| to be the absolute error between two floating
- point numbers $x$ and $y$, $\lvert x - y\rvert $ and returns the result as
- floating point number.
-\end{command}
-
-\begin{command}{\pgfmathfloatrelerror\marg{x}\marg{y}}
- Defines |\pgfmathresult| to be the relative error between two floating
- point numbers $x$ and $y$, $\lvert x - y\rvert / \lvert y \rvert$ and
- returns the result as floating point number.
-\end{command}
-
-\begin{command}{\pgfmathfloatint\marg{x}}
- Returns the integer part of the floating point number \meta{x}, by
- truncating any digits after the period. This methods truncates the absolute
- value $\rvert x \lvert$ to the next smaller integer and restores the
- original sign afterwards.
-
- The result is returned as floating point number as well.
-
- See also |\pgfmathfloattoint| which returns the number in integer format.
-\end{command}
-
-\begin{command}{\pgfmathlog{\marg{x}}}
- Defines |\pgfmathresult| to be the natural logarithm of \meta{x},
- $\ln(\meta{x})$. This method is logically the same as |\pgfmathln|, but it
- applies floating point arithmetics to read number \meta{x} and employs the
- logarithm identity \[ \ln(m \cdot 10^e) = \ln(m) + e \cdot \ln(10) \] to
- get the result. The factor $\ln(10)$ is a constant, so only $\ln(m)$ with
- $1 \le m < 10$ needs to be computed. This is done using standard pgf math
- operations.
-
- Please note that \meta{x} needs to be a number, expression parsing is not
- possible here.
-
- If \meta{x} is \emph{not} a bounded positive real number (for example
- $\meta{x} \le 0$), |\pgfmathresult| will be \emph{empty}, no error message
- will be generated.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fpu}}]
-\pgfmathlog{1.452e-7}
-\pgfmathresult
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fpu}}]
-\pgfmathlog{6.426e+8}
-\pgfmathresult
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Accessing the Original Math Routines for Programmers}
-
-As soon as the library is loaded, every private math routine will be copied to
-a new name. This allows library and package authors to access the \TeX-register
-based math routines even if the FPU is activated. And, of course, it allows the
-FPU as such to perform its own mantissa computations.
-
-The private implementations of \pgfname\ math commands, which are of the form
-|\pgfmath|\meta{name}|@|, will be available as|\pgfmath@basic@|\meta{name}|@|
-as soon as the library is loaded.
-
-\endgroup
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-lsystems.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-lsystems.tex
deleted file mode 100644
index 07abbb441b..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-lsystems.tex
+++ /dev/null
@@ -1,390 +0,0 @@
-% Copyright 2019 by Mark Wibrow
-%
-% This file may be distributed and/or modified
-%
-% 1. under the LaTeX Project Public License and/or
-% 2. under the GNU Public License.
-%
-% See the file doc/generic/pgf/licenses/LICENSE for more details.
-
-
-\section{Lindenmayer System Drawing Library}
-
-\subsection{Overview}
-
-Lindenmayer systems (also commonly known as ``L-systems''), were originally
-developed by Aristid Lindenmayer as a theory of algae growth patterns and then
-subsequently used to model branching patterns in plants and produce fractal
-patterns. Typically, an L-system consists of a set of symbols, each of which is
-associated with some graphical action (such as ``turn left'' or ``move
-forward'') and a set of rules (``production'' or ``rewrite'' rules). Given a
-string of symbols, the rewrite rules are applied several times and the when
-resulting string is processed the action associated with each symbol is
-executed.
-
-In \pgfname, L-systems can be used to create simple 2-dimensional fractal
-patterns\ldots
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{lindenmayersystems}},
- pre={\expandafter\let\csname pgf@lsystem@Koch curve\endcsname=\relax},
-]
-\begin{tikzpicture}
-\pgfdeclarelindenmayersystem{Koch curve}{
- \rule{F -> F-F++F-F}
-}
-
-\shadedraw [top color=white, bottom color=blue!50, draw=blue!50!black]
- [l-system={Koch curve, step=2pt, angle=60, axiom=F++F++F, order=3}]
- lindenmayer system -- cycle;
-\end{tikzpicture}
-\end{codeexample}
-%
-\noindent\ldots and ``plant like'' patterns\ldots
-%
-\begin{codeexample}[preamble={\usetikzlibrary{lindenmayersystems}}]
-\begin{tikzpicture}
-\draw [green!50!black, rotate=90]
- [l-system={rule set={F -> FF-[-F+F]+[+F-F]}, axiom=F, order=4, step=2pt,
- randomize step percent=25, angle=30, randomize angle percent=5}]
- lindenmayer system;
-\end{tikzpicture}
-\end{codeexample}
-%
-\noindent \ldots but it is important to bear in mind that even moderately
-complex L-systems can exceed the available memory of \TeX, and can be very
-slow. If possible, you are advised to increase the main memory and save stack
-to their maximum possible values for your particular \TeX{} distribution.
-However, even by doing this you may find you still run out of memory quite
-quickly.
-
-For an excellent introduction to L-systems (containing some ``really cool''
-pictures -- many of which are sadly not possible in \pgfname) see \emph{The
-Algorithmic Beauty of Plants} by Przemyslaw Prusinkiewicz and Aristid
-Lindenmayer (which is freely available via the internet).
-
-\begin{pgflibrary}{lindenmayersystems}
- This \pgfname-library provides basic commands for defining and using simple
- L-systems. The \tikzname-library provides, furthermore, a front end for
- using L-systems in \tikzname.
-\end{pgflibrary}
-
-
-\subsubsection{Declaring L-systems}
-
-Before an L-system can be used, it must be declared using the following
-command:
-
-\begin{command}{\pgfdeclarelindenmayersystem\marg{name}\marg{specification}}
- This command declares a Lindenmayer system called \meta{name}. The
- \meta{specification} argument contains a description of the L-system's
- symbols and rules. Two commands |\symbol| and |\rule| are only defined when
- the \meta{specification} argument is executed.
-
- \begin{command}{\symbol\marg{name}\marg{code}}
- This defines a symbol called \meta{name} for a specific L-system,
- and associates it with \meta{code}.
-
- A symbol should consist of a single alpha-numeric character (i.e.,
- |A|-|Z|, |a|-|z| or |0|-|9|). The symbols |F|, |f|, |+|, |-|, |[| and
- |]| are available by default so do not need to be defined for each
- L-system. However, if you are feeling adventurous, they can be
- redefined for specific L-systems if required. The L-system treats the
- default symbols as follows (the commands they execute are described
- below):
- %
- \begin{itemize}
- \item |F| move forward a certain distance, drawing a line. Uses
- |\pgflsystemdrawforward|.
- \item |f| move forward a certain distance, without drawing a line.
- Uses |\pgflsystemmoveforward|.
- \item |+| turn left by some angle. Uses |\pgflsystemturnleft|.
- \item |-| turn right by some angle. Uses |\pgflsystemturnright|.
- \item |[| save the current state (i.e., the position and
- direction). Uses |\pgflsystemsavestate|.
- \item |]| restore the last saved state. Uses
- |\pgflsystemrestorestate|.
- \end{itemize}
-
- The symbols |[| and |]| act like a stack: |[| pushes the state of the
- L-system on to the stack, and |]| pops a state off the stack.
-
- When \meta{code} is executed, the transformation matrix is set up so
- that the origin is at the current position and the positive x-axis
- ``points forward'', so |\pgfpathlineto{\pgfpoint{1cm}{0cm}}| draws a
- line 1cm forward.
-
- The following keys can alter the production of an L-system. However,
- they do not store values in themselves.
-
- \begin{key}{/pgf/lindenmayer system/step=\meta{length} (initially 5pt)}
- How far the L-system moves forward if required. This key sets the
- \TeX{} dimension |\pgflsystemstep|.
- \end{key}
-
- \begin{key}{/pgf/lindenmayer system/randomize step percent=\meta{percentage} (initially 0)}
- If the step is to be randomized, this key specifies by how much.
- The value is stored in the \TeX{} macro
- |\pgflsystemrandomizesteppercent|.
- \end{key}
-
- \begin{key}{/pgf/lindenmayer system/left angle=\meta{angle} (initially 90)}
- This key sets the angle through which the L-system turns when it
- turns left. The value is stored in the \TeX{} macro
- |\pgflsystemrleftangle|.
- \end{key}
-
- \begin{key}{/pgf/lindenmayer system/right angle=\meta{angle} (initially 90)}
- This key sets the angle through which the L-system turns when it
- turns right. The value is stored in the \TeX{} macro
- |\pgflsystemrrightangle|.
- \end{key}
-
- \begin{key}{/pgf/lindenmayer system/randomize angle percent=\meta{percentage} (initially 0)}
- If the angles are to be randomized, this key specifies by how much.
- The value is stored in the \TeX{} macro
- |\pgflsystemrandomizeanglepercent|.
- \end{key}
-
- For speed and convenience, when the code for a symbol is executed, the
- following commands are available.
-
- \begin{command}{\pgflsystemcurrentstep}
- The current ``step'' of the L-system (i.e., how far the system
- will move forward if required). This is initially set to the
- value in the \TeX-dimensions |\pgflsystemstep|, but the actual
- value may be changed if |\pgflsystemrandomizestep| is used
- (see below).
- \end{command}
-
- \begin{command}{\pgflsystemcurrentleftangle}
- The angle the L-system will turn when it turns left.
- The value stored in this macro may be changed if
- |\pgflsystemrandomizeleftangle| is used.
- \end{command}
-
- \begin{command}{\pgflsystemcurrentrightangle}
- The angle the L-system will turn when it turns right.
- The value stored in this macro may be changed if
- |\pgflsystemrandomizerightangle| is used.
- \end{command}
-
- The following commands may be useful if you wish to define your own
- symbols.
-
- \begin{command}{\pgflsystemrandomizestep}
- Randomizes the value in |\pgflsystemcurrentstep| according to the
- current value of the key |randomize step percent|.
- \end{command}
-
- \begin{command}{\pgflsystemrandomizeleftangle}
- Randomizes the value in |\pgflsystemcurrentleftangle| according to
- the value of the |randomize angle percent| key.
- \end{command}
-
- \begin{command}{\pgflsystemrandomizerightangle}
- Randomizes the value in |\pgflsystemcurrentrightangle| according
- to the value of the |randomize angle| key.
- \end{command}
-
- \begin{command}{\pgflsystemdrawforward}
- Move forward in the current direction, by |\pgflsystemcurrentstep|,
- drawing a line in the process. This macro calls
- |\pgflsystemrandomizestep|. Internally, \pgfname{} simply shifts
- the transformation matrix in the positive direction of the current
- (transformed) x-axis by |\pgflsystemstep| and then executes a
- line-to to the (newly transformed) origin.
- \end{command}
-
- \begin{command}{\pgflsystemmoveforward}
- Move forward in the current direction, by |\pgflsystemcurrentstep|,
- without drawing a line. This macro calls
- |\pgflsystemrandomizestep|. \pgfname{} executes a transformation as
- above, but executes a move-to to the (newly transformed) origin.
- \end{command}
-
- \begin{command}{\pgflsystemturnleft}
- Turn left by |\pgflsystemcurrentleftangle|. Internally, \pgfname{}
- simply rotates the transformation matrix. This macro calls
- |\pgflsystemrandomizeleftangle|.
- \end{command}
-
- \begin{command}{\pgflsystemturnright}
- Turn right by |\pgflsystemcurrentrightangle|. Internally,
- \pgfname{} simply rotates the transformation matrix. This macro
- calls |\pgflsystemrandomizerightangle|.
- \end{command}
-
- \begin{command}{\pgflsystemsavestate}
- Save the current position and orientation. Internally, \pgfname{}
- simply starts a new \TeX-group.
- \end{command}
-
- \begin{command}{\pgflsystemrestorestate}
- Restore the last saved position and orientation. Internally,
- \pgfname{} closes a \TeX-group, restoring the transformation matrix
- of the outer scope, and a move-to command is executed to the
- (transformed) origin.
- \end{command}
- \end{command}
-
- \begin{command}{\rule{\ttfamily\char`\{}\meta{head}{\ttfamily->}\meta{body}{\ttfamily\char`\}}}
- Declare a rule. \meta{head} should consist of a single symbol, which
- need not have been declared using |\symbol| or exist as a default
- symbol (in fact, the more interesting L-systems depend on using symbols
- with no corresponding code, to control the ``growth'' of the system).
- \meta{body} consists of a string of symbols, which again need not
- necessarily have any code associated with them.
- \end{command}
-
- As an example, the following shows an L-system that uses some of these
- commands. This example illustrates the point that some symbols, in this
- case |A| and |B|, do not have to have code associated with them. They
- simply control the growth of the system.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{lindenmayersystems}},
- pre={\nullfont\expandafter\let\csname pgf@lsystem@Hilbert curve\endcsname=\relax},
-]
-\pgfdeclarelindenmayersystem{Hilbert curve}{
- \symbol{X}{\pgflsystemdrawforward}
- \symbol{+}{\pgflsystemturnright} % Explicitly define + and - symbols.
- \symbol{-}{\pgflsystemturnleft}
- \rule{A -> +BX-AXA-XB+}
- \rule{B -> -AX+BXB+XA-}
-}
-\tikz\draw[lindenmayer system={Hilbert curve, axiom=A, order=4, angle=90}]
- lindenmayer system;
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Using Lindenmayer Systems}
-
-\subsubsection{Using L-Systems in PGF}
-
-The following command is used to run an L-system in \pgfname:
-%
-\begin{command}{\pgflindenmayersystem\marg{name}\marg{axiom}\marg{order}}
- Runs the L-system called \meta{name} using the input string \meta{axiom}
- for \meta{order} iterations. In general, prior to calling this command, the
- transformation matrix should be set appropriately for shifting and
- rotating, and a move-to to the (transformed) origin should be executed.
- This origin will be where the L-system starts. In addition, the relevant
- keys should be set appropriately.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{lindenmayersystems}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \pgfset{lindenmayer system/.cd, angle=60, step=2pt}
- \foreach \x/\y in {0cm/1cm, 1.5cm/1.5cm, 2.5cm/0.5cm, 1cm/0cm}{
- \pgftransformshift{\pgfqpoint{\x}{\y}}
- \pgfpathmoveto{\pgfpointorigin}
- \pgflindenmayersystem{Koch curve}{F++F++F}{2}
- \pgfusepath{stroke}
- }
-\end{tikzpicture}
-\end{codeexample}
-
- Note that it is perfectly feasible for an L-system to define special
- symbols which perform the move-to and use-path operations.
- %
-\end{command}
-
-
-\subsubsection{Using L-Systems in Ti\emph{k}Z}
-
-In \tikzname, an L-system is created using a path operation. However,
-\tikzname{} is more flexible regarding the positioning of the L-system and also
-provides keys to create L-systems ``on-line''.
-
-\begin{pathoperation}{lindenmayer system}{ \opt{|[|\meta{keys}|]|}}
- This will run an L-system according to the parameters specified in
- \meta{keys} (which can also contain normal \tikz{} keys such as |draw| or
- |thin|). The syntax is flexible regarding the L-system parameters and the
- following all do the same thing:
- %
-\begin{codeexample}[code only]
-\draw lindenmayer system [lindenmayer system={Hilbert curve, axiom=4, order=3}];
-\end{codeexample}
-
-\begin{codeexample}[code only]
-\draw [lindenmayer system={Hilbert curve, axiom=4, order=3}] lindenmayer system;
-\end{codeexample}
-
-\begin{codeexample}[code only]
-\tikzset{lindenmayer system={Hilbert curve, axiom=4, order=3}}
-\draw lindenmayer system;
-\end{codeexample}
- %
-\end{pathoperation}
-
-\begin{pathoperation}{l-system}{ \opt{|[|\meta{keys}|]|}}
- A more compact version of the |lindenmayer system| path command.
-\end{pathoperation}
-
-This library adds some additional keys for specifying L-systems. These keys
-only work in \tikzname{} and all have the same path, namely, |/pgf/lindenmayer|
-|system|, but the following keys are provided for convenience, so that you do
-not have to keep repeating this path:
-
-\begin{stylekey}{/pgf/lindenmayer system=\marg{keys}}
-\keyalias{tikz}
- This key changes the key path to |/pgf/lindenmayer systems| and executes
- \meta{keys}.
-\end{stylekey}
-
-\begin{stylekey}{/pgf/l-system=\marg{keys}}
-\keyalias{tikz}
- A more compact version of the previous key.
-\end{stylekey}
-
-\begin{key}{/pgf/lindenmayer system/name=\marg{name}}
- Sets the name for the L-system.
-\end{key}
-
-\begin{key}{/pgf/lindenmayer system/axiom=\marg{string}}
- Sets the axiom (or input string) for the L-system.
-\end{key}
-
-\begin{key}{/pgf/lindenmayer system/order=\marg{integer}}
- Sets the number of iterations the L-system will perform.
-\end{key}
-
-\begin{key}{/pgf/lindenmayer system/rule set=\marg{list}}
- This key allows an (anonymous) L-system to be declared ``on-line''. There
- is, however, a restriction that only the default symbols can be used for
- drawing (empty symbols can still be used to control the growth of the
- system). The rules in \meta{list} should be separated by commas.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{lindenmayersystems}}]
-\tikz[rotate=65]\draw [green!60!black] l-system
- [l-system={rule set={F -> F[+F]F[-F]}, axiom=F, order=4, angle=25,step=3pt}];
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/lindenmayer system/anchor=\meta{anchor}}
- Be default, when this key is not used, the L-system will start from the
- last specified coordinate. By using this key, the L-system will be placed
- inside a special (rectangle) node which can be positioned using
- \meta{anchor}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{lindenmayersystems}}]
-\begin{tikzpicture}[l-system={step=1.75pt, order=5, angle=60}]
- \pgfdeclarelindenmayersystem{Sierpinski triangle}{
- \symbol{X}{\pgflsystemdrawforward}
- \symbol{Y}{\pgflsystemdrawforward}
- \rule{X -> Y-X-Y}
- \rule{Y -> X+Y+X}
- }
- \draw [help lines] grid (3,2);
- \draw [red] (0,0) l-system
- [l-system={Sierpinski triangle, axiom=+++X, anchor=south west}];
- \draw [blue] (3,2) l-system
- [l-system={Sierpinski triangle, axiom=X, anchor=north east}];
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-math.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-math.tex
deleted file mode 100644
index 8fabb4998e..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-math.tex
+++ /dev/null
@@ -1,471 +0,0 @@
-% Copyright 2019 by Mark Wibrow
-%
-% 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{Math Library}
-\label{section-library-math}
-
-\begin{tikzlibrary}{math}
- This library defines a simple mathematical language to define simple
- functions and perform sequences of basic mathematical operations.
-\end{tikzlibrary}
-
-
-\subsection{Overview}
-
-\pgfname\ and \tikzname\ both use the \pgfname\ mathematical engine which
-provides many commands for parsing expressions. Unfortunately the \pgfname\
-math engine is somewhat cumbersome for long sequences of mathematical
-operations, particularly when assigning values to multiple variables. The
-\tikzname\ |calc| library provides some additional ``convenience'' operations
-for doing calculations (particularly with coordinates), but this can only be
-used inside \tikzname\ path commands.
-
-This |math| library provides a means to perform sequences of mathematical
-operations in a more `user friendly' manner than the \pgfname\ math engine. In
-addition, the coordinate calculations of the |calc| library can be accessed
-(provided it is loaded).
-%
-However as the |math| library uses the \pgfname\ math engine -- which uses pure
-\TeX\ to perform all its calculations -- it is subject to the same speed and
-accuracy limitations. It is worth bearing this in mind, before trying to
-implement algorithms requiring intensive and highly accurate computation. You
-can, of course use the |fp| or the |fpu| libraries to increase the accuracy
-(but not necessarily the speed) of computations.
-
-For most purposes, the features provided by this library are accessed using the
-following command:
-
-\begin{command}{\tikzmath\texttt{\{}\meta{statements}\texttt{\}}}
- This command process a series of \meta{statements} which can represent
- assignments, function definitions, conditional evaluation, and iterations.
- It provides, in effect, a miniature mathematical language to perform basic
- mathematical operations. Perhaps the most important thing to remember is
- that \emph{every statement should end with a semi-colon}. This is likely to
- be the most common reason why the |\tikzmath| command fails.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\tikzmath{
- % Adapted from http://www.cs.northwestern.edu/academics/courses/110/html/fib_rec.html
- function fibonacci(\n) {
- if \n == 0 then {
- return 0;
- } else {
- return fibonacci2(\n, 0, 1);
- };
- };
- function fibonacci2(\n, \p, \q) {
- if \n == 1 then {
- return \q;
- } else {
- return fibonacci2(\n-1, \q, \p+\q);
- };
- };
- int \f, \i;
- for \i in {0,1,...,20} {
- \f = fibonacci(\i);
- print {\f, };
- };
-}
-\end{codeexample}
- %
-\end{command}
-
-In addition to this command the following key is provided:
-
-\begin{key}{/tikz/evaluate={\meta{statements}}}
- This key simply executes |\tikzmath{|\meta{statements}|}|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\tikz[x=0.25cm,y=0.25cm,
- evaluate={
- int \i, \j;
- for \i in {0,...,10} {
- for \j in {0,...,10} {
- \a{\i,\j} = (\i+\j)*5;
- };
- };
- }
-]
-\foreach \i in {0,...,10}
- \foreach \j in {0,...,10}
- \fill [red!\a{\i,\j}!yellow] (\i,\j) rectangle ++(1, 1);
-\end{codeexample}
- %
-\end{key}
-
-The following sections describe the miniature language that this library
-provides and can be used in the |\tikzmath| command and the |evaluate| key.
-The language consists only of simple keywords and expressions but the
-mini-parser allows you to format code in a reasonably versatile way (much like
-the |tikz| parser) except that \emph{all the keywords must be followed by at
-least one space}. This is the second most important thing to remember (after
-remembering to insert semi-colons at the end of every statement).
-
-
-\subsection{Assignment}
-
-In the simplest case, you will want to evaluate an expression and assign it to
-a macro, or a \TeX\ count or dimension register. In this case, use of the
-|math| library is straightforward:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\newcount\mycount
-\newdimen\mydimen
-\tikzmath{
- \a = 4*5+6;
- \b = sin(30)*4;
- \mycount = log10(2048) / log10(2);
- \mydimen = 15^2;
-}
-\a, \b, \the\mycount, \the\mydimen
-\end{codeexample}
-
-In addition, \TeX-macros (\emph{not} \TeX\ registers) can be suffixed with an
-index, similar to indices in mathematical notation, for example, $x_1$, $x_2$,
-$x_3$:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\tikzmath{
- \x1 = 3+4; \x2 = 30+40; \x3 = 300+400;
-}
-\x1, \x2, \x3
-\end{codeexample}
-
-The index does not have to be a number. By using braces |{}|, more
-sophisticated indices can be created:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\tikzmath{
- \c{air} = 340; \c{water} = 1435; \c{steel} = 6100;
-}
-\foreach \medium in {air,steel}{The speed of sound in \medium\ is \c{\medium} m/s. }
-\end{codeexample}
-
-You should not, however, try to mix indexed and non-indexed variables. Once an
-assignment is made using an index, the |math| library expects all instances of
-the variable on the right hand side of an assignment to be followed by an
-index. This effect is reversed if you subsequently make an assignment to the
-variable without an index: the |math| library (or to be precise the \pgfname\
-math-engine) will then ignore any index following the variable on the right
-hand side of an assignment.
-
-In some cases, you may wish to assign a value or expression to a variable
-without evaluating it with the \pgfname\ math-engine. In this case, you can use
-the following keyword:
-
-\begin{math-keyword}{{let} \meta{variable} \texttt{=} \meta{expression}\texttt{;}}
- This keyword assigns \meta{expression} to \meta{variable} without
- evaluation. The \meta{expression} is however fully expanded using |\edef|.
- Any spaces preceding \meta{expression} are removed, but any trailing spaces
- (before the semi-colon) are included.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\tikzmath{
- let \x = (5*4)+1;
- let \c1 = blue;
-}
-\x, ``\c1''
-\end{codeexample}
- %
-\end{math-keyword}
-
-
-\subsection{Integers, ``Real'' Numbers, and Coordinates}
-
-By default, assignments are made by evaluating expressions using the \pgfname\
-math-engine and results are usually returned as number with a decimal point
-(unless you are assigning to a count register or use the |int| function).
-%
-As this is not always desirable, the |math| library allows variables -- which
-\emph{must} be \TeX\ macros -- to be `declared' as being a particular `type'.
-The library recognizes three types: integers (numbers without a decimal point),
-real numbers (numbers with a decimal point\footnote{Strictly speaking, due to
-the finite range and precision of \TeX\ numerical capabilities, the term
-``real'' is not correct.}), and coordinates.
-
-To declare a variable as being one of the three types, you can use the
-keywords shown below. It is important to remember that by telling the |math|
-library you want it to do a particular assignment for a variable, it will also
-do the same assignment when the variable is indexed.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\tikzmath{
- integer \x;
- \x1 = 3+4; \x2 = 30+40; \x3 = 300+400;
-}
-\x1, \x2, \x3
-\end{codeexample}
-
-%But, if you want integer results without using a count register or the
-%|int| function, you can use a keyword to indicate this:
-
-\begin{math-keyword}{{integer} \meta{variable}\opt{\texttt{,} \meta{additional variables}}\texttt{;}}
- The |integer| keyword indicates that assignments to the \meta{variable} or
- the comma separated list of \meta{additional variables} should be truncated
- (not rounded) to integers. The variables should be ordinary macros --
- \emph{not} \TeX\ registers. In addition the variables should \emph{not} be
- indexed.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\tikzmath{
- integer \x, \y, \z;
- \x = 4*5+6;
- \y = sin(30)*4;
- \z = log10(512) / log10(2);
- print {$x=\x$, $y=\y$, $z=\z$};
-}
-\end{codeexample}
- %
-\end{math-keyword}
-
-\begin{math-keyword}{{int} \meta{variable}\opt{\texttt{,} \meta{additional variables}}\texttt{;}}
- Short version of the |integer| keyword.
-\end{math-keyword}
-
-Having declared a variable as an integer, the |math| library will continue to
-assign only integers to that variable within the current \TeX\ scope. If you
-wish to assign non-integer (i.e., \emph{real}) numbers to the same variable,
-the following keyword can be used.
-
-\begin{math-keyword}{{real} \meta{variable}\opt{\texttt{,} \meta{additional variables}}\texttt{;}}
- The |real| keyword ensures that assignments \meta{variable} (and
- \meta{additional variables}) will not be truncated to integers.
-\end{math-keyword}
-
-In order to take advantage of |math| library interface to the |calc| library
-you must indicate that a variable is to be assigned coordinates, using the
-following keyword.
-
-\begin{math-keyword}{{coordinate} \meta{variable}\opt{\texttt{,} \meta{additional variables}}\texttt{;}}
- This keyword enables \tikzname-style coordinates such as |(2cm,3pt)| or
- |(my node.east)| to be parsed and assigned to \meta{variable} in the form
- $x,y$, which can then be used in a |tikzpicture|:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\tikzmath{
- coordinate \c;
- \c = (45:10pt);
-}
-\tikz\draw (0,0) -- (\c);
-\end{codeexample}
-
- If the \tikzname\ |calc| library is loaded, coordinate calculations can be
- performed; the coordinate expression does not have to be surrounded by
- |($|\ldots|$)|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\tikzmath{
- coordinate \c, \d;
- \c = (-1,2)+(1,-1);
- \d = (4,1)-(2,-1);
-}
-\tikz\draw (\c) -- (\d);
-\end{codeexample}
-
- In addition to assigning the $x$ and $y$ coordinates to \meta{variable}
- (possibly with an optional index), two further variables are defined. The
- first takes the name of \meta{variable} (e.g., |\c|) suffixed with |x|
- (i.e., |\cx|) and is assigned the $x$ coordinate of |\c|. The second takes
- the name of \meta{variable} suffixed with |y| (i.e., |\cy|) and is assigned
- the $y$ coordinate of |\c|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\tikzmath{
- coordinate \c;
- \c1 = (30:20pt);
- \c2 = (210:20pt);
-}
-\tikz\draw (\cx1,\cy1) -- (\cx2,\cy1) -- (\cx2,\cy2) -- (\cx1,\cy2);
-\end{codeexample}
- %
-\end{math-keyword}
-
-%\begin{math-keyword}{{point} \meta{variable}\opt{\texttt{,} \meta{additional variables}}\texttt{;}}
-% The |point| keyword is a synonym for the |coordinate| keyword and performs
-% the same function.
-%\end{math-keyword}
-
-
-\subsection{Repeating Things}
-
-\begin{math-keyword}{{for} \meta{variable} \texttt{in \{}\meta{list} \texttt{\}\{}\meta{expressions}\texttt{\};}}
- This is a ``trimmed down'' version of the |\foreach| command available as
- part of \pgfname\ and \tikzname, but cannot currently be used outside of
- the |\tikzmath| command. It is important to note the following:
- %
- \begin{itemize}
- \item Every value in \meta{list} is evaluated using the \pgfname\
- mathematical engine. However, if an item in \meta{list} contains a
- comma, it \emph{must} be surrounded by braces, for example,
- |{mod(5, 2)}|.
- %
-\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{math}}]
-\tikzmath{
- int \x, \v;
- \v=1;
- for \x in {1,...,{random(3,10)}} {
- \v=\v*2;
- };
- print {$x=\x, v=\v$};
-}
-\end{codeexample}
- %
- \item Because each item is evaluated, you cannot use \tikzname\
- coordinates in \meta{list}.
- \item Only single variable assignment is supported.
- \item The ``dots notation'' (e.g., |1,2,...,9|) can be used in
- \meta{list}, but is not as sophisticated as the \pgfname\
- |\foreach| command. In particular, contextual replacement is not
- possible.
- \item Assignments that occur in the loop body \emph{are not scoped}.
- They last beyond the body of each iteration and the end of the
- |for| statement. This includes the values assigned to the
- \meta{variable}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\tikzmath{
- int \x, \y;
- \y = 0;
- for \x1 in {1,...,5} {
- for \x2 in {10,20,...,50} {
- \y = \y+\x1*\x2;
- };
- };
-}
-$x_1=\x1, x_2=\x2, y=\y$
-\end{codeexample}
- \end{itemize}
-\end{math-keyword}
-
-
-\subsection{Branching Statements}
-
-Sometimes you may wish to execute different statements depending on the value
-of an expression. In this case the following keyword can be used:
-
-\begin{math-keyword}{{if} \meta{condition} \texttt{then \{}\meta{if-non-zero-statements}\texttt{\};}}
- This keyword executes \meta{if-non-zero-statements} if the expression in
- \meta{condition} evaluates to any value other than zero.
-\end{math-keyword}
-
-\begin{math-keyword}{{if} \meta{condition} \texttt{then \{}\meta{if-non-zero-statements}\texttt{\}} \texttt{else} \texttt{\{}\meta{if-zero-statements}\texttt{\}}\texttt{;}}
- This keyword executes \meta{if-non-zero-statements} if the expression in
- \meta{condition} evaluates to any value other than zero and the
- \meta{if-zero-statements} are executed if the expression in
- \meta{condition} evaluates to zero.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
- \begin{tikzpicture}
- \tikzmath{
- int \x;
- for \k in {0,10,...,350} {
- if \k>260 then { let \c = orange; } else {
- if \k>170 then { let \c = blue; } else {
- if \k>80 then { let \c = red; } else {
- let \c = green; }; }; };
- {
- \path [fill=\c!50, draw=\c] (\k:0.5cm) -- (\k:1cm) --
- (\k+5:1cm) -- (\k+5:0.5cm) -- cycle;
- };
- };
- }
- \end{tikzpicture}
-\end{codeexample}
- %
-\end{math-keyword}
-
-
-\subsection{Declaring Functions}
-
-You can add functions by using the following keywords:
-
-\begin{math-keyword}{{function} \meta{name}\texttt{(}\meta{arguments}\texttt{) \{} \meta{definition} \texttt{\};}}
- This keyword works much like the |declare function| provided by the
- \pgfname\ math-engine. The function \meta{name} can be any name that is not
- already a function name in the current scope. The list of \meta{arguments}
- are comma separated \TeX\ macros such as |\x|, or |\y| (it is not possible
- to declare functions that take variable numbers of arguments). If the
- function takes no arguments then the parentheses need not be used. It is
- very important to note that the arrays that the \pgfname\ math engine
- supports \emph{cannot currently be passed as arguments to functions}.
-
- The function \meta{definition} should be a sequence of statements that can
- be parsed by the |\tikzmath| command and should use the commands specified
- in the \meta{arguments}. The |return| keyword (described below) should be
- used to indicate the value returned by the function.
- %
- Although \meta{definition} can take any statements accepted by |\tikzmath|,
- it is not advisable try to define functions inside other functions.
- %
-\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{math}}]
-\tikzmath{
- function product(\x,\y) {
- return \x*\y;
- };
- int \i, \j, \k;
- \i = random(1,10);
- \j = random(20, 40);
- \k = product(\i, \j);
- print { $\i\times \j = \k$ };
-}
-\end{codeexample}
- %
-\end{math-keyword}
-
-\begin{math-keyword}{{return} \meta{expression}\texttt{;}}
- This keyword should be used as the last executed statement in a function
- definition to indicate the value that should be returned.
-\end{math-keyword}
-
-
-\subsection{Executing Code Outside the Parser}
-
-Sometimes you may wish to do ``something'' outside the parser, perhaps display
-some intermediate result or execute some code. In this case you have two
-options. Firstly, the following keyword can be used:
-
-\begin{math-keyword}{{print} \texttt{\{}\meta{code}\texttt{\};}}
- Execute \meta{code} immediately. This is intended as convenience keyword
- for displaying information in a document (analogous to the |print| command
- in real programming languages). The \meta{code} is executed inside a \TeX\
- group.
- %
-\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{math}}]
-\tikzmath{
- int \x, \y, \z;
- \x = random(2, 5);
- for \y in {0,...,6} {
- \z = \x^\y;
- print {$\x^\y=\z$, };
- };
-}
-\end{codeexample}
- %
-\end{math-keyword}
-
-Secondly, if a statement begins with a brace |{|, then everything up to the
-closing brace |}| is collected and executed (the closing brace \emph{must} be
-followed by a semi-colon). Like the |print| keyword, the contents of the braces
-is executed inside a \TeX\ group. Unlike the |print| keyword, the brace
-notation can be used in functions so that |tikz| path commands can be safely
-executed inside a |tikzpicture|.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{math}}]
-\begin{tikzpicture}
-\draw [help lines] grid (3,2);
-\tikzmath{
- coordinate \c;
- for \x in {0,10,...,360} {
- \c = (1.5cm, 1cm) + (\x:1cm and 0.5cm);
- { \fill (\c) circle [radius=1pt]; };
- };
-}
-\end{tikzpicture}
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-matrices.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-matrices.tex
deleted file mode 100644
index 816464c0e5..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-matrices.tex
+++ /dev/null
@@ -1,334 +0,0 @@
-% 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{Matrix Library}
-
-\begin{tikzlibrary}{matrix}
- This library package defines additional styles and options for creating
- matrices. The basic matrix styles and options can be found in
- Section~\ref{section-matrices}.
-\end{tikzlibrary}
-
-
-\subsection{Matrices of Nodes}
-
-A \emph{matrix of nodes} is a \tikzname\ matrix in which each cell contains a
-node. In this case it is bothersome having to write |\node{| at the beginning
-of each cell and |};| at the end of each cell. The following key simplifies
-typesetting such matrices.
-
-\begin{key}{/tikz/matrix of nodes}
- Conceptually, this key adds |\node{| at the beginning and |};| at the end
- of each cell and sets the |anchor| of the node to |base|. Furthermore, it
- adds the option |name| option to each node, where the name is set to
- \meta{matrix name}|-|\meta{row number}|-|\meta{column number}. For
- example, if the matrix has the name |my matrix|, then the node in the
- upper left cell will get the name |my matrix-1-1|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix (magic) [matrix of nodes]
- {
- 8 & 1 & 6 \\
- 3 & 5 & 7 \\
- 4 & 9 & 2 \\
- };
-
- \draw[thick,red,->] (magic-1-1) |- (magic-2-3);
-\end{tikzpicture}
-\end{codeexample}
-
- You may wish to add options to certain nodes in the matrix. This can be
- achieved in three ways.
- %
- \begin{enumerate}
- \item You can modify, say, the |row 2 column 3| style to pass special
- options to this particular cell.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}[row 2 column 3/.style=red]
- \matrix [matrix of nodes]
- {
- 8 & 1 & 6 \\
- 3 & 5 & 7 \\
- 4 & 9 & 2 \\
- };
-\end{tikzpicture}
-\end{codeexample}
- %
- \item At the beginning of a cell, you can use a special syntax. If a
- cell starts with a vertical bar, then everything between this bar
- and the next bar is passed on to the |node| command.
- %
-{\catcode`\|=12
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix [matrix of nodes]
- {
- 8 & 1 & 6 \\
- 3 & 5 & |[red]| 7 \\
- 4 & 9 & 2 \\
- };
-\end{tikzpicture}
-\end{codeexample}
-}
- %
- You can also use an option like \verb!|[red] (seven)|! to give a
- different name to the node.
-
- Note that the |&| character also takes an optional argument, which
- is an extra column skip.
- %
-{\catcode`\|=12
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix [matrix of nodes]
- {
- 8 &[1cm] 1 &[3mm] |[red]| 6 \\
- 3 & 5 & |[red]| 7 \\
- 4 & 9 & 2 \\
- };
-\end{tikzpicture}
-\end{codeexample}
-}
- \item If your cell starts with a |\path| command or any command that
- expands to |\path|, which includes |\draw|, |\node|, |\fill| and
- others, the |\node{| startup code and the |};| code are suppressed.
- This means that for this particular cell you can provide totally
- different contents.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix [matrix of nodes]
- {
- 8 & 1 & 6 \\
- 3 & 5 & \node[red]{7}; \draw(0,0) circle(10pt);\\
- 4 & 9 & 2 \\
- };
-\end{tikzpicture}
-\end{codeexample}
- \end{enumerate}
-\end{key}
-
-\begin{key}{/tikz/matrix of math nodes}
- This style is almost the same as the previous style, only |$| is added %$
- at the beginning and at the end of each node, so math mode will be switched
- on in all nodes.
- %
-{\catcode`\|=12
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix [matrix of math nodes]
- {
- a_8 & a_1 & a_6 \\
- a_3 & a_5 & |[red]| a_7 \\
- a_4 & a_9 & a_2 \\
- };
-\end{tikzpicture}
-\end{codeexample}
-}
-\end{key}
-
-\begin{key}{/tikz/nodes in empty cells=\meta{true or false} (default true)}
- When set to |true|, a node (with empty contents) is put in empty cells.
- Normally, empty cells are just, well, empty. The style can be used together
- with both a |matrix of nodes| and a |matrix of math nodes|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix [matrix of math nodes,nodes={circle,draw}]
- {
- a_8 & & a_6 \\
- a_3 & & a_7 \\
- a_4 & a_9 & \\
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix [matrix of math nodes,nodes={circle,draw},nodes in empty cells]
- {
- a_8 & & a_6 \\
- a_3 & & a_7 \\
- a_4 & a_9 & \\
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{End-of-Lines and End-of-Row Characters in Matrices of Nodes}
-
-Special care must be taken about the usage of the |\\| command inside a matrix
-of nodes. The reason is that this character is overloaded in \TeX: On the one
-hand, it is used to denote the end of a line in normal text; on the other hand
-it is used to denote the end of a row in a matrix. Now, if a matrix contains
-node which in turn may have multiple lines, it is unclear which meaning of |\\|
-should be used.
-
-This problem arises only when you use the |text width| option of nodes. Suppose
-you write a line like
-%
-\begin{codeexample}[code only]
-\matrix [text width=5cm,matrix of nodes]
-{
- first row & upper line \\ lower line \\
- second row & hmm \\
-};
-\end{codeexample}
-%
-This leaves \TeX\ trying to riddle out how many rows this matrix should have.
-Do you want two rows with the upper right cell containing a two-line text. Or
-did you mean a three row matrix with the second row having only one cell?
-
-Since \TeX\ is not clairvoyant, the following rules are used:
-%
-\begin{enumerate}
- \item Inside a matrix, the |\\| command, by default, signals the end of the
- row, not the end of a line in a cell.
- \item However, there is an exception to this rule: If a cell starts with a
- \TeX-group (this is, with |{|), then inside this first group the |\\|
- command retains the meaning of ``end of line'' character. Note that
- this special rule works only for the first group in a cell and this
- group must be at the beginning.
-\end{enumerate}
-
-The net effect of these rules is the following: Normally, |\\| is an end-of-row
-indicator; if you want to use it as an end-of-line indicator in a cell, just
-put the whole cell in curly braces. The following example illustrates the
-difference:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix [matrix of nodes,nodes={text width=16mm,draw}]
- {
- row 1 & upper line \\ lower line \\
- row 2 & hmm \\
- };
-\end{tikzpicture}
-\end{codeexample}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix [matrix of nodes,nodes={text width=16mm,draw}]
- {
- row 1 & {upper line \\ lower line} \\
- row 2 & hmm \\
- };
-\end{tikzpicture}
-\end{codeexample}
-
-Note that this system is not fool-proof. If you write things like |a&b{c\\d}\\|
-in a matrix of nodes, an error will result (because the second cell did not
-start with a brace, so |\\| retained its normal meaning and, thus, the second
-cell contained the text |b{c|, which is not balanced with respect to the number
-of braces).
-
-
-\subsection{Delimiters}
-
-Delimiters are parentheses or braces to the left and right of a formula or a
-matrix. The |matrix| library offers options for adding such delimiters to a
-matrix. However, delimiters can actually be added to any node that has the
-standard anchors |north|, |south|, |north west| and so on. In particular, you
-can add delimiters to any |rectangle| box. They are implemented by ``measuring
-the height'' of the node and then adding a delimiter of the correct size to the
-left or right using some after node magic.
-
-\begin{key}{/tikz/left delimiter=\meta{delimiter}}
- This option can be given to a any node that has the standard anchors
- |north|, |south| and so on. The \meta{delimiter} can be any delimiter that
- is acceptable to \TeX's |\left| command.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix [matrix of math nodes,left delimiter=(,right delimiter=\}]
- {
- a_8 & a_1 & a_6 \\
- a_3 & a_5 & a_7 \\
- a_4 & a_9 & a_2 \\
- };
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \node [fill=red!20,left delimiter=(,right delimiter=\}]
- {$\displaystyle\int_0^1 x\,dx$};
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{stylekey}{/tikz/every delimiter (initially \normalfont empty)}
- This style is executed for every delimiter. You can use it to shift or
- color delimiters or do whatever.
- \end{stylekey}
-
- \begin{stylekey}{/tikz/every left delimiter (initially \normalfont empty)}
- This style is additionally executed for every left delimiter.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- [every left delimiter/.style={red,xshift=1ex},
- every right delimiter/.style={xshift=-1ex}]
- \matrix [matrix of math nodes,left delimiter=(,right delimiter=\}]
- {
- a_8 & a_1 & a_6 \\
- a_3 & a_5 & a_7 \\
- a_4 & a_9 & a_2 \\
- };
-\end{tikzpicture}
-\end{codeexample}
- \end{stylekey}
-\end{key}
-
-\begin{key}{/tikz/right delimiter=\meta{delimiter}}
- Works as above.
- %
- \begin{stylekey}{/tikz/every right delimiter (initially \normalfont empty)}
- Works as above.
- \end{stylekey}
-\end{key}
-
-\begin{key}{/tikz/above delimiter=\meta{delimiter}}
- This option allows you to add a delimiter above the node. It is implemented
- by rotating a left delimiter.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix [matrix of math nodes,%
- left delimiter=\|,right delimiter=\rmoustache,%
- above delimiter=(,below delimiter=\}]
- {
- a_8 & a_1 & a_6 \\
- a_3 & a_5 & a_7 \\
- a_4 & a_9 & a_2 \\
- };
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{stylekey}{/tikz/every above delimiter (initially \normalfont empty)}
- Works as above.
- \end{stylekey}
-\end{key}
-
-\begin{key}{/tikz/below delimiter=\meta{delimiter}}
- Works as above.
- \begin{stylekey}{/tikz/every below delimiter (initially \normalfont empty)}
- Works as above.
- \end{stylekey}
-\end{key}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-mindmaps.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-mindmaps.tex
deleted file mode 100644
index 646f12bf6c..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-mindmaps.tex
+++ /dev/null
@@ -1,523 +0,0 @@
-% 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{Mindmap Drawing Library}
-
-\begin{tikzlibrary}{mindmap}
- This packages provides styles for drawing mindmap diagrams.
-\end{tikzlibrary}
-
-
-\subsection{Overview}
-
-This library is intended to make the creation of mindmaps or concept maps
-easier. A \emph{mindmap} is a graphical representation of a concept together
-with related concepts and annotations. Mindmaps are, essentially, trees,
-possibly with a few extra edges added, but they are usually drawn in a special
-way: The root concept is placed in the middle of the page and is drawn as a
-huge circle, ellipse, or cloud. The related concepts then ``leave'' this root
-concept via branch-like tendrils.
-
-The |mindmap| library of \tikzname\ produces mindmaps that look a bit different
-from the standard mindmaps: While the big root concept is still a circle,
-related concepts are also depicted as (smaller) circles. The related concepts
-are linked to the root concept via organic-looking connections. The overall
-effect is visually rather pleasing, but readers may not immediately think of a
-mindmap when they see a picture created with this library.
-
-Although it is not strictly necessary, you will usually create mindmaps using
-\tikzname's tree mechanism and some of the styles and macros of the package
-work best when used inside trees. However, it is still possible and sometimes
-necessary to treat parts of a mindmap as a graph with arbitrary edges and this
-is also possible.
-
-
-\subsection{The Mindmap Style}
-
-Every mindmap should be put in a scope or a picture where the |mindmap| style
-is used. This style installs some internal settings.
-
-\begin{stylekey}{/tikz/mindmap}
- Use this style with all pictures or at least scopes that contain a mindmap.
- It installs a whole bunch of settings that are useful for drawing mindmaps.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\tikz[mindmap,concept color=red!50]
- \node [concept] {Root concept}
- child[grow=right] {node[concept] {Child concept}};
-\end{codeexample}
- %
- The sizes of concepts are predefined in such a way that a medium-size
- mindmap will fit on an A4 page (more or less).
- %
- \begin{stylekey}{/tikz/every mindmap}
- This style is included by the |mindmap| style. Change this style to add
- special settings to your mindmaps.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\tikz[large mindmap,concept color=red!50]
- \node [concept] {Root concept}
- child[grow=right] {node[concept] {Child concept}};
-\end{codeexample}
- \end{stylekey}
-
- \paragraph{Remark:}
- Note that |mindmap| redefines |font| sizes and |sibling angle| depending on
- the current concept level (i.e.\ inside of |level 1 concept|,
- |level 2 concept| etc.). Thus, if you need to redefine these variables, use
-
- |level 1 concept/.append style={font=\small}|
-
- \noindent or
-
- |level 2 concept/.append style={sibling distance=90}|
-
- \noindent \emph{after} the |mindmap| style.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/small mindmap}
- This style includes the |mindmap| style, but additionally changes the
- default size of concepts, fonts and distances so that a medium-sized
- mindmap will fit on an A5 page (A5 pages are half as large as A4 pages).
- Mindmaps with |small mindmap| will also fit onto a standard frame of the
- |beamer| package.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/large mindmap}
- This style includes the |mindmap| style, but additionally changes the
- default size of concepts, fonts and distances so that a medium-sized
- mindmap will fit on an A3 page (A3 pages are twice as large as A4 pages).
-\end{stylekey}
-
-\begin{stylekey}{/tikz/huge mindmap}
- This style causes concepts to be even bigger and it is best used with A2
- paper and above.
-\end{stylekey}
-
-
-\subsection{Concepts Nodes}
-
-The basic entities of mindmaps are called \emph{concepts} in \tikzname. A
-concept is a node of style |concept| and it must be circular for some of the
-connection macros to work.
-
-
-\subsubsection{Isolated Concepts}
-
-The following styles influence how isolated concepts are rendered:
-
-\begin{stylekey}{/tikz/concept}
- This style should be used with all nodes that are concepts, although some
- styles like |extra concept| install this style automatically.
-
- Basically, this style makes the concept node circular and installs a
- uniform color called |concept color|, see below. Additionally, the style
- |every concept| is called.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\tikz[mindmap,concept color=red!50] \node [concept] {Some concept};
-\end{codeexample}
-
- \begin{stylekey}{/tikz/every concept}
- In order to change the appearance of concept nodes, you should change
- this style. Note, however, that the color of a concept should be
- uniform for some of the connection bar stuff to work, so you should not
- change the color or the draw/fill state of concepts using this option.
- It is mostly useful for changing the text color and font.
- \end{stylekey}
-
- \begin{key}{/tikz/concept color=\meta{color}}
- This option tells \tikzname\ which color should be used for filling and
- stroking concepts. The difference between this option and just setting
- |every concept| to the desired color is that this option allows
- \tikzname\ to keep track of the colors used for concepts. This is
- important when you \emph{change} the color between two connected
- concepts. In this case, \tikzname\ can automatically create a shading
- that provides a smooth transition between the old and the new concept
- color; we will come back to this in the next section.
- \end{key}
-\end{stylekey}
-
-\begin{stylekey}{/tikz/extra concept}
- This style is intended for concepts that are not part of the ``mindmap
- tree'', but stand beside it. Typically, they will have a subdued color or
- be smaller. In order to have these concepts appear in a uniform way and in
- order to indicate in the code that these concepts are additional, you can
- use this style.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\begin{tikzpicture}[mindmap,concept color=blue!80]
- \node [concept] {Root concept};
- \node [extra concept] at (10,0) {extra concept};
-\end{tikzpicture}
-\end{codeexample}
- %
- \begin{stylekey}{/tikz/every extra concept}
- Change this style to change the appearance of extra concepts.
- \end{stylekey}
-\end{stylekey}
-
-
-\subsubsection{Concepts in Trees}
-
-As pointed out earlier, \tikzname\ assumes that your mindmap is built using the
-|child| facilities of \tikzname. There are numerous options that influence how
-concepts are rendered at the different levels of a tree.
-
-\begin{stylekey}{/tikz/root concept}
- This style is used for the roots of mindmap trees. By adding something to
- this, you can change how the root of a mindmap will be rendered.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\tikz
- [root concept/.append style={concept color=blue!80,minimum size=3.5cm},
- mindmap]
- \node [concept] {Root concept};
-\end{codeexample}
-
- Note that styles like |large mindmap| redefine these styles, so you should
- add something to this style only inside the picture.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/level 1 concept}
- The |mindmap| style adds this style to the |level 1| style. This means that
- the first level children of a mindmap tree will use this style.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\tikz
- [root concept/.append style={concept color=blue!80},
- level 1 concept/.append style={concept color=red!50},
- mindmap]
- \node [concept] {Root concept}
- child[grow=30] {node[concept] {child}}
- child[grow=0 ] {node[concept] {child}};
-\end{codeexample}
-\end{stylekey}
-
-\begin{stylekey}{/tikz/level 2 concept}
- Works like |level 1 concept|, only for second level children.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/level 3 concept}
- Works like |level 1 concept|.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/level 4 concept}
- Works like |level 1 concept|. Note that there are no fifth and higher level
- styles, you need to modify |level 5| directly in such cases.
-\end{stylekey}
-
-\begin{key}{/tikz/concept color=\meta{color}}
- We saw already that this option is used to change the color of concepts. We
- now have a look at its effect when used on child nodes of a concept.
- Normally, this option simply changes the color of the children. However,
- when the option is given as an option to the |child| operation (and not to
- the |node| operation and also not as an option to all children via the
- |level 1| style), \tikzname\ will smoothly change the concept color from
- the parent's color to the color of the child concept.
-
- Here is an example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\tikz[mindmap,concept color=blue!80]
- \node [concept] {Root concept}
- child[concept color=red,grow=30] {node[concept] {Child concept}}
- child[concept color=orange,grow=0] {node[concept] {Child concept}};
-\end{codeexample}
-
- In order to have a concept color which changes with the hierarchy level, a
- tiny bit of magic is needed:
-% FIXME: is this a bug in the software!? The root concept is black!?
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\tikz[mindmap,text=white,
- root concept/.style={concept color=blue},
- level 1 concept/.append style=
- {every child/.style={concept color=blue!50}}]
- \node [concept] {Root concept}
- child[grow=30] {node[concept] {child}}
- child[grow=0 ] {node[concept] {child}};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Connecting Concepts}
-
-\subsubsection{Simple Connections}
-
-The easiest way to connect two concepts is to draw a line between them. In
-order to give such lines a consistent appearance, it is recommendable to use
-the following style when drawing such lines:
-
-\begin{stylekey}{/tikz/concept connection}
- This style can be used for lines between two concepts. Feel free to
- redefine this style.
-\end{stylekey}
-
-A problem arises when you need to connect concepts after the main mindmap has
-been drawn. In this case you will want the connection lines to lie
-\emph{behind} the main mindmap. However, you can draw the lines only after the
-coordinates of the concepts have been determined. In this case you should place
-the connecting lines on a background layer as in the following example:
-
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds,mindmap}}]
-\begin{tikzpicture}
- [root concept/.append style={concept color=blue!20,minimum size=2cm},
- level 1 concept/.append style={sibling angle=45},
- mindmap]
- \node [concept] {Root concept}
- [clockwise from=45]
- child { node[concept] (c1) {child}}
- child { node[concept] (c2) {child}}
- child { node[concept] (c3) {child}};
- \begin{pgfonlayer}{background}
- \draw [concept connection] (c1) edge (c2)
- edge (c3)
- (c2) edge (c3);
- \end{pgfonlayer}
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{The Circle Connection Bar Decoration}
-
-Instead of a simple line between two concepts, you can also add a bar between
-the two nodes that has slightly organic ends. These bars are also used by
-default as the edges from parents in the mindmap tree.
-
-For the drawing of the bars a special decoration is used, which is defined in
-the |mindmap| library:
-
-\begin{decoration}{circle connection bar}
- This decoration can be used to connect two circles. The start of the
- to-be-decorated path should lie on the border of the first circle, the end
- should lie on the border of the second circle. The following two decoration
- keys should be initialized with the sizes of the circles:
- %
- \begin{itemize}
- \item |start radius|
- \item |end radius|
- \end{itemize}
- %
- Furthermore, the following two decoration keys influence the decoration:
- %
- \begin{itemize}
- \item |amplitude|
- \item |angle|
- \end{itemize}
- %
- The decoration turns a straight line into a path that starts on the border
- of the first circle at the specified angle relative to the line connecting
- the centers of the circles. The path then changes into a rectangle whose
- thickness is given by the amplitude. Finally, the path ends with the same
- angles on the second circle.
-
- Here is an example that should make this clearer:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\begin{tikzpicture}
- [decoration={start radius=1cm,end radius=.5cm,amplitude=2mm,angle=30}]
- \fill[blue!20] (0,0) circle (1cm);
- \fill[red!20] (2.5,0) circle (.5cm);
-
- \filldraw [draw=red,fill=black,
- decorate,decoration=circle connection bar] (1,0) -- (2,0);
-\end{tikzpicture}
-\end{codeexample}
-
- As can be seen, the decorated path consists of three parts and is not
- really useful for drawing. However, if you fill the decorated path only,
- and if you use the same color as for the circles, the result is better.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\begin{tikzpicture}
- [blue!50,decoration={start radius=1cm,
- end radius=.5cm,amplitude=2mm,angle=30}]
- \fill (0,0) circle (1cm);
- \fill (2.5,0) circle (.5cm);
-
- \fill [decorate,decoration=circle connection bar] (1,0) -- (2,0);
-\end{tikzpicture}
-\end{codeexample}
-
- In the above example you may notice the small white line between the
- circles and the decorated path. This is due to rounding errors.
- Unfortunately, for larger distances, the errors can accumulate quite
- strongly, especially since \tikzname\ and \TeX\ are not very good at
- computing square roots. For this reason, it is a good idea to make the
- circles slightly larger to cover up such problems. When using nodes of
- shape |circle|, you can just add the |draw| option with a |line width| of
- one or two points (for very large distances you may need line width up to
- 4pt).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\begin{tikzpicture}
- [blue!50,decoration={start radius=1cm,
- end radius=.5cm,amplitude=2mm,angle=30}]
- \fill (0,0) circle (1cm+1pt);
- \fill (2.4,0) circle (.5cm+1pt);
-
- \fill [decorate,decoration=circle connection bar] (1,0) -- (1.9,0);
-\end{tikzpicture}
-\end{codeexample}
-
- % FIXME: this paragraph appears to be deprecated:
- %Note the slightly strange |outer sep=0pt|. This is needed so that
- %the decorated path lies on the border of the filled circle, not on the
- %border of the stroked circle (which is slightly larger and this
- %slightly larger size is exactly what we wish to use to cover up the
- %rounding errors).
-\end{decoration}
-
-
-\subsubsection{The Circle Connection Bar To-Path}
-
-The |circle connection bar| decoration is a bit complicated to use. Especially
-specifying the radii is quite bothersome (the amplitude and the angle can be
-set once and for all). For this reason, the |mindmap| library defines a special
-to-path that performs the necessary computations for you.
-
-\begin{stylekey}{/tikz/circle connection bar}
- This style installs a rather involved to-path. Unlike normal to-paths, this
- path requires that the start and the target of the to-path are named nodes
- of shape |circle| -- if this is not the case, this path will produce
- errors.
-
- Assuming that the start and the target are circles, the to-path will first
- compute the radii of these circles (by measuring the distance from the
- |center| anchor to some anchor on the border) and will set the
- |start circle| keys accordingly. Next, the |fill| option is set to the
- |concept color| while |draw=none| is set. The decoration is set to
- |circle connection bar|. Finally, the following style is included:
- %
- \begin{stylekey}{/tikz/every circle connection bar}
- Redefine this style to change the appearance of circle connection bar
- to-paths.
- \end{stylekey}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\begin{tikzpicture}[concept color=blue!50,blue!50,outer sep=0pt]
- \node (n1) at (0,0) [circle,minimum size=2cm,fill,draw,thick] {};
- \node (n2) at (2.5,0) [circle,minimum size=1cm,fill,draw,thick] {};
-
- \path (n1) to[circle connection bar] (n2);
-\end{tikzpicture}
-\end{codeexample}
- %
- Note that it is not a good idea to have more than one |to| operation
- together with the option |circle connection bar| in a single |\path|. Use
- the |edge| operation, instead, for creating multiple connections and this
- operation creates a new scope for each edge.
-\end{stylekey}
-
-In a mindmap we sometimes want colors to change from one concept color to
-another. Then, the connection bar should, ideally, consist of a smooth
-transition between these two colors. Getting this right using shadings is a bit
-tricky if you try this ``by hand'', so the |mindmap| library provides a
-special option for facilitating this procedure.
-
-\begin{key}{/tikz/circle connection bar switch color=|from (|\meta{first color}|) to (|\meta{second color}|)|}
- This style works similarly to the |circle connection bar|. The only
- difference is that instead of filling the path with a single color a
- shading is used.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\begin{tikzpicture}[outer sep=0pt]
- \node (n1) at (0,0) [circle,minimum size=2cm,fill,draw,thick,red] {};
- \node (n2) at (30:2.5) [circle,minimum size=1cm,fill,draw,thick,blue] {};
-
- \path (n1) to[circle connection bar switch color=from (red) to (blue)] (n2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Tree Edges}
-
-Most of the time, concepts in a mindmap are connected automatically when the
-mindmap is built as a tree. The reason is that the |mindmap| installs a
-|circle connection bar| path as the |edge from parent path|. Also, the
-|mindmap| option takes care of things like setting the correct |draw| and
-|outer sep| settings and some other stuff.
-
-In detail, the |mindmap| option sets the |edge from parent path| to a path that
-uses the to-path |circle connection bar| to connect the parent node and the
-child node. The |concept color| option (locally) changes this by using
-|circle connection bar switch color| instead with the from-color set to the old
-(parent's) concept color and the to-color set to the new (child's) concept
-color. This means that when you provide the |concept color| option to a |child|
-command, the color will change from the parent's concept color to the specified
-color.
-
-Let us now build a tree that way. Please note that we pass the |concept color|
-to the respective |child| and not to a |node| under it.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\begin{tikzpicture}
- \path[mindmap,concept color=black,text=white]
- node[concept] {Computer Science}
- [clockwise from=0]
- % note that `sibling angle' can only be defined in
- % `level 1 concept/.append style={}'
- child[concept color=green!50!black] {
- node[concept] {practical}
- [clockwise from=90]
- child { node[concept] {algorithms} }
- child { node[concept] {data structures} }
- child { node[concept] {pro\-gramming languages} }
- child { node[concept] {software engineer\-ing} }
- }
- % note that the `concept color' is passed to the `child'(!)
- child[concept color=blue] {
- node[concept] {applied}
- [clockwise from=-30]
- child { node[concept] {databases} }
- child { node[concept] {WWW} }
- }
- child[concept color=red] { node[concept] {technical} }
- child[concept color=orange] { node[concept] {theoretical} };
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Adding Annotations}
-
-An \emph{annotation} is some text outside a mindmap that, unlike an extra
-concept, simply explains something in the mindmap. The following style is
-mainly intended to help readers of the code see that a node in an annotation
-node.
-
-\begin{stylekey}{/tikz/annotation}
- This style indicates that a node is an annotation node. It includes the
- style |every annotation|, which allows you to change this style in a
- convenient fashion.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{mindmap}}]
-\begin{tikzpicture}
- [mindmap,concept color=blue!80,
- every annotation/.style={fill=red!20}]
- \node [concept] (root) {Root concept};
-
- \node [annotation,right] at (root.east)
- {The root concept is, in general, the most important concept.};
-\end{tikzpicture}
-\end{codeexample}
- %
- \begin{stylekey}{/tikz/every annotation}
- This style is included by |annotation|.
- \end{stylekey}
-\end{stylekey}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-patterns.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-patterns.tex
deleted file mode 100644
index 40a370d3fc..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-patterns.tex
+++ /dev/null
@@ -1,572 +0,0 @@
-% 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{Pattern Library}
-\label{section-library-patterns}
-
-\begin{pgflibrary}{patterns}
- The package defines patterns for filling areas.
-\end{pgflibrary}
-
-
-\newcommand\patternindex[1]{%
- \index{#1@\protect\texttt{#1} pattern}%
- \index{Patterns!#1@\protect\texttt{#1}}%
- \texttt{#1}&
- \begin{tikzpicture}[baseline=.5ex]
-
- % Background
- \pattern [path fading=west,pattern=checkerboard light gray]
- (0,0) rectangle (5cm,2em);
-
- \pattern [pattern=#1,pattern color=black] (0,0) rectangle +(1.5cm,2em);
- \pattern [pattern=#1,pattern color=blue] (1.75,0) rectangle +(1.5cm,2em);
- \pattern [pattern=#1,pattern color=red] (3.5,0) rectangle +(1.5cm,2em);
- \end{tikzpicture} \\[1ex]
-}
-
-\newcommand\patternindexinherentlycolored[1]{%
- \index{#1@\protect\texttt{#1} pattern}%
- \index{Patterns!#1@\protect\texttt{#1}}%
- \texttt{#1}&
- \begin{tikzpicture}[baseline=.5ex]
-
- % Background
- \pattern [path fading=west,pattern=checkerboard light gray]
- (0,0) rectangle (5cm,2em);
-
- \pattern [pattern=#1,pattern color=blue] (0,0) rectangle +(5cm,2em);
- \end{tikzpicture} \\[1ex]
-}
-
-
-\subsection{Form-Only Patterns}
-
-\begin{tabular}{ll}
- \emph{Pattern name}
- & \emph{Example (pattern in black, blue, and red on faded checkerboard)} \\
- \patternindex{horizontal lines}
- \patternindex{vertical lines}
- \patternindex{north east lines}
- \patternindex{north west lines}
- \patternindex{grid}
- \patternindex{crosshatch}
- \patternindex{dots}
- \patternindex{crosshatch dots}
- \patternindex{fivepointed stars}
- \patternindex{sixpointed stars}
- \patternindex{bricks}
- \patternindex{checkerboard}
-\end{tabular}
-
-
-\subsection{Inherently Colored Patterns}
-
-\begin{tabular}{ll}
- \emph{Pattern name} & \emph{Example} \\
- \patternindexinherentlycolored{checkerboard light gray}
- \patternindexinherentlycolored{horizontal lines light gray}
- \patternindexinherentlycolored{horizontal lines gray}
- \patternindexinherentlycolored{horizontal lines dark gray}
- \patternindexinherentlycolored{horizontal lines light blue}
- \patternindexinherentlycolored{horizontal lines dark blue}
- \patternindexinherentlycolored{crosshatch dots gray}
- \patternindexinherentlycolored{crosshatch dots light steel blue}
-\end{tabular}
-
-
-\subsection{User-Defined Patterns}
-\label{section-library-patterns-meta}
-
-\noindent\emph{by Mark Wibrow}
-
-\begin{pgflibrary}{patterns.meta}
- Define your own patterns with a syntax similar to |arrows.meta|.
-\end{pgflibrary}
-
-\emph{Caveat:} This library is currently experimental and might change without
-notice. There are some known shortcomings that will hopefully be fixed in the
-future.
-
-\begin{command}{\pgfdeclarepattern\marg{config}}
- This command is used to declare a new pattern. In contrast to the normal
- patterns and in the spirit of |arrows.meta| this command takes a list of
- keys and values to define the pattern. The following keys are available:
- %
- \begin{key}{/pgf/patterns/name=\meta{name}}
- The name of the pattern by which it can be used later on.
- \end{key}
- %
- \begin{key}{/pgf/patterns/type=\meta{type} (default uncolored)}
- The type of the pattern maps to what was called ``form only'' and
- ``inherently colored'' in the language of the normal patterns. The
- available choices are:
- %
- \begin{itemize}
- \item |uncolored| the pattern will obey the surrounding color.
- \item |colored| the pattern will have an intrinsic color.
- \item |form only| synonym for |uncolored|
- \item |inherently colored| synonym for |colored|
- \end{itemize}
- \end{key}
- %
- \begin{key}{/pgf/patterns/x=\meta{dimension} (default 1cm)}
- Unit vector of the coordinate system in the $x$-direction.
- \end{key}
- %
- \begin{key}{/pgf/patterns/y=\meta{dimension} (default 1cm)}
- Unit vector of the coordinate system in the $y$-direction.
- \end{key}
- %
- \begin{key}{/pgf/patterns/parameters=\meta{comma separated list} (default empty)}
- A list of parameters that are passed to the pattern. This is usually a
- list of \TeX\ macros. It is very important that these macros are fully
- expandable because the values they hold are being used for
- deduplication in the PDF file.
- \end{key}
- %
- \begin{key}{/pgf/patterns/defaults=\meta{comma separated list} (default empty)}
- This list holds default assignments to the parameters passed to the
- pattern. The default keys can then be found under the
- |/pgf/pattern keys/| prefix.
- \end{key}
- %
- \begin{key}{/pgf/patterns/bottom left=\meta{pgfpoint}}
- Bottom left corner of the pattern's bounding box, e.g.\
- |\pgfqpoint{-.1pt}{-.1pt}|.
- \end{key}
- %
- \begin{key}{/pgf/patterns/top right=\meta{pgfpoint}}
- Top right corner of the pattern's bounding box, e.g.\
- |\pgfqpoint{3.1pt}{3.1pt}|.
- \end{key}
- %
- \begin{key}{/pgf/patterns/tile size=\meta{pgfpoint}}
- Width and height of a single of the pattern as a \pgfname\ point
- specification, i.e. the $x$ coordinate is the width and the $y$
- specification, i.e.\ the $x$ coordinate is the width and the $y$
- coordinate is the height, e.g.\ |\pgfqpoint{3pt}{3pt}|.
- \end{key}
- %
- \begin{key}{/pgf/patterns/tile transformation=\meta{pgftransformation} (default empty)}
- A \pgfname\ transformation, e.g.\ |\pgftransformrotate{30}|.
- \end{key}
- %
- \begin{key}{/pgf/patterns/code=\meta{code}}
- The code should be \pgfname\ code that can be protocolled. It should not
- contain any color code or nodes.
- \end{key}
- %
- \begin{key}{/pgf/patterns/set up code=\meta{code} (default empty)}
- This code can be set if parameters have to be preprocessed before the
- actual pattern code can be run.
- \end{key}
-\end{command}
-
-\begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}]
-\pgfdeclarepattern{
- name=hatch,
- parameters={\hatchsize,\hatchangle,\hatchlinewidth},
- bottom left={\pgfpoint{-.1pt}{-.1pt}},
- top right={\pgfpoint{\hatchsize+.1pt}{\hatchsize+.1pt}},
- tile size={\pgfpoint{\hatchsize}{\hatchsize}},
- tile transformation={\pgftransformrotate{\hatchangle}},
- code={
- \pgfsetlinewidth{\hatchlinewidth}
- \pgfpathmoveto{\pgfpoint{-.1pt}{-.1pt}}
- \pgfpathlineto{\pgfpoint{\hatchsize+.1pt}{\hatchsize+.1pt}}
- \pgfpathmoveto{\pgfpoint{-.1pt}{\hatchsize+.1pt}}
- \pgfpathlineto{\pgfpoint{\hatchsize+.1pt}{-.1pt}}
- \pgfusepath{stroke}
- }
-}
-
-\tikzset{
- hatch size/.store in=\hatchsize,
- hatch angle/.store in=\hatchangle,
- hatch line width/.store in=\hatchlinewidth,
- hatch size=5pt,
- hatch angle=0pt,
- hatch line width=.5pt,
-}
-
-\begin{tikzpicture}
-\foreach \r in {1,...,4}
- \draw [pattern=hatch, pattern color=red]
- (\r*3,0) rectangle ++(2,2);
-
-\foreach \r in {1,...,4}
- \draw [pattern=hatch, pattern color=green, hatch size=2pt]
- (\r*3,3) rectangle ++(2,2);
-
-\foreach \r in {1,...,4}
- \draw [pattern=hatch, pattern color=blue, hatch size=10pt, hatch angle=21]
- (\r*3,6) rectangle ++(2,2);
-
-\foreach \r in {1,...,4}
- \draw [pattern=hatch, pattern color=orange, hatch line width=2pt]
- (\r*3,9) rectangle ++(2,2);
-\end{tikzpicture}
-\end{codeexample}
-
-There are a couple of predefined \pgfname\ patterns which are similar
-to their normal counterparts. For all of these the |xshift| and |yshift| are
-applied \emph{before} the rotation. If you want to rotate before shifting,
-just rotate in the drawing code.
-
-\begin{pattern}{Lines}
- The |Lines| pattern replaces the |horizontal lines|, |vertical lines|,
- |north east lines|, and |north west lines| patterns. Unfortunately, due to
- the way the old patterns are constructed, namely that they are not simply
- related to each other by rotation, the |Lines| pattern cannot be used as a
- drop-in replacement.
-
- However, the pattern options can be tuned to resemble the other versions
- closely. The available parameters are:
- %
- \begin{key}{/pgf/pattern keys/distance (initially 3pt)}
- Distance between lines.
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/angle (initially 0)}
- By default the lines are horizontal. The whole pattern is rotated by
- this angle. The rotation angle is measured in the mathematically
- positive sense.
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/xshift (initially 0pt)}
- Shifts the whole pattern in $x$-direction (before applying the
- rotation).
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/yshift (initially 0pt)}
- Shifts the whole pattern in $y$-direction (before applying the
- rotation).
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/line width (initially \string\the\string\pgflinewidth)}
- Thickness of the lines.
- \end{key}
- %
- The following settings can be used to reproduce the other |... lines|
- patterns.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns,patterns.meta}}]
-\begin{tikzpicture}
- \draw[pattern={horizontal lines},pattern color=orange]
- (0,0) rectangle +(1,1);
- \draw[pattern={Lines[yshift=.5pt]},pattern color=blue]
- (0,0) rectangle +(1,1);
-
- \draw[pattern={vertical lines},pattern color=orange]
- (1,0) rectangle +(1,1);
- \draw[pattern={Lines[angle=90,yshift=-.5pt]},pattern color=blue]
- (1,0) rectangle +(1,1);
-
- \draw[pattern={north east lines},pattern color=orange]
- (0,1) rectangle +(1,1);
- \draw[pattern={Lines[angle=45,distance={3pt/sqrt(2)}]},pattern color=blue]
- (0,1) rectangle +(1,1);
-
- \draw[pattern={north west lines},pattern color=orange]
- (1,1) rectangle +(1,1);
- \draw[pattern={Lines[angle=-45,distance={3pt/sqrt(2)}]},pattern color=blue]
- (1,1) rectangle +(1,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{pattern}
-
-\begin{pattern}{Hatch}
- The |Hatch| pattern replaces the |grid| and |crosshatch| patterns.
- The |Hatch| pattern without options is a drop-in replacement for the
- |grid| pattern.
- %
- \begin{key}{/pgf/pattern keys/distance (initially 3pt)}
- Distance between crosses.
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/angle (initially 0)}
- By default the lines are horizontal and vertical. The whole pattern is
- rotated by this angle. The rotation angle is measured in the
- mathematically positive sense.
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/xshift (initially 0pt)}
- Shifts the whole pattern in $x$-direction (before applying the
- rotation).
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/yshift (initially 0pt)}
- Shifts the whole pattern in $y$-direction (before applying the
- rotation).
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/line width (initially \string\the\string\pgflinewidth)}
- Thickness of the lines.
- \end{key}
- %
- The following settings can be used to reproduce the |grid| and
- |crosshatch| patterns.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns,patterns.meta}}]
-\begin{tikzpicture}
- \draw[pattern={grid},pattern color=orange]
- (0,0) rectangle +(1,1);
- \draw[pattern={Hatch},pattern color=blue]
- (0,0) rectangle +(1,1);
-
- \draw[pattern={crosshatch},pattern color=orange]
- (1,0) rectangle +(1,1);
- \draw[pattern={Hatch[angle=45,distance={3pt/sqrt(2)},xshift=.1pt]},
- pattern color=blue] (1,0) rectangle +(1,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{pattern}
-
-\begin{pattern}{Dots}
- The |Dots| pattern replaces the |dots| and |crosshatch dots| patterns. The
- |Dots| pattern without options is a drop-in replacement for the |dots|
- pattern.
- %
- \begin{key}{/pgf/pattern keys/distance (initially 3pt)}
- Distance between dots.
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/angle (initially 0)}
- By default the lines are arranged on a regular grid. The whole pattern
- is rotated by this angle. The rotation angle is measured in the
- mathematically positive sense.
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/xshift (initially 0pt)}
- Shifts the whole pattern in $x$-direction (before applying the
- rotation).
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/yshift (initially 0pt)}
- Shifts the whole pattern in $y$-direction (before applying the
- rotation).
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/radius (initially 0.5pt)}
- Radius of the dots.
- \end{key}
- %
- The following settings can be used to reproduce the |dots| and
- |crosshatch dots| patterns.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns,patterns.meta}}]
-\begin{tikzpicture}
- \draw[pattern={dots},pattern color=orange]
- (0,0) rectangle +(1,1);
- \draw[pattern={Dots},pattern color=blue]
- (0,0) rectangle +(1,1);
-
- \draw[pattern={crosshatch dots},pattern color=orange]
- (1,0) rectangle +(1,1);
- \draw[pattern={Dots[angle=45,distance={3pt/sqrt(2)}]},
- pattern color=blue] (1,0) rectangle +(1,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{pattern}
-
-\begin{pattern}{Stars}
- The |Stars| pattern replaces the |fivepointed stars| and |sixpointed stars|
- patterns. However, the stars of the |Stars| pattern are constructed in a
- fundamentally different fashion, so it can't be used as a drop-in
- replacement.
- %
- \begin{key}{/pgf/pattern keys/distance (initially 3mm)}
- Distance between stars.
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/angle (initially 0)}
- By default the stars are arranged on a regular grid. The whole pattern
- is rotated by this angle. The rotation angle is measured in the
- mathematically positive sense.
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/xshift (initially 0pt)}
- Shifts the whole pattern in $x$-direction (before applying the
- rotation).
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/yshift (initially 0pt)}
- Shifts the whole pattern in $y$-direction (before applying the
- rotation).
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/radius (initially 1mm)}
- Outer radius of the enclosing circle of the stars.
- \end{key}
- %
- \begin{key}{/pgf/pattern keys/points (initially 5)}
- Number of pointy ends of the stars.
- \end{key}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns,patterns.meta}}]
-\begin{tikzpicture}
- \draw[pattern={fivepointed stars},pattern color=orange]
- (0,0) rectangle +(1,1);
- \draw[pattern={Stars},pattern color=blue]
- (0,0) rectangle +(1,1);
-
- \draw[pattern={sixpointed stars},pattern color=orange]
- (1,0) rectangle +(1,1);
- \draw[pattern={Stars[points=6]},pattern color=blue]
- (1,0) rectangle +(1,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{pattern}
-
-
-\begin{command}{\tikzdeclarepattern\marg{config}}
- A pattern declared with |\pgfdeclarepattern| can only execute \pgfname\
- code. This command extends the functionality to also allow \tikzname\
- code. All the same keys of |\pgfdeclarepattern| are valid, but some of
- them have been overloaded to give a more natural \tikzname\ syntax.
- %
- \begin{key}{/tikz/patterns/bottom left=\meta{point}}
- Instead of a \pgfname\ name point, this key takes a \tikzname\ point,
- e.g.\ |(-.1,-.1)|.
- \end{key}
- %
- \begin{key}{/tikz/patterns/top right=\meta{point}}
- Instead of a \pgfname\ name point, this key takes a \tikzname\ point,
- e.g.\ |(3.1,3.1)|.
- \end{key}
- %
- \begin{key}{/tikz/patterns/tile size=\meta{point}}
- Instead of a \pgfname\ name point, this key takes a \tikzname\ point,
- e.g.\ |(3,3)|.
- \end{key}
- %
- \begin{key}{/tikz/patterns/tile transformation=\meta{transformation}}
- Instead of a \pgfname\ transformation, this key takes a list of keys
- and value and extracts the resulting transformation from them, e.g.\
- |rotate=30|.
- \end{key}
-
- In addition to the overloaded keys, some new keys have been added.
- %
- \begin{key}{/tikz/patterns/bounding box=\meta{point} and \meta{point}}
- This is a shorthand to set the bounding box. It will assign the first
- point to |bottom left| and the second point to |top right|.
- \end{key}
- %
- \begin{key}{/tikz/patterns/infer tile bounding box=\meta{dimension} (default 0pt)}
- Instead of specifying the bounding box by hand, you can ask \tikzname\
- to infer the size of the bounding box for you. The \meta{dimension}
- parameter is padding that is added around the bounding box.
- \end{key}
-\end{command}
-
-\begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}]
-\tikzdeclarepattern{
- name=flower,
- type=colored,
- bottom left={(-.1pt,-.1pt)},
- top right={(10.1pt,10.1pt)},
- tile size={(10pt,10pt)},
- code={
- \tikzset{x=1pt,y=1pt}
- \path [draw=green] (5,2.5) -- (5, 7.5);
- \foreach \i in {0,60,...,300}
- \path [fill=pink, shift={(5,7.5)}, rotate=-\i]
- (0,0) .. controls ++(120:4) and ++(60:4) .. (0,0);
- \path [fill=red] (5,7.5) circle [radius=1];
- \foreach \i in {-45,45}
- \path [fill=green, shift={(5,2.5)}, rotate=-\i]
- (0,0) .. controls ++(120:4) and ++(60:4) .. (0,0);
- }
-}
-
-\tikz\draw [pattern=flower] circle [radius=1];
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}]
-\tikzdeclarepattern{
- name=mystars,
- type=uncolored,
- bounding box={(-5pt,-5pt) and (5pt,5pt)},
- tile size={(\tikztilesize,\tikztilesize)},
- parameters={\tikzstarpoints,\tikzstarradius,\tikzstarrotate,\tikztilesize},
- tile transformation={rotate=\tikzstarrotate},
- defaults={
- points/.store in=\tikzstarpoints,points=5,
- radius/.store in=\tikzstarradius,radius=3pt,
- rotate/.store in=\tikzstarrotate,rotate=0,
- tile size/.store in=\tikztilesize,tile size=10pt,
- },
- code={
- \pgfmathparse{180/\tikzstarpoints}\let\a=\pgfmathresult
- \fill (90:\tikzstarradius) \foreach \i in {1,...,\tikzstarpoints}{
- -- (90+2*\i*\a-\a:\tikzstarradius/2) -- (90+2*\i*\a:\tikzstarradius)
- } -- cycle;
- }
-}
-
-\begin{tikzpicture}
- \draw[pattern=mystars,pattern color=blue] (0,0) rectangle +(2,2);
- \draw[pattern={mystars[points=7,tile size=15pt]}] (2,0) rectangle +(2,2);
- \draw[pattern={mystars[rotate=45]},pattern color=red] (0,2) rectangle +(2,2);
- \draw[pattern={mystars[rotate=30,points=4,radius=5pt]}] (2,2) rectangle +(2,2);
-\end{tikzpicture}
-\end{codeexample}
-
-Instead of macros you can also use \pgfname\ keys as parameters, if that is
-what you prefer.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{patterns.meta}}]
-\tikzdeclarepattern{
- name=mylines,
- parameters={
- \pgfkeysvalueof{/pgf/pattern keys/size},
- \pgfkeysvalueof{/pgf/pattern keys/angle},
- \pgfkeysvalueof{/pgf/pattern keys/line width},
- },
- bounding box={
- (0,-0.5*\pgfkeysvalueof{/pgf/pattern keys/line width}) and
- (\pgfkeysvalueof{/pgf/pattern keys/size},
- 0.5*\pgfkeysvalueof{/pgf/pattern keys/line width})},
- tile size={(\pgfkeysvalueof{/pgf/pattern keys/size},
- \pgfkeysvalueof{/pgf/pattern keys/size})},
- tile transformation={rotate=\pgfkeysvalueof{/pgf/pattern keys/angle}},
- defaults={
- size/.initial=5pt,
- angle/.initial=45,
- line width/.initial=.4pt,
- },
- code={
- \draw [line width=\pgfkeysvalueof{/pgf/pattern keys/line width}]
- (0,0) -- (\pgfkeysvalueof{/pgf/pattern keys/size},0);
- },
-}
-
-\begin{tikzpicture}
- \draw[pattern={mylines[size=10pt,line width=.8pt,angle=10]},
- pattern color=red] (0,0) rectangle ++(2,2);
- \draw[pattern={mylines[size= 5pt,line width=.8pt,angle=40]},
- pattern color=blue] (2,0) rectangle ++(2,2);
- \draw[pattern={mylines[size=10pt,line width=.4pt,angle=90]},
- pattern color=green] (0,2) rectangle ++(2,2);
- \draw[pattern={mylines[size= 2pt,line width= 1pt,angle=70]},
- pattern color=orange] (2,2) rectangle ++(2,2);
-\end{tikzpicture}
-\end{codeexample}
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-perspective.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-perspective.tex
deleted file mode 100644
index 0c0518f924..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-perspective.tex
+++ /dev/null
@@ -1,446 +0,0 @@
-
-\section{Three Point Perspective Drawing Library}
-
-\noindent\emph{by Max Snippe}
-
-\begin{tikzlibrary}{perspective}
- This library provides tools for perspective drawing with one, two, or three
- vanishing points.
-\end{tikzlibrary}
-
-
-\subsection{Coordinate Systems}
-
-\begin{coordinatesystem}{three point perspective}
- The |three point perspective| coordinate system is very similar to the |xyz|
- coordinate system, save that it will display the provided coordinates with a
- perspective projection.
- %
- \begin{key}{/tikz/cs/x=\meta{number} (initially 0)}
- The $x$ component of the coordinate. Should be given \emph{without} unit.
- \end{key}
- %
- \begin{key}{/tikz/cs/y=\meta{number} (initially 0)}
- Same as |x|.
- \end{key}
- %
- \begin{key}{/tikz/cs/z=\meta{number} (initially 0)}
- Same as |x|.
- \end{key}
-\end{coordinatesystem}
-
-\begin{coordinatesystem}{tpp}
- The |tpp| coordinate system is an alias for the |three point perspective|
- coordinate system.
-\end{coordinatesystem}
-
-
-\subsection{Setting the view}
-
-\begin{key}{/tikz/3d view=\marg{azimuth}\marg{elevation}
- (default \{-30\}\{15\})}
- With the |3d view| option, the projection of the 3D coordinates on the 2D page
- is defined. It is determined by rotating the coordinate system by
- $-\meta{azimuth}$ around the $z$-axis, and by \meta{elevation} around the
- (new) $x$-axis, as shown below.
-
- \begin{tikzpicture}[
- viewpoint/.pic={
- \draw (22.5:0.45) -- (0,0) -- (-22.5:0.45);
- \draw (0,0) ++ (22.5:0.35) arc (22.5:-22.5:0.35);
- \draw (0.225,0) circle (0.02 and 0.09);
- }]
- \begin{scope}[3d view={-20}{20}]
- \draw[->] (-3,0,0) -- (3,0,0) node[pos=1.05]{x};
- \draw[->] (0,-3,0) -- (0,3,0) node[pos=1.05]{y};
- \draw[->] (0,0,-1) -- (0,0,3) node[pos=1.05]{z};
-
- \pgfmathsetmacro\az{50}
- \begin{scope}[canvas is xy plane at z=0]
- \draw[->] (0,0) ++(0,-2) arc (-90:-90+\az:2) coordinate[pos=0.5](az);
- \draw (az) -- ++(-90+\az/2:1) node[below]{\meta{azimuth}};
- \draw[dashed] (0,0) -- ++(-90+\az:3);
- \end{scope}
- \begin{scope}[rotate around z=\az]
- \pgfmathsetmacro\el{50}
- \begin{scope}[canvas is yz plane at x=0]
- \draw[->] (0,0) ++(-2.5,0) arc (180:180-\el:2.5)
- coordinate[pos=0.5](el);
- \draw (el) -- ++(180-\el/2:1) node[above]{\meta{elevation}};
- \draw[dashed] (0,0) --
- pic[solid,sloped,transform shape,pos=1.2]{viewpoint} ++(180-\el:3);
- \end{scope}
- \end{scope}
- \end{scope}
- \end{tikzpicture}
-
- For example, when both \meta{azimuth} and \meta{elevation} are 0$^\circ$,
- $+z$ will be pointing upward, and $+x$ will be pointing right. The default is
- as shown below.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[3d view]
- \draw[->] (-1,0,0) -- (1,0,0) node[pos=1.1]{x};
- \draw[->] (0,-1,0) -- (0,1,0) node[pos=1.1]{y};
- \draw[->] (0,0,-1) -- (0,0,1) node[pos=1.1]{z};
-\end{tikzpicture}
-\end{codeexample}
-\end{key}
-
-\begin{stylekey}{/tikz/isometric view}
- A special kind of |3d view| is isometric, which can be set with the
- |isometric view| style. It simply sets |3d view={-45}{35.26}|. The value for
- \meta{elevation} is determined with $\arctan(1/\sqrt{2})$. In isometric
- projection the angle between any pair of axes is 120$^\circ$, as shown below.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[isometric view]
- \draw[->] (-1,0,0) -- (1,0,0) node[pos=1.1]{x};
- \draw[->] (0,-1,0) -- (0,1,0) node[pos=1.1]{y};
- \draw[->] (0,0,-1) -- (0,0,1) node[pos=1.1]{z};
-\end{tikzpicture}
-\end{codeexample}
-\end{stylekey}
-
-
-\subsection{Defining the perspective}
-
-In this section, the following example cuboid will be used with various
-scaling. As a reference, the axes will be shown too, without perspective
-projection.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\newcommand\simplecuboid[3]{%
- \fill[gray!80!white] (tpp cs:x=0,y=0,z=#3)
- -- (tpp cs:x=0,y=#2,z=#3)
- -- (tpp cs:x=#1,y=#2,z=#3)
- -- (tpp cs:x=#1,y=0,z=#3) -- cycle;
- \fill[gray] (tpp cs:x=0,y=0,z=0)
- -- (tpp cs:x=0,y=0,z=#3)
- -- (tpp cs:x=0,y=#2,z=#3)
- -- (tpp cs:x=0,y=#2,z=0) -- cycle;
- \fill[gray!50!white] (tpp cs:x=0,y=0,z=0)
- -- (tpp cs:x=0,y=0,z=#3)
- -- (tpp cs:x=#1,y=0,z=#3)
- -- (tpp cs:x=#1,y=0,z=0) -- cycle;}
-\newcommand{\simpleaxes}[3]{%
- \draw[->] (-0.5,0,0) -- (#1,0,0) node[pos=1.1]{x};
- \draw[->] (0,-0.5,0) -- (0,#2,0) node[pos=1.1]{y};
- \draw[->] (0,0,-0.5) -- (0,0,#3) node[pos=1.1]{z};}
-
-\begin{tikzpicture}[3d view]
- \simplecuboid{2}{2}{2}
- \simpleaxes{2}{2}{2}
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[setup code,hidden]
-\newcommand\simplecuboid[3]{%
- \fill[gray!80!white] (tpp cs:x=0,y=0,z=#3)
- -- (tpp cs:x=0,y=#2,z=#3)
- -- (tpp cs:x=#1,y=#2,z=#3)
- -- (tpp cs:x=#1,y=0,z=#3) -- cycle;
- \fill[gray] (tpp cs:x=0,y=0,z=0)
- -- (tpp cs:x=0,y=0,z=#3)
- -- (tpp cs:x=0,y=#2,z=#3)
- -- (tpp cs:x=0,y=#2,z=0) -- cycle;
- \fill[gray!50!white] (tpp cs:x=0,y=0,z=0)
- -- (tpp cs:x=0,y=0,z=#3)
- -- (tpp cs:x=#1,y=0,z=#3)
- -- (tpp cs:x=#1,y=0,z=0) -- cycle;}
-
-\newcommand{\simpleaxes}[3]{%
- \draw[->] (-0.5,0,0) -- (#1,0,0) node[pos=1.1]{x};
- \draw[->] (0,-0.5,0) -- (0,#2,0) node[pos=1.1]{y};
- \draw[->] (0,0,-0.5) -- (0,0,#3) node[pos=1.1]{z};}
-\end{codeexample}
-
-\begin{key}{/tikz/perspective=\meta{vanishing points}
- (default p=\{(10,0,0)\},q=\{(0,10,0)\},r=\{(0,0,20)\})}
- The `strength' of the perspective can be determined by setting the location of
- the vanishing points. The default values have a stronger perspective towards
- $x$ and $y$ than towards $z$, as shown below.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[3d view,perspective]
- \simplecuboid{2}{2}{2}
- \simpleaxes{2}{2}{2}
-\end{tikzpicture}
-\end{codeexample}
-%
- From this example it also shows that the maximum dimensions of the cuboid are
- no longer 2 by 2 by 2. This is inherent to the perspective projection.
- %
- \begin{key}{/tikz/perspective/p=\marg{x,y,z} (initially (0,0,0))}
- The location of the vanishing point that determines the `strength' of the
- perspective in $x$-direction can be set with the |p| key.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[
- 3d view,
- perspective={
- p = {(5,0,0)}}]
- \simplecuboid{2}{2}{2}
- \simpleaxes{2}{2}{2}
-\end{tikzpicture}
-\end{codeexample}
- %
- Note also that when only |p| is provided, the perspective in $y$ and $z$
- direction is turned off.
-
- To turn off the perspective in $x$-direction, one must set the $x$ component
- of |p| to \texttt{0} (e.g.\ |p={(0,a,b)}|, where \texttt{a} and \texttt{b}
- can be any number and will be ignored). Or one can provide |q| and |r| and
- omit |p|.
-
- By changing the $y$ and $z$ components of |p|, one can achieve various
- effects.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[
- 3d view,
- perspective={
- p = {(5,0,1)}}]
- \simplecuboid{2}{2}{2}
- \simpleaxes{2}{2}{2}
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[
- 3d view,
- perspective={
- p = {(5,1,0)}}]
- \simplecuboid{2}{2}{2}
- \simpleaxes{2}{2}{2}
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[
- 3d view,
- perspective={
- p = {(5,1,1)}}]
- \simplecuboid{2}{2}{2}
- \simpleaxes{2}{2}{2}
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
- %
- \begin{key}{/tikz/perspective/q=\marg{x,y,z} (initially (0,0,0))}
- Similar to |p|, but can be turned off by setting its $y$ component to
- \texttt{0}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[
- 3d view,
- perspective={
- q = {(0,5,0)}}]
- \simplecuboid{2}{2}{2}
- \simpleaxes{2}{2}{2}
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
- %
- \begin{key}{/tikz/perspective/r=\marg{x,y,z} (initially (0,0,0))}
- Similar to |p|, but can be turned off by setting its $z$ component to
- \texttt{0}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[
- 3d view,
- perspective={
- r = {(0,0,5)}}]
- \simplecuboid{2}{2}{2}
- \simpleaxes{2}{2}{2}
-\end{tikzpicture}
-\end{codeexample}
- %
- \end{key}
-\end{key}
-
-
-\subsection{Shortcomings}
-
-Currently a number of things are not working, mostly due to the fact that PGF
-uses a 2D coordinate system underwater, and perspective projection is a
-non-linear affine transformation which needs to be aware of all three
-coordinates. These three coordinates are currently lost when processing a 3D
-coordinate.
-The issues include, but possibly are not limited to:
-%
-\begin{itemize}
- \item Keys like |shift|, |xshift|, |yshift| are not working
- \item Keys like |rotate around x|, |rotate around y|, and |rotate around z|
- are not working
- \item Units are not working
- \item Most keys from the |3d| library are unsupported, e.g.\ all the
- |canvas is .. plane| keys.
-\end{itemize}
-
-
-\subsection{Examples}
-
-An |r| that lies `below' your drawing can mimic a macro effect.
-%
-\nopagebreak
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[
- isometric view,
- perspective={
- p = {(8,0,0)},
- q = {(0,8,0)},
- r = {(0,0,-8)}}]
-
- \simplecuboid{2}{2}{2}]
-
-\end{tikzpicture}
-\end{codeexample}
-
-A peculiar phenomenon inherent to perspective drawing, is that however great
-your coordinate will become in the direction of the vanishing point, it will
-never reach it.
-%
-\nopagebreak
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[
- isometric view,
- perspective={
- p = {(4,0,0)},
- q = {(0,4,0)}}]
-
- \node[fill=red,circle,inner sep=1.5pt,label=above:p] at (4,0,0){};
-
- \foreach \i in {0,...,100}{
- \filldraw[fill = gray] (tpp cs:x=\i,y=0,z=0)
- -- (tpp cs:x=\i+0.5,y=0,z=0)
- -- (tpp cs:x=\i+0.5,y=2,z=0)
- -- (tpp cs:x=\i,y=2,z=0)
- -- cycle;}
-\end{tikzpicture}
-\end{codeexample}
-
-Even for simple examples, the added perspective might add another `dimension' to
-your drawing. In this case, two vanishing points give a more intuitive result
-then three would.
-%
-\nopagebreak
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[
- scale=0.7,
- 3d view,
- perspective={
- p = {(20,0,0)},
- q = {(0,20,0)}}]
-
- \filldraw[fill=brown] (tpp cs:x=0,y=0,z=0)
- -- (tpp cs:x=0,y=4,z=0)
- -- (tpp cs:x=0,y=4,z=2)
- -- (tpp cs:x=0,y=2,z=4)
- -- (tpp cs:x=0,y=0,z=2) -- cycle;
- \filldraw[fill=red!70!black] (tpp cs:x=0,y=0,z=2)
- -- (tpp cs:x=5,y=0,z=2)
- -- (tpp cs:x=5,y=2,z=4)
- -- (tpp cs:x=0,y=2,z=4) -- cycle;
- \filldraw[fill=brown!80!white] (tpp cs:x=0,y=0,z=0)
- -- (tpp cs:x=0,y=0,z=2)
- -- (tpp cs:x=5,y=0,z=2)
- -- (tpp cs:x=5,y=0,z=0) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
-
-With the vanishing points nearby, the distortion of parallel lines becomes very
-strong. This might lead to \texttt{Dimension too large} errors.
-%
-\nopagebreak
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[
- 3d view,
- perspective={
- p = {(2,0,0)},
- q = {(0,2,0)},
- r = {(0,0,2)}},
- scale=4,
- vanishing point/.style={fill,circle,inner sep=2pt}]
-
- \simplecuboid{3}{1}{2}
-
- \node[vanishing point,label = right:p] (p) at (2,0,0){};
- \node[vanishing point,label = left:q] (q) at (0,2,0){};
- \node[vanishing point,label = above:r] (r) at (0,0,2){};
-
- \begin{scope}[dotted]
- \foreach \y in {0,1}{
- \foreach \z in {0,2}{
- \draw (tpp cs:x=0,y=\y,z=\z) -- (p.center);}}
- \foreach \x in {0,3}{
- \foreach \z in {0,2}{
- \draw (tpp cs:x=\x,y=0,z=\z) -- (q.center);}}
- \foreach \x in {0,3}{
- \foreach \y in {0,1}{
- \draw (tpp cs:x=\x,y=\y,z=0) -- (r.center);}}
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-% A more complex example.
-\iffalse
-Of course these examples can become as complex as desired, but as with any 3D
-drawing using \tikzname, the order of drawing commands is important and can
-become increasingly more complex.
-%
-\nopagebreak
-\begin{codeexample}[preamble={\usetikzlibrary{perspective}}]
-\begin{tikzpicture}[
- cycle of vertices/.style 2 args={
- insert path={
- foreach \i [count=\j,evaluate=\j as \k using
- {ifthenelse(\j==1,"","-- "}] in {#2}{\k (vert-#1-\i)} -- cycle}},
- scale=0.7,
- line join=round,
- bottom/.style={draw=white!50!black,fill=white!40!black},
- front/.style={draw=white!50!black,fill=black},
- side/.style={draw=white!50!black,fill=white!80!black},
-]
- \begin{scope}[
- 3d view={-20}{0},
- perspective={
- p = {(20,0,0)},
- q = {(0,20,0)},
- r = {(5,1,50)},
- }]
- \path foreach \x/\y/\z [count=\i] in {
- 3.5/2.0/0.0,3.5/2.0/4.0,6.0/2.0/4.0,6.5/2.0/3.5,6.5/2.0/0.5,6.0/2.0/0.0,
- 4.5/2.0/1.0,4.5/2.0/3.0,5.5/2.0/3.0,5.5/2.0/1.0,3.5/0.0/0.0,3.5/0.0/4.0,
- 6.0/0.0/4.0,6.5/0.0/3.5,6.5/0.0/0.5,6.0/0.0/0.0,4.5/0.0/1.0,4.5/0.0/3.0,
- 5.5/0.0/3.0,5.5/0.0/1.0%
- }{(tpp cs:x=\x,y=\y,z=\z) coordinate[name=vert-D-\i]};
- \filldraw[front,cycle of vertices={D}{1,...,6},
- cycle of vertices={D}{7,10,9,8}];
- \filldraw[side,cycle of vertices={D}{10,9,19,20}];
- \filldraw[bottom,cycle of vertices={D}{8,9,19,18}];
- \filldraw[front,cycle of vertices={D}{11,...,16},
- cycle of vertices={D}{17,20,19,18}];
- \filldraw[side,cycle of vertices={D}{1,2,12,11}];
- % '3'
- \path foreach \x/\y/\z [count=\i] in {
- 0.0/2.0/0.0,0.0/2.0/1.0,2.0/2.0/1.0,2.0/2.0/1.5,0.0/2.0/1.5,0.0/2.0/2.5,
- 2.0/2.0/2.5,2.0/2.0/3.0,0.0/2.0/3.0,0.0/2.0/4.0,3.0/2.0/4.0,3.0/2.0/0.0,
- 0.0/0.0/0.0,0.0/0.0/1.0,2.0/0.0/1.0,2.0/0.0/1.5,0.0/0.0/1.5,0.0/0.0/2.5,
- 2.0/0.0/2.5,2.0/0.0/3.0,0.0/0.0/3.0,0.0/0.0/4.0,3.0/0.0/4.0,3.0/0.0/0.0%
- }{(tpp cs:x=\x,y=\y,z=\z) coordinate[name=vert-3-\i]};
- \filldraw[front,cycle of vertices={3}{1,...,12}];
- \filldraw[side,cycle of vertices={3}{3,4,16,15}];
- \filldraw[side,cycle of vertices={3}{7,8,20,19}];
- \filldraw[side,cycle of vertices={3}{1,2,14,13}];
- \filldraw[side,cycle of vertices={3}{5,6,18,17}];
- \filldraw[side,cycle of vertices={3}{9,10,22,21}];
- \filldraw[bottom,cycle of vertices={3}{4,5,17,16}];
- \filldraw[bottom,cycle of vertices={3}{8,9,21,20}];
- \filldraw[front,cycle of vertices={3}{13,...,24}];
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-\fi
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-petri.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-petri.tex
deleted file mode 100644
index e5f0360bf7..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-petri.tex
+++ /dev/null
@@ -1,380 +0,0 @@
-% 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{Petri-Net Drawing Library}
-
-\begin{tikzlibrary}{petri}
- This packages provides shapes and styles for drawing Petri nets.
-\end{tikzlibrary}
-
-
-\subsection{Places}
-
-The package defines a style for drawing places of Petri nets.
-
-\begin{stylekey}{/tikz/place}
- This style indicates that a node is a place of a Petri net. Usually, the
- text of the node should be empty since places do not contain any text. You
- should use the |label| option to add text outside the node like its name or
- its capacity. You should use the |tokens| options, explained in
- Section~\ref{section-tokens}, to add tokens inside the place.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri,positioning}}]
-\begin{tikzpicture}
- \node[place,label=above:$p_1$,tokens=2] (p1) {};
- \node[place,label=below:$p_2\ge1$,right=of p1] (p2) {};
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{stylekey}{/tikz/every place}
- This style is evoked by the style |place|. To change the appearance of
- places, you can change this style.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri,positioning}}]
-\begin{tikzpicture}
- [every place/.style={draw=blue,fill=blue!20,thick,minimum size=9mm}]
- \node[place,tokens=7,label=above:$p_1$] (p1) {};
- \node[place,structured tokens={3,2,9},
- label=below:$p_2\ge1$,right=of p1] (p2) {};
-\end{tikzpicture}
-\end{codeexample}
- \end{stylekey}
-\end{stylekey}
-
-
-\subsection{Transitions}
-
-Transitions are also nodes. They should be drawn using the following style:
-
-\begin{stylekey}{/tikz/transition}
- This style indicates that a node is a transition. As for places, the text
- of a transition should be empty and the |label| option should be used for
- adding labels.
-
- To connect a transition to places, you can use the |edge| command as in the
- following example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri,positioning}}]
-\begin{tikzpicture}
- \node[place,tokens=2,label=above:$p_1$] (p1) {};
- \node[place,label=above:$p_2\ge1$,right=of p1] (p2) {};
-
- \node[transition,below right=of p1,label=below:$t_1$] {}
- edge[pre] (p1)
- edge[post] node[auto] {2} (p2);
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{stylekey}{/tikz/every transition}
- This style is evoked by the style |transition|.
- \end{stylekey}
-
- \begin{stylekey}{/tikz/pre}
- This style can be used with paths leading \emph{from} a transition
- \emph{to} a place to indicate that the place is in the pre-set of the
- transition. By default, this style is |<-,shorten <=1pt|, but feel free
- to redefine it.
- \end{stylekey}
-
- \begin{stylekey}{/tikz/post}
- This style is also used with paths leading \emph{from} a transition
- \emph{to} a place, but this time the place is in the post-set of the
- transition. Again, feel free to redefine it.
- \end{stylekey}
-
- \begin{stylekey}{/tikz/pre and post}
- This style is to be used to indicate that a place is both in the pre-
- and post-set of a transition.
- \end{stylekey}
-\end{stylekey}
-
-
-\subsection{Tokens}
-\label{section-tokens}
-
-Interestingly, the most complicated aspect of drawing Petri nets in \tikzname\
-turns out to be the placement of tokens.
-
-Let us start with a single token. They are also nodes and there is a simple
-style for typesetting them.
-
-\begin{stylekey}{/tikz/token}
- This style indicates that a node is a token. By default, this causes the
- node to be a small black circle. Unlike places and transitions, it
- \emph{does} make sense to provide text for the token node. Such text will
- be typeset in a tiny font and in white on black (naturally, you can easily
- change this by setting the style |every token|).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri,positioning}}]
-\begin{tikzpicture}
- \node[place,label=above:$p_1$] (p1) {};
- \node[token] at (p1) {};
-
- \node[place,label=above:$p_2$,right=of p1] (p2) {};
- \node[token] at (p2) {$y$};
-\end{tikzpicture}
-\end{codeexample}
- %
- \begin{stylekey}{/tikz/every token}
- Change this style to change the appearance of tokens.
- \end{stylekey}
-\end{stylekey}
-
-In the above example, it is bothersome that we need an extra command for the
-token node. Worse, when we have \emph{two} tokens on a node, it is difficult to
-place both nodes inside the node without overlap.
-
-The Petri library offers a solution to this problem: The |children are tokens|
-style.
-
-\begin{stylekey}{/tikz/children are tokens}
- The idea behind this style is to use trees mechanism for placing tokens.
- Every token lying on a place is treated as a child of the node. Normally
- this would have the effect that the tokens are placed below the place and
- they would be connected to the place by an edge. The |children are tokens|
- style, however, redefines the growth function of trees such that it places
- the children next to each other inside (or, rather, on top) of the place
- node. Additionally, the edge from the parent node is not drawn.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri}}]
-\begin{tikzpicture}
- \node[place,label=above:$p_1$] {}
- [children are tokens]
- child {node [token] {1}}
- child {node [token] {2}}
- child {node [token] {3}};
-\end{tikzpicture}
-\end{codeexample}
-
- In detail, what happens is the following: Tree growth functions tell
- \tikzname\ where it should place the children of nodes. These functions get
- passed the number of children that a node has an the number of the child
- that should be placed. The special tree growth function for tokens has a
- special mapping for each possible number of children up to nine children.
- This mapping decides for each child where it should be placed on top of the
- place. For example, a single child is placed directly on top of the place.
- Two children are placed next to each other, separated by the
- |token distance|. Three children are placed in a triangle whose side
- lengths are |token distance|; and so on up to nine tokens. If you wish to
- place more than nice tokens on a place, you will have to write your own
- placement code.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri}}]
-\begin{tikzpicture}
- \node[place,label=above:$p_2$] {}
- [children are tokens]
- child {node [token] {1}}
- child {node [token,fill=red] {2}}
- child {node [token,fill=red] {2}}
- child {node [token] {1}};
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{key}{/tikz/token distance=\meta{distance}}
- This specifies the distance between the centers of the tokens in the
- arrangements of the option |children are tokens|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri}}]
-\begin{tikzpicture}
- \node[place,label=above:$p_3$] {}
- [children are tokens,token distance=1.1ex]
- child {node [token] {}}
- child {node [token,red] {}}
- child {node [token,blue] {}}
- child {node [token] {}};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{stylekey}
-
-The |children are tokens| option gives you a lot of flexibility, but it is a
-bit cumbersome to use. For this reason there are some options that help in
-standard situations. They all use |children are tokens| internally, so any
-change to, say, the |every token| style will affect how these options depict
-tokens.
-
-\begin{key}{/tikz/tokens=\meta{number}}
- This option is given to a |place| node, not to a |token| node. The effect
- of this option is to add \meta{number} many child nodes to the place, each
- having the style |token|. Thus, the following two pieces of codes have the
- same effect:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri}}]
-\tikz
- \node[place] {}
- [children are tokens]
- child {node [token] {}}
- child {node [token] {}}
- child {node [token] {}};
-\tikz
- \node[place,tokens=3] {};
-\end{codeexample}
- %
- It is legal to say |tokens=0|, no tokens are drawn in this case. This
- option does not handle ten or more tokens correctly. If you need this many
- tokens, you will have to program your own code.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri}}]
-\begin{tikzpicture}[every place/.style={minimum size=9mm}]
-
- \foreach \x/\y/\tokennumber in {0/2/1,1/2/2,2/2/3,
- 0/1/4,1/1/5,2/1/6,
- 0/0/7,1/0/8,2/0/9}
- \node [place,tokens=\tokennumber] at (\x,\y) {};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/colored tokens=\meta{color list}}
- This option, which must also be given when a place node is being created,
- gets a list of colors as parameter. It will then add as many tokens to the
- place as there are colors in this list, each filled correspondingly.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri}}]
-\tikz \node[place,colored tokens={black,black,red,blue}] {};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/structured tokens=\meta{token texts}}
- This option, which must again be passed to a place, gets a list of texts
- for tokens. For each text, a new token will be added to the place.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri}}]
-\tikz \node[place,structured tokens={$x$,$y$,$z$}] {};
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{petri}}]
-\begin{tikzpicture}[every place/.style={minimum size=9mm}]
-
- \foreach \x/\y/\tokennumber in {0/2/1,1/2/2,2/2/3,
- 0/1/4,1/1/5,2/1/6,
- 0/0/7,1/0/8,2/0/9}
- \node [place,structured tokens={1,...,\tokennumber}] at (\x,\y) {};
-\end{tikzpicture}
-\end{codeexample}
- %
- If you use lots of structured tokens, consider redefining the |every token|
- style so that the tokens are larger.
-\end{key}
-
-
-\subsection{Examples}
-
-\begin{codeexample}[preamble={\usetikzlibrary{petri}}]
-\begin{tikzpicture}[yscale=-1.6,xscale=1.5,thick,
- every transition/.style={draw=red,fill=red!20,minimum size=3mm},
- every place/.style={draw=blue,fill=blue!20,minimum size=6mm}]
-
- \foreach \i in {1,...,6} {
- \node[place,label=left:$p_\i$] (p\i) at (0,\i) {};
- \node[place,label=right:$q_\i$] (q\i) at (8,\i) {};
- }
- \foreach \name/\var/\vala/\valb/\height/\x in
- {m1/m_1/f/t/2.25/3,m2/m_2/f/t/2.25/5,h/\mathit{hold}/1/2/4.5/4} {
- \node[place,label=above:{$\var = \vala$}] (\name\vala) at (\x,\height) {};
- \node[place,yshift=-8mm,label=below:{$\var = \valb$}] (\name\valb) at (\x,\height) {};
- }
- \node[token] at (p1) {}; \node[token] at (q1) {};
- \node[token] at (m1f) {}; \node[token] at (m2f) {};
- \node[token] at (h1) {};
-
- \node[transition] at (1.5,1.5) {} edge [pre] (p1) edge [post] (p2);
- \node[transition] at (1.5,2.5) {} edge [pre] (p2) edge[pre] (m1f)
- edge [post](p3) edge[post] (m1t);
- \node[transition] at (1.5,3.3) {} edge [pre] (p3) edge [post] (p4)
- edge [pre and post] (h1);
- \node[transition] at (1.5,3.7) {} edge [pre] (p3) edge [pre] (h2)
- edge [post] (p4) edge [post] (h1.west);
- \node[transition] at (1.5,4.3) {} edge [pre] (p4) edge [post] (p5)
- edge [pre and post] (m2f);
- \node[transition] at (1.5,4.7) {} edge [pre] (p4) edge [post] (p5)
- edge [pre and post] (h2);
- \node[transition] at (1.5,5.5) {} edge [pre] (p5) edge [pre] (m1t)
- edge [post] (p6) edge [post] (m1f);
- \node[transition] at (1.5,6.5) {} edge [pre] (p6) edge [post] (p1.south east);
- \node[transition] at (6.5,1.5) {} edge [pre] (q1) edge [post] (q2);
- \node[transition] at (6.5,2.5) {} edge [pre] (q2) edge [pre] (m2f)
- edge [post] (q3) edge [post] (m2t);
- \node[transition] at (6.5,3.3) {} edge [pre] (q3) edge [post] (q4)
- edge [pre and post] (h2);
- \node[transition] at (6.5,3.7) {} edge [pre] (q3) edge [pre] (h1)
- edge [post] (q4) edge [post] (h2.east);
- \node[transition] at (6.5,4.3) {} edge [pre] (q4) edge [post] (q5)
- edge [pre and post] (m1f);
- \node[transition] at (6.5,4.7) {} edge [pre] (q4) edge [post] (q5)
- edge [pre and post] (h1);
- \node[transition] at (6.5,5.5) {} edge [pre] (q5) edge [pre] (m2t)
- edge [post] (q6) edge [post] (m2f);
- \node[transition] at (6.5,6.5) {} edge [pre] (q6) edge [post] (q1.south west);
-\end{tikzpicture}
-\end{codeexample}
-
-Here is the same net once more, but with these styles changes:
-%
-\begin{codeexample}[code only]
-\begin{tikzpicture}[yscale=-1.1,thin,>=stealth,
- every transition/.style={fill,minimum width=1mm,minimum height=3.5mm},
- every place/.style={draw,thick,minimum size=6mm}]
-\end{codeexample}
-
-\begin{tikzpicture}[yscale=-1.1,thin,>=stealth,
- every transition/.style={fill,minimum width=1mm,minimum height=3.5mm},
- every place/.style={draw,thick,minimum size=6mm}]
-
- \foreach \i in {1,...,6} {
- \node[place,label=left:$p_\i$] (p\i) at (0,\i) {};
- \node[place,label=right:$q_\i$] (q\i) at (8,\i) {};
- }
- \foreach \name/\var/\vala/\valb/\height/\x in
- {m1/m_1/f/t/2.25/3,m2/m_2/f/t/2.25/5,h/\mathit{hold}/1/2/4.5/4} {
- \node[place,label=above:{$\var = \vala$}] (\name\vala) at (\x,\height) {};
- \node[place,yshift=-8mm,label=below:{$\var = \valb$}] (\name\valb) at (\x,\height) {};
- }
- \node[token] at (p1) {}; \node[token] at (q1) {};
- \node[token] at (m1f) {}; \node[token] at (m2f) {};
- \node[token] at (h1) {};
-
- \node[transition] at (1.5,1.5) {} edge [pre] (p1) edge [post] (p2);
- \node[transition] at (1.5,2.5) {} edge [pre] (p2) edge [pre] (m1f)
- edge [post] (p3) edge [post] (m1t);
- \node[transition] at (1.5,3.3) {} edge [pre] (p3) edge [post] (p4)
- edge [pre and post] (h1);
- \node[transition] at (1.5,3.7) {} edge [pre] (p3) edge [pre] (h2)
- edge [post] (p4) edge [post] (h1.west);
- \node[transition] at (1.5,4.3) {} edge [pre] (p4) edge [post] (p5)
- edge [pre and post] (m2f);
- \node[transition] at (1.5,4.7) {} edge [pre] (p4) edge [post] (p5)
- edge [pre and post] (h2);
- \node[transition] at (1.5,5.5) {} edge [pre] (p5) edge [pre] (m1t)
- edge [post] (p6) edge [post] (m1f);
- \node[transition] at (1.5,6.5) {} edge [pre] (p6) edge [post] (p1.south east);
- \node[transition] at (6.5,1.5) {} edge [pre] (q1) edge [post] (q2);
- \node[transition] at (6.5,2.5) {} edge [pre] (q2) edge [pre] (m2f)
- edge [post] (q3) edge [post] (m2t);
- \node[transition] at (6.5,3.3) {} edge [pre] (q3) edge [post] (q4)
- edge [pre and post] (h2);
- \node[transition] at (6.5,3.7) {} edge [pre] (q3) edge [pre] (h1)
- edge [post] (q4) edge [post] (h2.east);
- \node[transition] at (6.5,4.3) {} edge [pre] (q4) edge [post] (q5)
- edge [pre and post] (m1f);
- \node[transition] at (6.5,4.7) {} edge [pre] (q4) edge [post] (q5)
- edge [pre and post] (h1);
- \node[transition] at (6.5,5.5) {} edge [pre] (q5) edge [pre] (m2t)
- edge [post] (q6) edge [post] (m2f);
- \node[transition] at (6.5,6.5) {} edge [pre] (q6) edge [post] (q1.south west);
-\end{tikzpicture}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex
deleted file mode 100644
index 689e3f0c1b..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex
+++ /dev/null
@@ -1,694 +0,0 @@
-% Copyright 2018 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{Plot Handler Library}
-\label{section-library-plothandlers}
-
-\begin{pgflibrary}{plothandlers}
- This library packages defines additional plot handlers, see
- Section~\ref{section-plot-handlers} for an introduction to plot handlers.
- The additional handlers are described in the following.
-
- This library is loaded automatically by \tikzname.
-\end{pgflibrary}
-
-
-\subsection{Curve Plot Handlers}
-
-\begin{command}{\pgfplothandlercurveto}
- This handler will issue a |\pgfpathcurveto| command for each point of the
- plot, \emph{except} possibly for the first. As for the line-to handler,
- what happens with the first point can be specified using
- |\pgfsetmovetofirstplotpoint| or |\pgfsetlinetofirstplotpoint|.
-
- Obviously, the |\pgfpathcurveto| command needs, in addition to the points
- on the path, some control points. These are generated automatically using a
- somewhat ``dumb'' algorithm: Suppose you have three points $x$, $y$, and
- $z$ on the curve such that $y$ is between $x$ and $z$:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlercurveto
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
-
- In order to determine the control points of the curve at the point $y$, the
- handler computes the vector $z-x$ and scales it by the tension factor (see
- below). Let us call the resulting vector $s$. Then $y+s$ and $y-s$ will be
- the control points around $y$. The first control point at the beginning of
- the curve will be the beginning itself, once more; likewise the last
- control point is the end itself.
-\end{command}
-
-\begin{command}{\pgfsetplottension\marg{value}}
- Sets the factor used by the curve plot handlers to determine the distance
- of the control points from the points they control. The higher the
- curvature of the curve points, the higher this value should be. A value of
- $1$ will cause four points at quarter positions of a circle to be connected
- using a circle. The default is $0.5$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfsetplottension{0.75}
- \pgfplothandlercurveto
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfplothandlerclosedcurve}
- This handler works like the curve-to plot handler, only it will add a new
- part to the current path that is a closed curve through the plot points.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerclosedcurve
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Constant Plot Handlers}
-
-There are several plot handlers which produce piecewise constant interpolations
-between successive points:
-
-\begin{command}{\pgfplothandlerconstantlineto}
- This handler works like the line-to plot handler, only it will produce a
- connected, piecewise constant path to connect the points.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerconstantlineto
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfplothandlerconstantlinetomarkright}
- A variant of |\pgfplothandlerconstantlineto| which places its mark on the
- right line ends.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerconstantlinetomarkright
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfplothandlerconstantlinetomarkmid}
- A variant of |\pgfplothandlerconstantlineto| which places its mark on the
- center of the line.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerconstantlinetomarkmid
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
- The plot handler always connects two data points by a horizontal line
- starting from the previous data points, followed by a vertical line in the
- middle between the two data points, followed by a horizontal line between
- the middle and the current data point. This results in a symmetric constant
- plot handler for constant mesh width.
-\end{command}
-
-\begin{command}{\pgfplothandlerjumpmarkleft}
- This handler works like the line-to plot handler, only it will produce a
- non-connected, piecewise constant path to connect the points. If there are
- any plot marks, they will be placed on the left open pieces.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerjumpmarkleft
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfplothandlerjumpmarkright}
- This handler works like the line-to plot handler, only it will produce a
- non-connected, piecewise constant path to connect the points. If there are
- any plot marks, they will be placed on the right open pieces.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerjumpmarkright
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfplothandlerjumpmarkmid}
- This handler works like the |\pgfplothandlerconstantlinetomarkmid|, but it
- will produce a non-connected, piecewise constant path to connect the
- points. If there are any plot marks, they will be placed in the center of
- the horizontal line segment..
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerjumpmarkmid
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
- See |\pgfplothandlerconstantlinetomarkmid| for details.
-\end{command}
-
-
-\subsection{Comb Plot Handlers}
-
-There are three ``comb'' plot handlers. Their name stems from the fact that the
-plots they produce look like ``combs'' (more or less).
-
-\begin{command}{\pgfplothandlerxcomb}
- This handler converts each point in the plot stream into a line from the
- $y$-axis to the point's coordinate, resulting in a ``horizontal comb''.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerxcomb
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfplothandlerycomb}
- This handler converts each point in the plot stream into a line from the
- $x$-axis to the point's coordinate, resulting in a ``vertical comb''.
-
- This handler is useful for creating ``bar diagrams''.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerycomb
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfplothandlerpolarcomb}
- This handler converts each point in the plot stream into a line from the
- origin to the point's coordinate.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerpolarcomb
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\pgfname\ bar or comb plots usually draw something from zero to the current
-plot's coordinate. The ``zero'' offset can be changed using an input stream
-which returns the desired offset successively for each processed coordinate.
-
-There are two such streams, which can be configured independently. The first
-one returns ``zeros'' for coordinate~$x$, the second one returns ``zeros'' for
-coordinate~$y$. They are used as follows.
-%
-\begin{codeexample}[code only]
-\pgfplotxzerolevelstreamstart
-\pgfplotxzerolevelstreamnext % assigns \pgf@x
-\pgfplotxzerolevelstreamnext
-\pgfplotxzerolevelstreamnext
-\pgfplotxzerolevelstreamend
-\end{codeexample}
-%
-\begin{codeexample}[code only]
-\pgfplotyzerolevelstreamstart
-\pgfplotyzerolevelstreamnext % assigns \pgf@x
-\pgfplotyzerolevelstreamend
-\end{codeexample}
-%
-Different zero level streams can be implemented by overwriting these macros.
-
-\begin{command}{\pgfplotxzerolevelstreamconstant\marg{dimension}}
- This zero level stream always returns \marg{dimension} instead of $x=0$pt.
-
- It is used for |xcomb| and |xbar|.
-\end{command}
-
-\begin{command}{\pgfplotyzerolevelstreamconstant\marg{dimension}}
- This zero level stream always returns \marg{dimension} instead of $y=0$pt.
-
- It is used for |ycomb| and |ybar|.
-\end{command}
-
-
-\subsection{Bar Plot Handlers}
-\label{section-plotlib-bar-handlers}
-
-While comb plot handlers produce a line-to operation to generate combs, bar
-plot handlers employ rectangular shapes, allowing filled bars (or pattern
-bars).
-
-\begin{command}{\pgfplothandlerybar}
- This handler converts each point in the plot stream into a rectangle from
- the $x$-axis to the point's coordinate. The rectangle is placed centered at
- the $x$-axis.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerybar
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfplothandlerxbar}
- This handler converts each point in the plot stream into a rectangle from
- the $y$-axis to the point's coordinate. The rectangle is placed centered at
- the $y$-axis.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlerxbar
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\label{key-bar-width}%
-\begin{key}{/pgf/bar width=\marg{dimension} (initially 10pt)}
-\keyalias{tikz}
- Sets the width of |\pgfplothandlerxbar| and |\pgfplothandlerybar| to
- \marg{dimension}. The argument \marg{dimension} will be evaluated using the
- math parser.
-\end{key}
-
-\label{key-bar-shift}%
-\begin{key}{/pgf/bar shift=\marg{dimension} (initially 0pt)}
-\keyalias{tikz}
- Sets a shift used by |\pgfplothandlerxbar| and |\pgfplothandlerybar| to
- \marg{dimension}. It has the same effect as |xshift|, but it applies only
- to those bar plots. The argument \marg{dimension} will be evaluated using
- the math parser.
-\end{key}
-
-\begin{command}{\pgfplotbarwidth}
- Expands to the value of |/pgf/bar width|.
-\end{command}
-
-\begin{command}{\pgfplothandlerybarinterval}
- This handler is a variant of |\pgfplothandlerybar| which works with
- intervals instead of points.
-
- Bars are drawn between successive input coordinates and the width is
- determined relatively to the interval length.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,2) node {$x_1$} (1,1) node {$x_2$} (2,.5) node {$x_3$} (4,0.7) node {$x_4$};
- \pgfplothandlerybarinterval
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{2cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
-
- In more detail, if $(x_i,y_i)$ and $(x_{i+1},y_{i+1})$ denote successive
- input coordinates, the bar will be placed above the interval
- $[x_i,x_{i+1}]$, centered at
- %
- \[ x_i + \text{\meta{bar interval shift}} \cdot (x_{i+1} - x_i) \]
- %
- with width
- %
- \[ \text{\meta{bar interval width}} \cdot (x_{i+1} - x_i). \]
- %
- Here, \meta{bar interval shift} and \meta{bar interval width} denote the
- current values of the associated options.
-
- If you have $N+1$ input points, you will get $N$ bars (one for each
- interval). The $y$~value of the last point will be ignored.
-\end{command}
-
-\begin{command}{\pgfplothandlerxbarinterval}
- As |\pgfplothandlerybarinterval|, this handler provides bar plots with
- relative bar sizes and offsets, one bar for each $y$~coordinate interval.
-\end{command}
-
-\begin{key}{/pgf/bar interval shift=\marg{factor} (initially 0.5)}
-\label{key-bar-interval-shift}%
-\keyalias{tikz}
- Sets the \emph{relative} shift of |\pgfplothandlerxbarinterval| and
- |\pgfplothandlerybarinterval| to \meta{factor}. As
- |/pgf/bar interval width|, the argument is relative to the interval length
- of the input coordinates.
-
- The argument \marg{scale} will be evaluated using the math parser.
-\end{key}
-
-\begin{key}{/pgf/bar interval width=\marg{scale} (initially 1)}
-\label{key-bar-interval-width}%
-\keyalias{tikz}
- Sets the \emph{relative} width of |\pgfplothandlerxbarinterval| and
- |\pgfplothandlerybarinterval| to \marg{scale}. The argument is relative to
- $(x_{i+1} - x_i)$ for $y$~bar plots and relative to $(y_{i+1}-y_i)$ for
- $x$~bar plots.
-
- The argument \marg{scale} will be evaluated using the math parser.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[bar interval width=0.5]
- \draw[gray]
- (0,3) -- (0,-0.1)
- (1,3) -- (1,-0.1)
- (2,3) -- (2,-0.1)
- (4,3) -- (4,-0.1);
- \pgfplothandlerybarinterval
- \begin{scope}[bar interval shift=0.25,fill=blue]
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{2cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreampoint{\pgfpoint{4cm}{0.7cm}}
- \pgfplotstreamend
- \pgfusepath{fill}
- \end{scope}
- \begin{scope}[bar interval shift=0.75,fill=red]
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{3cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{0.2cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.7cm}}
- \pgfplotstreampoint{\pgfpoint{4cm}{0.2cm}}
- \pgfplotstreamend
- \pgfusepath{fill}
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
- %
- Please note that bars are always centered, so we have to use shifts $0.25$
- and $0.75$ instead of $0$ and $0.5$.
-\end{key}
-
-
-\subsection{Gapped Plot Handlers}
-\label{section-plot-gapped}
-
-\begin{command}{\pgfplothandlergaplineto}
- This handler will connect the points of the plots by straight line
- segments. However, at the start and the end of the lines there will be a
- small gap, given by the following key:
- %
- \begin{key}{/pgf/gap around stream point=\meta{dimension} (initially 1.5pt)}
- The \meta{dimension} by which the lines between consecutive stream
- points are shortened at the beginning and end.
- \end{key}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \pgfplothandlergaplineto
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfplothandlergapcycle}
- Works like |\pgfplothandlergaplineto|, but the last point is connected to
- the first in the same fashion:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \pgfplothandlergapcycle
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Mark Plot Handler}
-\label{section-plot-marks}
-
-\begin{command}{\pgfplothandlermark\marg{mark code}}
- This command will execute the \meta{mark code} for some points of the plot,
- but each time the coordinate transformation matrix will be set up such that
- the origin is at the position of the point to be plotted. This way, if the
- \meta{mark code} draws a little circle around the origin, little circles
- will be drawn at some point of the plot.
-
- By default, a mark is drawn at all points of the plot. However, two
- parameters $r$ and $p$ influence this. First, only every $r$th mark is
- drawn. Second, the first mark drawn is the $p$th. These parameters can be
- influenced using the commands below.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlermark{\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}}
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
-
- Typically, the \meta{code} will be |\pgfuseplotmark{|\meta{plot mark
- name}|}|, where \meta{plot mark name} is the name of a predefined plot
- mark.
-\end{command}
-
-\begin{command}{\pgfsetplotmarkrepeat\marg{repeat}}
- Sets the $r$ parameter to \meta{repeat}, that is, only every $r$th mark
- will be drawn.
-\end{command}
-
-\begin{command}{\pgfsetplotmarkphase\marg{phase}}
- Sets the $p$ parameter to \meta{phase}, that is, the first mark to be drawn
- is the $p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so on.
-\end{command}
-
-\begin{command}{\pgfplothandlermarklisted\marg{mark code}\marg{index list}}
- This command works similar to the previous one. However, marks will only be
- placed at those indices in the given \meta{index list}. The syntax for the
- list is the same as for the |\foreach| statement. For example, if you
- provide the list |1,3,...,25|, a mark will be placed only at every second
- point. Similarly, |1,2,4,8,16,32| yields marks only at those points that
- are powers of two.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlermarklisted
- {\pgfpathcircle{\pgfpointorigin}{4pt}\pgfusepath{stroke}}
- {1,3}
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfuseplotmark\marg{plot mark name}}
- Draws the given \meta{plot mark name} at the origin. The \meta{plot mark
- name} must have been previously declared using |\pgfdeclareplotmark|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlermark{\pgfuseplotmark{pentagon}}
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfdeclareplotmark\marg{plot mark name}\marg{code}}
- Declares a plot mark for later used with the |\pgfuseplotmark| command.
- %
-\begin{codeexample}[]
-\pgfdeclareplotmark{my plot mark}
- {\pgfpathcircle{\pgfpoint{0cm}{1ex}}{1ex}\pgfusepathqstroke}
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfplothandlermark{\pgfuseplotmark{my plot mark}}
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsetplotmarksize\marg{dimension}}
- This command sets the \TeX\ dimension |\pgfplotmarksize| to
- \meta{dimension}. This dimension is a ``recommendation'' for plot mark code
- at which size the plot mark should be drawn; plot mark code may choose to
- ignore this \meta{dimension} altogether. For circles, \meta{dimension}
- should be the radius, for other shapes it should be about half the
- width/height.
-
- The predefined plot marks all take this dimension into account.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[gray] (0,0) node {x} (1,1) node {y} (2,.5) node {z};
- \pgfsetplotmarksize{1ex}
- \pgfplothandlermark{\pgfuseplotmark{*}}
- \pgfplotstreamstart
- \pgfplotstreampoint{\pgfpoint{0cm}{0cm}}
- \pgfplotstreampoint{\pgfpoint{1cm}{1cm}}
- \pgfplotstreampoint{\pgfpoint{2cm}{0.5cm}}
- \pgfplotstreamend
- \pgfusepath{stroke}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{textoken}{\pgfplotmarksize}
- A \TeX\ dimension that is a ``recommendation'' for the size of plot marks.
-\end{textoken}
-
-The following plot marks are predefined (the filling color has been set to
-yellow):
-
-\medskip
-\begin{tabular}{lc}
- \plotmarkentry{*}
- \plotmarkentry{x}
- \plotmarkentry{+}
-\end{tabular}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-marks.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-marks.tex
deleted file mode 100644
index d6d8f7cb28..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-marks.tex
+++ /dev/null
@@ -1,116 +0,0 @@
-% Copyright 2018 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{Plot Mark Library}
-
-\begin{pgflibrary}{plotmarks}
- This library defines a number of plot marks.
-\end{pgflibrary}
-
-This library defines the following plot marks in addition to |*|, |x|, and |+|
-(the filling color has been set to a dark yellow):
-
-{
-\catcode`\|=12
-\medskip
-\begin{tabular}{lc}
- \plotmarkentry{-}
- \index{*vbar@\protect\texttt{\protect\myvbar} plot mark}%
- \index{Plot marks!*vbar@\protect\texttt{\protect\myvbar}}
- %
- \texttt{\char`\\pgfuseplotmark\char`\{\declare{|}\char`\}} &
- \tikz\draw [color=black!25] plot [
- mark=|,mark options={fill=yellow,draw=black}
- ] coordinates {(0,0) (.5,0.2) (1,0) (1.5,0.2)};\\
- \plotmarkentry{o}
- \plotmarkentry{asterisk}
- \plotmarkentry{star}
- \plotmarkentry{10-pointed star}
- \plotmarkentry{oplus}
- \plotmarkentry{oplus*}
- \plotmarkentry{otimes}
- \plotmarkentry{otimes*}
- \plotmarkentry{square}
- \plotmarkentry{square*}
- \plotmarkentry{triangle}
- \plotmarkentry{triangle*}
- \plotmarkentry{diamond}
- \plotmarkentry{diamond*}
- \plotmarkentry{halfdiamond*}
- \plotmarkentry{halfsquare*}
- \plotmarkentry{halfsquare right*}
- \plotmarkentry{halfsquare left*}
- \plotmarkentry{pentagon}
- \plotmarkentry{pentagon*}
- \plotmarkentry{Mercedes star}
- \plotmarkentry{Mercedes star flipped}
- \plotmarkentry{halfcircle}
- \plotmarkentry{halfcircle*}
- \plotmarkentry{heart}
- \plotmarkentry{text}
-\end{tabular}
-}
-
-Note that each of the provided marks can be rotated freely by means of
-|mark options={rotate=90}| or |every mark/.append style={rotate=90}|.
-
-\begin{key}{/pgf/mark color=\marg{color} (initially empty)}
- Defines the additional fill color for the |halfcircle|, |halfcircle*|,
- |halfdiamond*| and |halfsquare*| markers. An empty value uses |white|
- (which is the initial configuration). The special value |none| disables
- filling of the respective parts.
-
- Note that |halfsquare| will be filled with |mark color|, and the starred
- variant |halfsquare*| will be filled half with |mark color| and half with
- the actual |fill| color.
-\end{key}
-
-
-{
-\def\showit#1{%
- \tikz\draw[color=black!25] plot[#1,mark options={fill=examplefill,draw=black}] coordinates{(0,0) (.5,0.2) (1,0) (1.5,0.2)};}%
-
-\begin{key}{/pgf/text mark=\marg{text} (initially p)}
- Changes the text shown by |mark=text|.
-
- With |/pgf/text mark=m|: \pgfkeys{/pgf/text mark=m}\showit{mark=text}
-
- With |/pgf/text mark=A|: \pgfkeys{/pgf/text mark=A}\showit{mark=text}
-
- There is no limitation about the number of characters or whatever. In fact,
- any \TeX\ material can be inserted as \marg{text}, including images.
-\end{key}
-
-\begin{key}{/pgf/text mark as node=\marg{boolean} (initially false)}
- Configures how |mark=text| will be drawn: either as |\node| or as |\pgftext|.
-
- The first choice is highly flexible and possibly slow, the second is very
- fast and usually enough.
-\end{key}
-
-\begin{key}{/pgf/text mark style=\marg{options for \texttt{mark=text}}}
- Defines a set of options which control the appearance of |mark=text|.
-
- If |/pgf/text mark as node=false| (the default), \marg{options} is provided
- as argument to |\pgftext| -- which provides only some basic keys like
- |left|, |right|, |top|, |bottom|, |base| and |rotate|.
-
- If |/pgf/text mark as node=true|, \marg{options} is provided as argument to
- |\node|. This means you can provide a very powerful set of options
- including |anchor|, |scale|, |fill|, |draw|, |rounded corners| etc.
-\end{key}
-
-}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-profiler.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-profiler.tex
deleted file mode 100644
index 6e5200a9fe..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-profiler.tex
+++ /dev/null
@@ -1,242 +0,0 @@
-% Copyright 2019 by Christian Feuersaenger
-%
-% 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{Profiler Library}
-
-{\noindent {\emph{by Christian Feuersänger}}}
-
-\begin{pgflibrary}{profiler}
- A library to simplify the optimization of runtime speed of \TeX\ programs.
-
- It relies on the |pdftex| primitive
- \declareandlabel{\pdfelapsedtime}\footnote{The primitive is emulated in
- lua\TeX.} to count (fractional) seconds and counts total time and self time
- for macro invocations.
-\end{pgflibrary}
-
-
-\subsection{Overview}
-
-The intended audience for this library are people writing \TeX\ code which
-should be optimized. It is certainly \emph{not} useful for the end-user.
-
-The work flow for the optimization is simple: the preamble contains
-configuration commands like
-%
-\begin{codeexample}[code only]
-\usepgflibrary{profiler}
-\pgfprofilenewforenvironment{tikzpicture}
-\pgfprofilenewforcommand{\pgfkeys}{1}
-\end{codeexample}
-%
-\noindent and then, the time between |\begin{tikzpicture}| and
-|\end{tikzpicture}| and the time required to call |\pgfkeys| will be collected.
-
-At the end, a short usage summary like
-%
-\begin{codeexample}[code only, tikz syntax=false]
- pgflibraryprofiler(main job) {total time=1.07378sec; (100.0122%) self time=0.034sec; (3.1662%)}
- pgflibraryprofiler(<ENV>tikzpicture) {total time=1.03978sec; (96.84601%) self time=1.00415sec; (93.52722%)}
- pgflibraryprofiler(<CS>pgfkeys) {total time=0.03563sec; (3.31726%) self time=0.03563sec; (3.31726%)}
-\end{codeexample}
-%
-\noindent will be provided in the log file, furthermore, the same information
-is available in a text table called |\jobname.profiler.|\meta{datetime}|.dat|
-which is of the form:
-%
-\begin{codeexample}[code only, tikz syntax=false]
-profilerentry totaltime[s] totaltime[percent] selftime[s] selftime[percent]
-main job 1.07378 100.0122 0.034 3.1662
-<ENV>tikzpicture 1.03978 96.84601 1.00415 93.52722
-<CS>pgfkeys 0.03563 3.31726 0.03563 3.31726
-\end{codeexample}
-%
-Here, the |totaltime| means the time used for all invocations of the respective
-profiler entry (one row in the table). The |selftime| measures time which is
-not already counted for in another profiler entry which has been invoked within
-the current one. The example above is not very exciting: the main job consists
-only of several (quite complex) pictures and nothing else. Thus, its total time
-is large. However, the self time is very small because the |tikzpicture|s are
-counted separately, and they have been invoked within the |main job|. The
-|\pgfkeys| control sequence has been invoked within the |tikzpicture|, that's
-why the |selftime| for the |tikzpicture| is a little bit smaller than its
-|totaltime|.
-
-
-\subsection{Requirements}
-
-The library works with |pdftex| and |luatex|. Furthermore, it requires a more
-or less recent version of |pdftex| which supports the |\pdfelapsedtime|
-directive.
-
-
-\subsection{Defining Profiler Entries}
-
-Unlike profilers for C/C++ or java, this library doesn't extract information
-about every \TeX\ macro automatically, nor does it collect information for each
-of them. Instead, every profiler entry needs to be defined explicitly. Only
-defined profiler entries will be processed.
-
-\begin{command}{\pgfprofilenew\marg{name}}
- Defines a new profiler entry named \meta{name}.
-
- This updates a set of internal registers used to track the profiler entry.
- The \meta{name} can be arbitrary, it doesn't need to be related to any
- \TeX\ macro.
-
- The actual job of counting seconds is accomplished using
- |\pgfprofilestart|\marg{name} followed eventually by the command
- |\pgfprofileend|\marg{name}.
-
- It doesn't hurt if |\pgfprofilenew| is called multiple times with the same
- name.
-\end{command}
-
-\begin{command}{\pgfprofilenewforcommand\oarg{profiler entry name}\marg{\textbackslash macro}\marg{arguments}}
- Defines a new profiler entry which will measure the time spent in
- \meta{\textbackslash macro}. This calls |\pgfprofilenew| and replaces the
- current definition of \meta{\textbackslash macro} with a new one.
-
- If \oarg{profiler entry name} has been provided, this defines the argument
- for |\pgfprofilenew|. It is allowed to use the same name for multiple
- commands; in this case, they are treated as if it where the same command.
- If the optional argument is not used, the profiler entry will be called
- `\declareandlabel{\pgfprofilecs}\meta{macro}' (\meta{macro} without
- backslash) where |\pgfprofilecs| is predefined to be |<CS>|.
-
- The replacement macro will collect all required arguments, start counting,
- invoke the original macro definition and stop counting.
-
- The following macro types are supported within |\pgfprofilenewforcommand|:
- %
- \begin{itemize}
- \item commands which take one (optional) argument in square brackets
- followed by one optional argument which has to be delimited by
- curly braces (use an empty argument for \meta{arguments} in this
- case),
- \item commands which take one (optional) argument in square brackets
- and \emph{exactly} \meta{arguments} arguments afterwards.
- \end{itemize}
-
- Take a look at |\pgfprofilenewforcommandpattern| in case you have more
- complicated commands.
-
- Note that the library can't detect if a command has been redefined
- somewhere.
-\end{command}
-
-\begin{command}{\pgfprofilenewforcommandpattern\oarg{profiler entry name}\marg{\textbackslash macro}\marg{argument pattern}\marg{invocation pattern}}
- A variant of |\pgfprofilenewforcommand| which can be used with arbitrary
- \meta{argument patterns}. Example:
- %
-\begin{codeexample}[code only]
-\def\mymacro#1\to#2\in#3{ ... }
-\pgfprofilenewforcommandpattern{\mymacro}{#1\to#2\in#3}{{#1}\to{#2}\in{#3}}
-\end{codeexample}
-
- Note that |\pgfprofilenewforcommand| is a special case of
- |\pgfprofilenewforcommandpattern|:
- %
-\begin{codeexample}[code only]
-\def\mymacro#1#2{ ... }
-\pgfprofilenewforcommand\macro{2}
-\pgfprofilenewforcommandpattern{\mymacro}{#1#2}{{#1}{#2}}
-\end{codeexample}
- %
- Thus, \meta{argument pattern} is a copy-paste from the definition of your
- command. The \meta{invocation pattern} is used by the |profiler| library to
- invoke the \emph{original} command, so it is closely related to
- \meta{argument pattern}, but it needs extra curly braces around each
- argument.
-
- The behavior of |\pgfprofilenewforcommandpattern| is the same as discussed
- above: it defines a new profiler entry which will measure the time spent in
- \meta{\textbackslash macro}. The details about this definition has already
- been described. Note that up to one optional argument in square brackets is
- also checked automatically.
-
- If you like to profile a command which doesn't match here for whatever
- reasons, you'll have to redefine it manually and insert |\pgfprofilestart|
- and |\pgfprofileend| in appropriate places.
-\end{command}
-
-\begin{command}{\pgfprofileshowinvocationsfor\marg{profiler entry name}}
- Enables verbose output for \emph{every} invocation of \meta{profiler entry
- name}.
-
- This is only available for profiler entries for commands (those created by
- |\pgfprofilenewforcommand| for example). It will also show all given
- arguments.
-\end{command}
-
-\begin{command}{\pgfprofileshowinvocationsexpandedfor\marg{profiler entry name}}
- A variant of |\pgfprofileshowinvocationsfor| which will expand all
- arguments for \meta{profiler entry name} before showing them. The
- invocation as such is not affected by this expansion.
-
- This expansion (with |\edef|) might yield unrecoverable errors for some
- commands. Handle with care.
-\end{command}
-
-\begin{command}{\pgfprofilenewforenvironment\oarg{profiler entry name}\marg{environment name}}
- Defines a new profiler entry which measures time spent in the environment
- \meta{environment name}.
-
- This calls |\pgfprofilenew| and handles the begin/end of the environment
- automatically.
-
- The argument for |\pgfprofilenew| is \meta{profiler entry name}, or, if
- this optional argument is not used, it is
- `\declareandlabel{\pgfprofileenv}\meta{environment name}' where
- |\pgfprofileenv| is predefined as |<ENV>|. Again, it is permitted to use
- the same \meta{profiler entry name} multiple times to merge different
- commands into one output section.
-\end{command}
-
-\begin{command}{\pgfprofilestart\marg{profiler entry name}}
- Starts (or resumes) timing of \meta{profiler entry name}. The argument must
- have been declared in the preamble using |\pgfprofilenew|.
-
- Nested calls of |\pgfprofilestart| with the same argument will be ignored.
-
- The invocation of this command doesn't change the environment: it doesn't
- introduce any \TeX\ groups nor does it modify the token list.
-\end{command}
-
-\begin{command}{\pgfprofileend\marg{profiler entry name}}
- Stops (or interrupts) timing of \meta{profiler entry name}.
-
- This command finishes a preceding call to |\pgfprofilestart|.
-\end{command}
-
-\begin{command}{\pgfprofilepostprocess}
- For \LaTeX, this command is installed automatically in |\end{document}|. It
- stops all running timings, evaluates them and returns the result into the
- logfile. Furthermore, it generates a text table called
- |\jobname.profiler.|\meta{YYYY}|-|\meta{MM}|-|\meta{DD}|_|\meta{HH}|h_|\meta{MM}|m.dat|
- with the same information.
-
- Note that the |profiler| library predefines two profiler entries, namely
- |main job| which counts time from the beginning of the document until
- |\pgfprofilepostprocess| and |preamble| which counts time from the
- beginning of the document until |\begin{document}|.
-\end{command}
-
-\begin{command}{\pgfprofilesetrel\marg{profiler entry name} (initially main job)}
- Sets the profiler entry whose total time will be used to compute all other
- relative times. Thus, \meta{profiler entry name} will use $100\%$ of the
- total time per definition, all other relative times are relative to this
- one.
-\end{command}
-
-\begin{command}{\pgfprofileifisrunning\marg{profiler entry name}\marg{true code}\marg{false code}}
- Invokes \marg{true code} if \marg{profiler entry name} is currently running
- and \marg{false code} otherwise.
-\end{command}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-rdf.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-rdf.tex
deleted file mode 100644
index 1e9debff43..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-rdf.tex
+++ /dev/null
@@ -1,1040 +0,0 @@
-% 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{Resource Description Framework Library}
-\label{section-library-rdf}
-\label{section-tikz-rdf}
-
-With \todosp{why two labels? Both don't seem to be used.} certain output
-formats (in particular, with \textsc{svg}), \tikzname\ can add \emph{semantic
-annotations} to an output file. Consider as an example the drawing of a finite
-automaton. In your \TeX\ code, you might have a nice description of the
-automaton like the following:
-%
-\begin{codeexample}[code only]
-\tikz[automaton] \graph { a[state, initial] ->[transition] b [state] ->[transition] c[state, final] };
-\end{codeexample}
-%
-This description of the automaton carries a lot of ``semantic information''
-like the information that the node |a| is not just some node, but actually the
-initial state of the automaton, while |c| is a final state. Unfortunately, in
-the output produced \tikzname, this information is normally ``lost'': In the
-output, |a| is only a short text, possibly with a circle drawn around it; but
-there is no information that \emph{this} text and \emph{this} circle together
-form the state of an automaton.
-
-As a human (more precisely, as a computer scientist), you might ``see'' that
-the text and the circle form a state, but most software will have a very hard
-time retrieving this semantic information from the output. In particular, it is
-more or less impossible to design a search engine that you can query to find,
-say, ``all automata with three states'' in a document.
-
-This is the point were \emph{semantic annotations} come in. These are small
-labels or ``hints'' in the \emph{output} that tell you (and, more importantly,
-a program) that the text and the circle together form a state of an automaton.
-There is a standard for specifying such annotations (``resource description
-framework annotations'', abbreviated \textsc{rdf}a) and \tikzname\ provides a
-way of adding such annotations to an output file using the |rdf engine| key,
-explained in a moment. Note, however, that the output format must support such
-annotations; currently \tikzname\ only supports \textsc{svg}.
-
-
-\subsection{Starting the RDF Engine}
-
-\begin{tikzlibrary}{rdf}
- You need to load this library for the keys described in the following.
- However, even when this library is loaded, \textsc{rdf} information is only
- written to the output inside scopes where the following key is set:
- %
- \begin{key}{/tikz/rdf engine on}
- Switches ``on'' the generation of \textsc{rdf} information for the
- current \TeX\ scope. The idea is that libraries can internally use the
- |rdf engine| key (explained below) a lot in order to provide good
- semantic information in the output when desired, but need not worry
- that this will bloat output files since users have to use this key
- explicitly to include semantic information in the output.
- \end{key}
-\end{tikzlibrary}
-
-\begin{key}{/tikz/rdf engine=\meta{rdf keys}}
- This key only has an effect when |rdf engine on| is called, otherwise the
- argument is silently ignored. The \meta{rdf keys} get executed with the
- path prefix |/tikz/rdf engine| at the beginning of the current scope (for a
- node, at the beginning of the node's scope). Depending on which keys are
- used, semantic information gets to be added to the output.
-
- Note that you cannot simply the keys with path prefix |/tikz/rdf engine|
- directly since they need to be executed at very specific times during
- \tikzname's processing of scopes. Always call those keys via this key.
-\end{key}
-
-The following key is useful for generally setting the prefix for a larger
-number of annotations:
-
-\begin{key}{/tikz/rdf engine/prefix=\meta{prefix: iri}}
- Inside the current scope, you can use \meta{prefix}|:| inside curies
- (compact universal resource identifier expressions, see the \textsc{rdfa}
- specification) as an abbreviation for the \meta{iri}. (It has the same
- effect as the |prefix| attribute in \textsc{rdf}a.) You can use this key
- several times for a given scope.
- %
-\begin{codeexample}[code only]
-\scoped [rdf engine = {
- prefix = {rdf: http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark},
- prefix = {automata: http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/},
- statement = { ..., predicate = rdf:type, object = automata:state },
- statement = { ..., predicate = rdf:type, object = automata:final },
- }] ...
-\end{codeexample}
- %
- The above could also be written more verbosely as
- %
-\begin{codeexample}[code only]
-\scoped [rdf engine = {
- statement = { ...,
- predicate = http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark type,
- object = http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/state }
- },
- statement = { ...,
- predicate = http://www.w3.org/1999/02/22-rdf-syntax-ns\tikzrdfhashmark type,
- object = http://www.tcs.uni-luebeck.de/ontologies/2016/04/28/automata/final }
- }] ...
-\end{codeexample}
-
- The use of the command |\tikzrdfhashmark| is necessary since \TeX\ assigns
- a special meaning to hash marks. The command simple expands to a ``normal''
- hash mark for use in texts.
- %
- \begin{command}{\tikzrdfhashmark}
- Expands to |#| with catcode 11.
- \end{command}
-\end{key}
-
-
-\subsection{Creating Statements}
-
-\tikzname's method of adding semantic information to an output is based on the
-principles underlying the \emph{resource description framework} (\textsc{rdf}).
-In this framework, all semantic information is encoded using a large graph
-consisting of nodes and connecting directed edges, but the nodes are called
-\emph{resources} and the edges are called \emph{statements}. A resource is
-identified by an \textsc{iri}, an \emph{internationalized resource identifier,}
-which basically looks like the well-known \textsc{url}s, but allows additional
-Unicode characters. Note that these \textsc{iri}s do not need to point to
-``real'' webpages, they are just a way of conceptually identifying resources
-uniquely and permanently. Similarly, each edge (statement) of the \textsc{rdf}
-graph has such an \textsc{iri} attached to it, which identifies the ``flavour''
-of the arc.
-
-In a ``mathematical'' graph, each edge has a ``tail'' and a ``head'' vertex and
-a label, but in the context of the resource description framework these notions
-are called differently: As mentioned before, an edge is called a
-\emph{statement}, the tail of this edge is called the \emph{subject}, the head
-is called the \emph{object} (in the linguistic sense), and the label is called
-the \emph{predicate}. Thus, a statement is -- quite fittingly -- a triple
-``subject predicate object''.
-
-Note that in the \textsc{rdf} framework \emph{all} semantic information must be
-encoded using statements of this fixed kind. Many semantic notions are easy to
-store in this way such as ``Albert Einstein was a physicist'' (``Albert
-Einstein'' is the subject, ``was'' is the predicate, ``a physicist'' is the
-object), but other notions do not fit well like ``The automaton has states
-$q_1$, $q_2$, $q_a$, and $q_b$'' since there are several objects in the
-statement. Nevertheless, all information must be encoded as simple statements
-with a single subject, a single predicate, and a single object.
-
-You add an \textsc{rdf} statement to the output file using the following key:
-
-\begin{key}{/tikz/rdf engine/statement=\marg{options}}
- Each use of this key will add one \textsc{rdf} statement to the output
- file. The \meta{options} will be executed with the path prefix
- |/tikz/rdf engine/statements| and must use the three keys |subject|,
- |predicate|, and |object| to specify the three components of the statement
- (these keys can, however, be called by styles internally, so not all
- statements will explicitly set these three keys). Note that \emph{all three
- must always be set}, it is \emph{not} possible to setup, say, just a
- subject for a scope and then omit the subject for statements inside the
- scope. (However, using styles you can setup things in such a way that a
- certain subject is used for several statements.)
- %
-\begin{codeexample}[code only]
-\tikz [rdf engine = {
- statement = {
- subject = http://www.example.org/persons/Einstein,
- predicate = http://www.example.org/predicates/isA,
- object = http://www.example.org/professions/physicist
- },
- statement = {
- subject = http://www.example.org/persons/Curie,
- predicate = http://www.example.org/predicates/isA,
- object = http://www.example.org/professions/physicist
- }}] { ... }
-\end{codeexample}
-
- The statements are normally added at the beginning of the scope where the
- |rdf enging| command is used (except when the |object| is |scope content|,
- which is explained later). This means that when you use |prefix| inside an
- |rdf engine| command, it will apply to all statements, regardless of the
- order.
-
- \begin{key}{/tikz/rdf engine/statements/subject=\meta{subject}}
- Sets the subject of the to-be-created statement. The \meta{subject} can
- be in one of two possible formats:
- %
- \begin{enumerate}
- \item A curie (a \emph{compact universal resource identifier
- expression,} see the \textsc{rdfa} specification for details).
- Examples are standard \textsc{url}s like
- |http://www.example.org|, but also text like |#my_automaton|.
- Note that in order to include a hashmark in a curie you should
- use the command |\tikzrdfhashmark|, which expands to a hash
- mark (\TeX\ treats hash marks in a special way, which is why
- this command is used here).
- \item When the \meta{subject} starts with an opening parenthesis,
- that is, with ``|(|'', the \meta{subject} must have the form
- |(|\meta{node or scope name}|)|. In this case, the \meta{node
- or scope name} must be the name of an already existing node
- (the current node or scope is considered as ``existing'' here).
- Then, the curie |#|\meta{id} is used as subject, where the
- \meta{id} is a unique internal identifier for the node.
-
- As an example, suppose you wish to specify that a node has some
- other node as child, you could write the following:
- %
-\begin{codeexample}[code only]
-\tikz [ rdf engine = { prefix = { rels: http://www.example.org/relations/} } ] {
- \node (fritz) { Fritz };
- \node (heinz) at (2,0) { Heinz };
- \draw [->] (fritz) -- (heinz)
- [rdf engine = {
- statement = {
- subject = (fritz),
- predicate = rels:isSonOf,
- object = (heinz)
- } } ];
-}
-\end{codeexample}
- \end{enumerate}
- %
- You can use a macro as \meta{subject}, it will be expanded before the
- above syntax check is done.
-
- If you use the |subject| key several times inside a single |statement|
- command, (only) the last subject is used.
- \end{key}
-
- \begin{key}{/tikz/rdf engine/statements/predicate=\meta{predicate}}
- Sets the predicate for the statement. The syntax is exactly the same as
- for the subject. Unlike for subjects, you can use the predicate key
- several times inside a single statement and the uses will
- ``accumulate'' and several statements are created, namely one statement
- for each use of |predicate| for the subject and object specified inside
- the use of |statement|. This behavior is not very systematic (it
- violates the rule ``one statement per |statement|'') and you should
- normally use the |statement| once for each use of the |predicate|
- key. However, in conjunction with the object |scope content| it is
- necessary to allow this behavior.
- \end{key}
-
- \begin{key}{/tikz/rdf engine/statements/object=\meta{object}}
- Sets the object for the statement. The syntax allowed for the
- \meta{object} is as follows:
- %
- \begin{enumerate}
- \item As for |subject| and |predicate| you can use a curie here.
- This is the default unless one of the following special cases
- is used:
- \item As for |subject| and |predicate|, you can use the syntax
- |(|\meta{name of node or scope}|)| to create and use a curie
- for the node or scope.
- \item If the \meta{object} starts with |"|, it must have the syntax
- |"|\meta{literals}|"|. In this case, the object of the
- statement is not a curie (not a normal ``resource'') but the
- string of \meta{literals} given.
- \item If the \meta{object} is the text ``|scope content|'', the
- object of the statement is actually the whole contents of the
- scope to which this statement is attached.
- \item The two previous cases can be combined in the form of an
- object of the form |"|\meta{literals}|" and scope content|. In
- this case, the contents of the scope is ``normally'' the
- object, but this gets ``overruled'' by the \meta{literals}.
- Formally, this means that the object is the \meta{literals},
- but the intended semantics is that the object is the scope
- content, only for further processing it should be considered to
- be \meta{literals}. A typical example is the case where the
- scope content is, say, the text ``January 1st, 2000'' but the
- \meta{literals} are set to |2000-01-01|, which is easier for
- software to process:
- %
-\begin{codeexample}[code only]
-\node [rdf engine = {
- statement = {
- subject = ...,
- predicate = dc:Date,
- object = "2000-01-01" and scope content
- } } ] { January 1st, 2000 };
-\end{codeexample}
- \end{enumerate}
- %
- For the last two cases, only one statement may be given per scope that
- has the |scope content| as its object; if more than one is given, the
- last one wins. This is the reason why several uses of |predicate| are
- allowed in a |statement|.
- \end{key}
-
- \begin{key}{/tikz/rdf engine/statements/has type=\meta{type}}
- This style is a shorthand for |predicate=rdf:type| and
- |object=|\meta{type}.
- \end{key}
-\end{key}
-
-
-\subsection{Creating Resources}
-
-In \textsc{rdf} statements, when you can use the name of a \tikzname\ scope or
-node surrounded by parenthesis, a curie is inserted into the output that
-references this scope or node. While this makes it easy to describe
-relationships between existing nodes, in library code (\textsc{rdf} generation
-code added to library styles and gets executed as a ``byproduct'') there are
-two situations where this method is insufficient:
-%
-\begin{enumerate}
- \item You may sometimes wish to create additional resources in the
- \textsc{rdf} graph that are not represented by any concrete node or
- scope in the \tikzname\ picture. For instance, a finite automaton has a
- set of states and a set of transitions, but neither of these
- ``containers'' has any concrete representation in the output. One
- could, of course, create ``dummy scopes'' for this purpose, but this is
- rather hard to do inside styles of a library.
- \item You may not know the name of the current scope in library code. For
- instance, a style like |state|, which can be added to a node to
- indicate that the node is supposed to be a state in a finite automaton,
- might contain something like the following code:
- %
-\begin{codeexample}[code only]
-state/.style = {
- draw, circle, minimum size = ...,
- rdf engine = {
- subject = ???,
- predicate = rdf:type,
- object = automata:state
- }
-}
-\end{codeexample}
- %
- The problem is, of course, what should be passed to the |subject|. We
- cannot even write something like |(\tikz@fig@name)| since no name may
- have been set for the state.
-\end{enumerate}
-
-Each of the above problems is solved by a special keys:
-
-\begin{key}{/tikz/rdf engine/get new resource curie=\meta{macro}}
- The \meta{macro} will be set to a new unique curie that can be used
- anywhere where a curie is allowed. Here is an example how we can add a
- state and a transition container to an automaton, both of which have no
- corresponding scope in \tikzname.
- %
-\begin{codeexample}[code only]
-\tikz [ name = my automaton,
- rdf engine = {
- get new resource curie = \statecurie,
- get new resource curie = \transitiocurie,
- statement = {
- subject = (my automaton),
- predicate = automata:hasStateSet,
- object = \statecurie },
- statement = {
- subject = \statecurie,
- hat type = automata:stateSet },
- statement = {
- subject = (my automaton),
- predicate = automata:hasTransitionSet,
- object = \transitiocurie },
- statement = {
- subject = \transitiocurie,
- hat type = automata:transitionSet } } ] { ... }
-\end{codeexample}
- %
- The \meta{macro} will be valid for the whole scope.
-\end{key}
-
-\begin{key}{/tikz/rdf engine/get scope curie=\meta{macro}}
- The \meta{macro} will be set to a unique curie that represents the scope or
- node. If the scope is named (using the |name| key or the special
- parenthesis syntax for nodes) and this name is later referenced in another
- statement, the same curie will be generated. Note how in the following code
- no name is given for the automaton, which means that the whole \textsc{rdf}
- code could be moved inside a style like |finite automaton| or something
- similar.
- %
-\begin{codeexample}[code only]
-\tikz [ rdf engine = {
- get new resource curie = \statecurie,
- get new resource curie = \transitiocurie,
- get scope curie = \automatoncurie,
- statement = {
- subject = \automatoncurie,
- predicate = automata:hasStateSet,
- object = \statecurie },
- statement = {
- subject = \statecurie,
- hat type = automata:stateSet },
- statement = {
- subject = \automatoncurie,
- predicate = automata:hasTransitionSet,
- object = \transitiocurie },
- statement = {
- subject = \transitiocurie,
- hat type = automata:transitionSet } } ] { ... }
-\end{codeexample}
- %
- The \meta{macro} will be valid for the whole scope.
-\end{key}
-
-The following key builds on the above keys:
-%
-\begin{key}{/tikz/rdf engine/scope is new context}
- This key executes |get scope curie=\tikzrdfcontext|, thereby setting the
- macro |\tikzrdfcontext| to the current scope. The idea is the key is used
- with ``major resources'' and that keys can use this macro as the |subject|
- of statements if no subject is given explicitly. For instance, a |title|
- key might be defined as follows:
- %
-\begin{codeexample}[code only]
-title/.style = {
- rdf engine = { statement = {
- subject = \tikzrdfcontext,
- predicate = dc:Title,
- object = "#1"
-} } }
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Creating Containers}
-
-A \emph{container} is a resource that represents a set or a sequence of
-elements. In \textsc{rdf} this is modeled by having a statement say that the
-type of the resource is something special like |rdf:Seq| and then for each
-member resource of the container add a statement saying that the container has
-as its $i$th member the member resource. Here is an example of a container
-with two elements:
-%
-\begin{codeexample}[code only]
-\tikz {
- \node (safe) { Safe }
- child { node (coins) {Coins} }
- child { node (gold) {Gold} };
-
- \scoped [rdf engine = {
- statement = {
- subject = (safe),
- has type = rdf:Seq
- },
- statement = {
- subject = (safe),
- predicate = rdf:_1,
- object = (coins)
- },
- statement = {
- subject = (safe),
- predicate = rdf:_2,
- object = (gold)
- } }];
-}
-\end{codeexample}
-
-However, the above code is error-prone and does not integrate well with styles
-and libraries. For this reason, \tikzname\ offers some styles that may help in
-creating containers:
-
-\begin{key}{/tikz/rdf engine/statements/is a container}
- Add this key to a statement in order to tell \tikzname\ that it should
- setup a special counter for the subject of the statement that keeps track
- of the container's children.
-\end{key}
-
-\begin{key}{/tikz/rdf engine/statements/has as member}
- This key may only be added to statements whose subject was previously used
- as a subject in a statement containing the |is a container| key. In this
- case, the internal counter will be increased and the predicate will be set
- to |rdf:_|\meta{count}. This means that we can write the above code as:
- %
-\begin{codeexample}[code only]
-\tikz { ...
-
- \scoped [rdf engine = {
- statement = {
- subject = (safe),
- has type = rdf:Seq,
- is a container,
- },
- statement = {
- subject = (safe),
- has as member,
- object = (coins)
- },
- statement = {
- subject = (safe),
- has as member,
- object = (gold)
- } }];
-}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/rdf engine/statements/is a sequence}
- This is a shorthand for |predicate = rdf:Seq, is a container|. In the above
- example we could say:
- %
-\begin{codeexample}[code only]
-\tikz { ...
-
- \scoped [rdf engine = {
- statement = {
- subject = (safe),
- is a sequence
- },
- ... } ]; }
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/rdf engine/statements/is a bag}
- This is a shorthand for |predicate = rdf:Bag, is a container|.
-\end{key}
-
-\begin{key}{/tikz/rdf engine/statements/is an alternative}
- This is a shorthand for |predicate = rdf:Alt, is a container|.
-\end{key}
-
-
-\subsection{Creating Semantic Information Inside Styles and Libraries}
-
-\begingroup
-
-The \textsc{rdf} library was designed in such a way that normal document
-authors do not need to use the keys of the library explicitly, except possibly
-for saying |rdf engine on| somewhere at the beginning. Instead, library authors
-should include the necessary commands to generate \textsc{rdf} information that
-is then automatically included in the output. Furthermore, if the author does
-not ``switch on'' the generation of \textsc{rdf} information, all uses of
-|rdf engine| will simply be ignored silently and neither the speed of
-compilation nor the size of the generated files is impacted.
-
-
-\subsubsection{An Example Library for Drawing Finite Automata}
-
-In the following, we have a look at how a library might be augmented by
-\textsc{rdf} generation keys. The library we augment is a (fictitious) library
-for drawing finite automata. The library offers the following styles:
-%
-\begin{enumerate}
- \item |dfa| and |nfa| can be added to a scope to indicate that the scope
- contains a deterministic or a nondeterministic finite automaton.
- \item |state| can be added to a node to indicate that the node is a state
- in the automaton.
- \item |initial| and |final| are used to indicate that a state is an initial
- or final state, which should be rendered in a special way.
- \item |transition| can be added to an edge to indicate that there is a
- transition in the automaton from the first state to the second state.
- The style takes a parameter which is the symbol read by the automaton.
-\end{enumerate}
-
-Here are some possible definitions of these keys that do not (yet) generate
-\textsc{rdf} information:
-%
-\begin{codeexample}[code only, setup code]
-\tikzset {
- dfa/.style = { semithick, > = To [sep] },
- nfa/.style = { semithick, > = To [sep] },
- state/.style = { circle, draw, minimum size = 1cm },
- final/.style = { double },
- initial/.style = { draw = red }, % to keep things simple
- transition/.style = { edge label = {$#1$} } }
-\end{codeexample}
-
-The library could be used as follows:
-%
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{graphs,rdf}}]
-\tikz [dfa]
- \graph [math nodes, grow right = 1.5cm] {
- q_0 [state, initial] -> [transition = a]
- q_1 [state] -> [transition = b, loop above]
- q_1 -> [transition = a]
- q_2 [state, final]
- };
-\end{codeexample}
-
-
-\subsubsection{Adding Semantic Information About the Automata as a Whole}
-
-Let us change the different keys so that they add \textsc{rdf} information to
-the output. For this, we first need an ontology that defines notions like
-``state'' or ``deterministic finite automaton''. For the purposes of this
-example, we just assume that such an ontology exists at
-|http://www.tcs.uni-luebeck.de/ontologies/automata/|. The new definition of the
-|dfa| key might start as follows (we will extend these later on):
-%
-\begin{codeexample}[code only]
-dfa/.style = {
- semithick, > = To [sep], % as before,
- rdf engine = {
- %
- % Setup prefix:
- prefix = { automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ },
- %
- % Get the curie of the automaton and store it in a macro for later use:
- get scope curie = \mylibAutomatonCurie,
- %
- % Make a statement that the resource is, indeed, an automaton:
- statement = {
- subject = \mylibAutomatonCurie,
- has type = automata:types/automaton },
- %
- % Make a statement that the automaton is deterministic:
- statement = {
- subject = \mylibAutomatonCurie,
- predicate = automata:properties/deterministic,
- object = "yes" } } }
-\end{codeexample}
-
-The definition of the style |nfa| would be exactly the same as for |dfa|,
-except, of course, that the last statement would have |"no"| as object. Note
-that the original styles |dfa| and |nfa| has identical definitions since,
-indeed, there is no ``visual'' difference between the two. In contrast, the
-\textsc{rdf} information stores this information in the output.
-
-
-\subsubsection{Adding Semantic Information About the States}
-
-We next augment the styles for creating states and marking them as final or
-initial. We could do the following (note that we do not setup the prefix since
-this has been done by the surrounding |dfa| or |nfa| key):
-%
-\begin{codeexample}[code only]
-state/.style = {
- circle, draw, minimum size = 1cm, % as before,
- rdf engine = {
- get scope curie = \mylibStateCurie,
- statement = {
- subject = \mylibStateCurie,
- has type = automata:types/state },
- statement = {
- subject = \mylibStateCurie,
- predicate = rdf:value,
- object = scope content } } }
-\end{codeexample}
-
-The first statement tells us that the circle with its contents is a state (and
-not just ``any'' fancy circle). The second statement tells us that the
-``value'' of this state is the content. One might argue that, instead, only the
-number itself (like ``$q_0$'' or perhaps only ``$0$'') should be the ``value''
-or, perhaps, a different property should actually be used (like
-|automata:stateNumber| or something like that). However, these are questions of
-ontological modeling, not of the use of the \textsc{rdf} engine.
-
-What is definitely missing from the above definition is a link between the
-automaton resource and the state resource. Note that the state's rendering code
-will be inside the scope of the automaton, so, in a sense, the state is
-``inside'' the automaton in the output. However, the nesting of scopes is
-\emph{not} part of the \textsc{rdf} graph; we must make these relationships
-explicit using statements. One way to achieve this would be to add the
-following to the |state| style:
-%
-\begin{codeexample}[code only]
- statement = {
- subject = \mylibAutomatonCurie,
- predicate = automata:hasAsAState,
- object = \mylibStateCurie }
-\end{codeexample}
-
-Note that we can access the macro |\mylibAutomatonCurie| here since this will
-have been setup by the surrounding |dfa| or |nfa| key. While the above is
-possible and legitimate, we will see a better solution using containers in a
-moment (``better'' in the sense that the ontological model is easier to process
-by software).
-
-The two styles |final| and |initial| are easy to augment:
-%
-\begin{codeexample}[code only]
-final/.style = {
- double, % as before,
- rdf engine = {
- get scope curie = \mylibStateCurie,
- statement = {
- subject = \mylibStateCurie,
- has type = automata:properties/final } } }
-\end{codeexample}
-
-Note that when we write |node [state, final] ...| the state now has two types:
-It has type |automata:types/state| and also |automata:properties/final|. This
-is perfectly legitimate. Also note that I added |get scope curie| to the above
-definition, which may seem superfluous since the |state| style already executes
-this key to get a curie for the state resource. However, users should be free
-to write |node [final, state] ...| and, now, the |final| key will be executed
-first.
-
-The style for |initial| is the same as for |final| only with a different type.
-
-
-\subsubsection{Adding Semantic Information About the Transitions}
-
-A transition is, essentially, a labeled edge from a state to another state. It
-may seem tempting to model them as a statement with the first state as its
-subject and the second state as the object and the transition's symbol as the
-label (turned into a curie in some appropriate way). However, closer inspection
-shows that this is not a good way of modeling transitions: In essence, it is
-just coincidence that the \textsc{rdf} graph happens to be a directed graph
-and, at the same time, the thing we describe by it (the automaton) can also be
-viewed as a directed graph. If, for instance, we consider alternating automata
-where a transition can involve more than two states, the simple model breaks
-down.
-
-The ``right'' way of modeling a transition is to treat the transition as a
-resource of its own and then make statements like ``the transition has this
-state as its old state''. This turns out to be relatively easy to achieve:
-%
-\begin{codeexample}[code only]
-transition/.style = {
- edge label = {#1}, % as before,
- rdf engine = {
- get scope curie = \mylibTransitionCurie,
- statement = {
- subject = \mylibTransitionCurie,
- has type = automata:types/transition },
- statement = {
- subject = \mylibTransitionCurie,
- predicate = automata:properties/symbolReadFromTape,
- object = "#1" },
- statement = {
- subject = \mylibTransitionCurie,
- predicate = automata:relations/oldState,
- object = (\tikztostart) },
- statement = {
- subject = \mylibTransitionCurie,
- predicate = automata:relations/newState,
- object = (\tikztotarget) } } }
-\end{codeexample}
-
-
-\subsubsection{Using Containers}
-
-As a last step we wish to organize the states and transitions using containers.
-As explained earlier, we can easily add statements linking our automaton to the
-states and to the transitions, but the \textsc{rdf} standard has standard way
-of specifying that a set of resources form a logical sequence: containers.
-
-In case automata contained \emph{only} states, we could setup the automaton
-itself to be the container and the states to be its elements. However, the
-automaton has states and transitions and in this example I would like to keep
-these in separate containers. Thus, we must create two containers and then make
-statements that the automaton contains these two containers. Since these
-containers do not have any accompanying visual representation, we use the
-|get new resource curie| key to create new resources that are purely for
-descriptive purposes inside the \textsc{rdf} graph:
-%
-\begin{codeexample}[code only]
-dfa/.style = {
- semithick, > = To [sep], % as before,
- rdf engine = {
- prefix = { automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ },
- get scope curie = \mylibAutomatonCurie,
- statement = { ... as before that automaton has type automata:types/automaton ... },
- statement = { ... as before that automaton is deterministic ... },
- get new resource curie = \mylibStateContainerCurie,
- statement = {
- subject = \mylibStateContainerCurie,
- is a sequence },
- statement = {
- subject = \mylibAutomatonCurie,
- predicate = automata:relations/hasAsStateContainer,
- object = \mylibStateContainerCurie },
- get new resource curie = \mylibTransitionContainerCurie,
- statement = {
- subject = \mylibTransitionContainerCurie,
- is a sequence },
- statement = {
- subject = \mylibAutomatonCurie,
- predicate = automata:relations/hasAsTransitionContainer,
- object = \mylibTransitionContainerCurie } } }
-\end{codeexample}
-
-We can now modify the |state| style as follows:
-%
-\begin{codeexample}[code only]
-state/.style = {
- circle, draw, minimum size = 1cm, % as before,
- rdf engine = {
- get scope curie = \mylibStateCurie,
- statement = { ... as before ... },
- statement = { ... as before ... },
- statement = {
- subject = \mylibStateContainerCurie,
- has as member,
- object = \mylibStateCurie } } }
-\end{codeexample}
-
-The modification for the |transition| style is similar:
-%
-\begin{codeexample}[code only]
-transition/.style = {
- edge label = {#1}, % as before,
- rdf engine = {
- get scope curie = \mylibTransitionCurie,
- statement = { ... as before ... },
- statement = { ... as before ... },
- statement = { ... as before ... },
- statement = { ... as before ... },
- statement = {
- subject = \mylibTransitionContainerCurie,
- has as member,
- object = \mylibTransitionCurie } } }
-\end{codeexample}
-
-
-\subsubsection{The Resulting RDF Graph}
-
-Putting it all together, we now get the following library code:
-%
-\begin{codeexample}[setup code, multipage]
-\tikzset {
- dfa/.style = {
- semithick, > = To [sep], % as before,
- rdf engine = {
- prefix = { automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ },
- get scope curie = \mylibAutomatonCurie,
- statement = {
- subject = \mylibAutomatonCurie,
- has type = automata:types/automaton },
- statement = {
- subject = \mylibAutomatonCurie,
- predicate = automata:properties/deterministic,
- object = "yes" },
- get new resource curie = \mylibStateContainerCurie,
- statement = {
- subject = \mylibStateContainerCurie,
- is a sequence },
- statement = {
- subject = \mylibAutomatonCurie,
- predicate = automata:relations/hasAsStateContainer,
- object = \mylibStateContainerCurie },
- get new resource curie = \mylibTransitionContainerCurie,
- statement = {
- subject = \mylibTransitionContainerCurie,
- is a sequence },
- statement = {
- subject = \mylibAutomatonCurie,
- predicate = automata:relations/hasAsTransitionContainer,
- object = \mylibTransitionContainerCurie } } },
- state/.style = {
- circle, draw, minimum size = 1cm, % as before,
- rdf engine = {
- get scope curie = \mylibStateCurie,
- statement = {
- subject = \mylibStateCurie,
- has type = automata:types/state },
- statement = {
- subject = \mylibStateCurie,
- predicate = rdf:value,
- object = scope content },
- statement = {
- subject = \mylibStateContainerCurie,
- has as member,
- object = \mylibStateCurie } } },
- initial/.style = {
- draw = red, % as before,
- rdf engine = {
- get scope curie = \mylibStateCurie,
- statement = {
- subject = \mylibStateCurie,
- has type = automata:properties/initial } } },
- final/.style = {
- double, % as before,
- rdf engine = {
- get scope curie = \mylibStateCurie,
- statement = {
- subject = \mylibStateCurie,
- has type = automata:properties/final } } },
- transition/.style = {
- edge label = {$#1$}, % as before,
- rdf engine = {
- get scope curie = \mylibTransitionCurie,
- statement = {
- subject = \mylibTransitionCurie,
- has type = automata:types/transition },
- statement = {
- subject = \mylibTransitionCurie,
- predicate = automata:properties/symbolReadFromTape,
- object = "#1" },
- statement = {
- subject = \mylibTransitionCurie,
- predicate = automata:relations/oldState,
- object = (\tikztostart) },
- statement = {
- subject = \mylibTransitionCurie,
- predicate = automata:relations/newState,
- object = (\tikztotarget) },
- statement = {
- subject = \mylibTransitionContainerCurie,
- has as member,
- object = \mylibTransitionCurie } } }
-}
-\end{codeexample}
-
-\emph{Using} this code is still ``as easy as before'', indeed, the code for
-creating the automaton is perfectly unchanged:
-%
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{graphs,rdf}}]
-\tikzset { rdf engine on }
-\tikz [dfa]
- \graph [math nodes, grow right = 1.5cm] {
- q_0 [state, initial] -> [transition = a]
- q_1 [state] -> [transition = b, loop above]
- q_1 -> [transition = a]
- q_2 [state, final]
- };
-\end{codeexample}
-
-Let us now have a look at the result. If the above is processed using \TeX\ and
-transformed to \textsc{svg} code, the following results (reformatted and
-slightly simplified):
-%
-\begin{codeexample}[multipage]
-<g id="pgf3" prefix=" automata: http://www.tcs.uni-luebeck.de/ontologies/automata/ ">
- <!-- The automaton -->
- <g about="#pgf3" property="rdf:type" resource="automata:types/automaton" />
- <g about="#pgf3" property="automata:properties/deterministic" content="yes" />
- <g about="#pgf4" property="rdf:type" resource="rdf:Seq" />
- <g about="#pgf3" property="automata:relations/hasAsStateContainer" resource="#pgf4" />
- <g about="#pgf5" property="rdf:type" resource="rdf:Seq" />
- <g about="#pgf3" property="automata:relations/hasAsTransitionContainer" resource="#pgf5" />
- <g id="pgf6" about="#pgf6" property="rdf:value">
- <!-- State $q_0$ -->
- <g about="#pgf6" property="rdf:type" resource="automata:types/state" />
- <g about="#pgf4" property="rdf:_1" resource="#pgf6" />
- <g about="#pgf6" property="rdf:type" resource="automata:properties/initial" />
- <g stroke="#f00"> <!-- Red Line -->
- <path id="pgf6bp" d="M 14.22636 0.0 C 14.22636 7.8571 7.8571 14.22636 0.0 14.22636 ..." />
- ...
- </g>
- </g>
- <g id="pgf7" about="#pgf7" property="rdf:value">
- <!-- State $q_1$ -->
- <g about="#pgf7" property="rdf:type" resource="automata:types/state" />
- <g about="#pgf4" property="rdf:_2" resource="#pgf7" />
- <path id="pgf7bp" d="M 56.90549 0.0 C 56.90549 7.8571 50.53622 14.22636 42.67912 14.22636 ..." />
- ...
- </g>
- <g id="pgf8" >
- <!-- Transition from $q_0$ to $q_1$ -->
- <g about="#pgf8" property="rdf:type" resource="automata:types/transition" />
- <g about="#pgf8" property="automata:properties/symbolReadFromTape" content="a" />
- <g about="#pgf8" property="automata:relations/oldState" resource="#pgf6" />
- <g about="#pgf8" property="automata:relations/newState" resource="#pgf7" />
- <g about="#pgf5" property="rdf:_1" resource="#pgf8" />
- <path id="pgf8p" d="M 14.52637 0.0 L 26.49275 0.0"/>
- ...
- </g>
- <g id="pgf11" >
- <!-- Transition loop at $q_1$ -->
- <g about="#pgf11" property="rdf:type" resource="automata:types/transition" />
- <g about="#pgf11" property="automata:properties/symbolReadFromTape" content="b" />
- <g about="#pgf11" property="automata:relations/oldState" resource="#pgf7" />
- <g about="#pgf11" property="automata:relations/newState" resource="#pgf7" />
- <g about="#pgf5" property="rdf:_2" resource="#pgf11" />
- <path id="pgf11p" d="M 38.91211 14.05888 C 33.07051 35.8591 51.00113 36.72765 47.05392 16.66444"/>
- ...
- </g>
- <g id="pgf12" about="#pgf12" property="rdf:value">
- <!-- State $q_2$ -->
- <g about="#pgf12" property="rdf:type" resource="automata:types/state" />
- <g about="#pgf4" property="rdf:_3" resource="#pgf12" />
- <g about="#pgf12" property="rdf:type" resource="automata:properties/final" />
- <g stroke-width="1.80002"> <!-- Double Line -->
- <path id="pgf12bp" d="M 99.58461 0.0 C 99.58461 7.8571 93.21535 14.22636 85.35825 14.22636 ..." />
- ...
- </g>
- </g>
- <g id="pgf13" >
- <!-- Transition from $q_1$ to $q_2$ -->
- <g about="#pgf13" property="rdf:type" resource="automata:types/transition" />
- <g about="#pgf13" property="automata:properties/symbolReadFromTape" content="a" />
- <g about="#pgf13" property="automata:relations/oldState" resource="#pgf7" />
- <g about="#pgf13" property="automata:relations/newState" resource="#pgf12" />
- <g about="#pgf5" property="rdf:_3" resource="#pgf13" />
- <path id="pgf13p" d="M 57.20549 0.0 L 69.17188 0.0"/>
- ...
- </g>
-</g>
-\end{codeexample}
-
-When this code is processed by some \textsc{rdf}a tool, the following graph
-will result where the blue nodes represent resources:
-
-\ifluatex
-\else
- This example can only be typeset using Lua\TeX.
- \endgroup\expandafter\endinput
-\fi
-
-{
- \newbox\myboxa
- \setbox\myboxa=\hbox{\tiny {\tikz\node[circle, draw=red, fill=white] {$q_0$};}}
- \newbox\myboxb
- \setbox\myboxb=\hbox{\tiny {\tikz\node[circle, draw,fill=white] {$q_1$};}}
- \newbox\myboxc
- \setbox\myboxc=\hbox{\tiny {\tikz\node[circle, draw,fill=white, double] {$q_2$};}}
- \catcode`\_=11
- \begin{tikzpicture}[font=\tiny\ttfamily, > = {Stealth [round, sep]}]
- \graph [layered layout, sibling sep=1mm, sibling distance=0pt,
- resource/.style = {align=left,font=\footnotesize\ttfamily, draw = blue, thick, fill=blue!20, rounded corners},
- predicate/.style = {align=right,font=\scriptsize\ttfamily,fill=black!5,rotate=90,anchor=mid east, rounded corners},
- tail anchor=south, head anchor=north] {
- pgf3/\#pgf3[resource] -- /"rdf:type"[predicate] -> automaton[as={automata:\\types/\\automaton},resource];
- pgf3/\#pgf3[resource] -- /"automata:\\properties/deterministic"[predicate] -> /{"yes"}[resource];
- pgf4/\#pgf4[resource] -- /"rdf:type"[predicate] -> rdf:Seq[resource];
- pgf3/\#pgf3[resource] -- /"automata:\\relations/\\hasAsStateContainer"[predicate] -> pgf4[resource];
- pgf5/\#pgf5[resource] -- /"rdf:type"[predicate] -> rdf:Seq[resource];
- pgf3/\#pgf3[resource] -- /"atuomata:\\relations/\\hasAsTransitionContainer"[predicate] -> pgf5[resource];
- pgf6/\#pgf6[resource] -- /"rdf:value"[predicate] -> /[as={\box\myboxa},resource];
- pgf6/\#pgf6[resource] -- /"rdf:type"[predicate] -> state/"automata:\\types/state"[resource];
- pgf4/\#pgf4[resource] -- /"rdf:_1"[predicate] -> pgf6[resource];
- pgf6/\#pgf6[resource] -- /"rdf:type"[predicate] -> initial/"automata:\\properties/\\initial"[resource];
- pgf7/\#pgf7[resource] -- /"rdf:value"[predicate] -> /[as={\box\myboxb},resource];
- pgf7/\#pgf7[resource] -- /"rdf:type"[predicate] -> state/"automata:\\types/state"[resource];
- pgf4/\#pgf4[resource] -- /"rdf:_2"[predicate] -> pgf7[resource];
- pgf12/\#pgf12[resource] -- /"rdf:value"[predicate] -> /[as={\box\myboxc},resource];
- pgf12/\#pgf12[resource] -- /"rdf:type"[predicate] -> state/"automata:\\types/state"[resource];
- pgf4/\#pgf4[resource] -- /"rdf:_3"[predicate] -> pgf12[resource];
- pgf12/\#pgf12[resource] -- /"rdf:type"[predicate] -> final/"automata:\\properties/\\final"[resource];
- pgf8/\#pgf8[resource] -- /"rdf:type"[predicate] -> transition/"automata:\\types/\\transition"[resource];
- pgf8/\#pgf8[resource] -- /"automata:\\properties/\\symbolReadFromTape"[predicate] -> /{"a"}[resource];
- pgf8/\#pgf8[resource] -- /"automata:\\relations/oldState"[predicate] -> pgf6[resource];
- pgf8/\#pgf8[resource] -- /"automata:\\relations/newState"[predicate] -> pgf7[resource];
- pgf5/\#pgf5[resource] -- /"rdf:_1"[predicate] -> pgf8[resource];
- pgf11/\#pgf11[resource] -- /"rdf:type"[predicate] -> transition/"automata:\\types/\\transition"[resource];
- pgf11/\#pgf11[resource] -- /"automata:\\properties/\\symbolReadFromTape"[predicate] -> /{"b"}[resource];
- pgf11/\#pgf11[resource] -- /"automata:\\relations/oldState"[predicate] -> pgf7[resource];
- pgf11/\#pgf11[resource] -- /"automata:\\relations/newState"[predicate] -> pgf7[resource];
- pgf5/\#pgf5[resource] -- /"rdf:_2"[predicate] -> pgf11[resource];
- pgf13/\#pgf13[resource] -- /"rdf:type"[predicate] -> transition/"automata:\\types/\\transition"[resource];
- pgf13/\#pgf13[resource] -- /"automata:\\properties/\\symbolReadFromTape"[predicate] -> /{"a"}[resource];
- pgf13/\#pgf13[resource] -- /"automata:\\relations/oldState"[predicate] -> pgf7[resource];
- pgf13/\#pgf13[resource] -- /"automata:\\relations/newState"[predicate] -> pgf12[resource];
- pgf5/\#pgf5[resource] -- /"rdf:_3"[predicate] -> pgf13[resource];
- };
-\end{tikzpicture}
-}
-
-\endgroup
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-shadings.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-shadings.tex
deleted file mode 100644
index e2afddbb34..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-shadings.tex
+++ /dev/null
@@ -1,220 +0,0 @@
-% 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{Shadings Library}
-\label{section-library-shadings}
-
-\begin{pgflibrary}{shadings}
- The package defines a number of shadings in addition to the ball and axis
- shadings that are available by default.
-\end{pgflibrary}
-
-In the following, the shadings defined in the library are listed in
-alphabetical order. The colors of some of these shadings can be configured
-using special options (like |left color|). These options implicitly select the
-shading.
-
-The three shadings |axis|, |ball|, and |radial| are always defined, even when
-this library is not used.
-
-\begin{shading}{axis}
- In this always-defined shading the colors change gradually between three
- horizontal lines. The top line is at the top (uppermost) point of the path,
- the middle is in the middle, the bottom line is at the bottom of the path.
- %
- \begin{key}{/tikz/top color=\meta{color}}
- This option sets the color to be used at the top in an |axis| shading.
- When this option is given, several things happen:
- %
- \begin{enumerate}
- \item The |shade| option is selected.
- \item The |shading=axis| option is selected.
- \item The middle color of the axis shading is set to the average of
- the given top color \meta{color} and of whatever color is
- currently selected for the bottom.
- \item The rotation angle of the shading is set to 0.
- \end{enumerate}
- %
-\begin{codeexample}[preamble={\usepgflibrary{shadings}}]
-\tikz \draw[top color=red] (0,0) rectangle (2,1);
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/bottom color=\meta{color}}
- This option works like |top color|, only for the bottom color.
- \end{key}
-
- \begin{key}{/tikz/middle color=\meta{color}}
- This option specifies the color for the middle of an axis shading. It
- also sets the |shade| and |shading=axis| options, but it does not
- change the rotation angle.
-
- \emph{Note:} Since both |top color| and |bottom color| change the
- middle color, this option should be given \emph{last} if all of these
- options need to be given:
- %
-\begin{codeexample}[preamble={\usepgflibrary{shadings}}]
-\tikz \draw[top color=white,bottom color=black,middle color=red]
- (0,0) rectangle (2,1);
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/left color=\meta{color}}
- This option does exactly the same as |top color|, except that the
- shading angle is set to $90^\circ$.
- \end{key}
-
- \begin{key}{/tikz/right color=\meta{color}}
- Works like |left color|.
- \end{key}
-\end{shading}
-
-\begin{shading}{ball}
- This always-defined shading fills the path with a shading that ``looks like
- a ball''. The default ``color'' of the ball is blue (for no particular
- reason).
-
- \begin{key}{/tikz/ball color=\meta{color}}
- This option sets the color used for the ball shading. It sets the
- |shade| and |shading=ball| options. Note that the ball will never
- ``completely'' have the color \meta{color}. At its ``highlight'' spot a
- certain amount of white is mixed in, at the border a certain amount of
- black. Because of this, it also makes sense to say |ball color=white|
- or |ball color=black|
- %
-\begin{codeexample}[preamble={\usepgflibrary{shadings}}]
-\begin{tikzpicture}
- \shade[ball color=white] (0,0) circle (2ex);
- \shade[ball color=red] (1,0) circle (2ex);
- \shade[ball color=black] (2,0) circle (2ex);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{shading}
-
-\begin{shading}{bilinear interpolation}
- This shading fills a rectangle with colors that a bilinearly interpolated
- between the colors in the four corners of the rectangle. These four colors
- are called |lower left|, |lower right|, |upper left|, and |upper right|. By
- changing these color, you can change the way the shading looks. The library
- also defines four options, called the same way, that can be used to set
- these colors and select the shading implicitly.
- %
-\begin{codeexample}[preamble={\usepgflibrary{shadings}}]
-\tikz
- \shade[upper left=red,upper right=green,
- lower left=blue,lower right=yellow]
- (0,0) rectangle (3,2);
-\end{codeexample}
-
- \begin{key}{/tikz/lower left=\meta{color} (initially white)}
- Sets the color to be used in a |bilinear interpolation| shading for the
- lower left corner. Also, this options selects this shading and sets the
- |shade| option.
- \end{key}
-
- \begin{key}{/tikz/upper left=\meta{color} (initially white)}
- Works like |lower left|.
- \end{key}
-
- \begin{key}{/tikz/upper right=\meta{color} (initially white)}
- Works like |lower left|.
- \end{key}
-
- \begin{key}{/tikz/lower right=\meta{color} (initially white)}
- Works like |lower left|.
- \end{key}
-\end{shading}
-
-\begin{shading}{color wheel}
-\label{shading-color-wheel}%
- This shading fills the path with a color wheel.
- %
-\begin{codeexample}[preamble={\usepgflibrary{shadings}}]
-\tikz \shade[shading=color wheel] (0,0) circle (1.5);
-\end{codeexample}
- %
- To produce a color ring, cut out a circle from the color wheel:
- %
-\begin{codeexample}[preamble={\usepgflibrary{shadings}}]
-\tikz \shade[shading=color wheel] [even odd rule]
- (0,0) circle (1.5)
- (0,0) circle (1);
-\end{codeexample}
- %
-\end{shading}
-
-\begin{shading}{color wheel black center}
- This shading looks like a color wheel, but the brightness drops to zero in
- the center.
- %
-\begin{codeexample}[preamble={\usepgflibrary{shadings}}]
-\tikz \shade[shading=color wheel black center] (0,0) circle (1.5);
-\end{codeexample}
- %
-\end{shading}
-
-\begin{shading}{color wheel white center}
- This shading looks like a color wheel, but the saturation drops to zero in
- the center.
- %
-\begin{codeexample}[preamble={\usepgflibrary{shadings}}]
-\tikz \shade[shading=color wheel white center] (0,0) circle (1.5);
-\end{codeexample}
- %
-\end{shading}
-
-\makeatletter
-\begin{shading}{Mandelbrot set}
- This shading is just for fun. It fills the path with a zoomable Mandelbrot
- set. Note that this is \emph{not} a bitmap graphic. Rather, the Mandelbrot
- set is \emph{computed by the \textsc{pdf} renderer} and can be zoomed
- arbitrarily (give it a try, if you have a fast computer).
- %
-\begin{codeexample}[preamble={\usepgflibrary{shadings}}]
-\tikz \shade[shading=Mandelbrot set] (0,0) rectangle (2,2);
-\end{codeexample}
- %
-\end{shading}
-\makeatother
-
-\begin{shading}{radial}
- This always-defined shading fills the path with a gradual sweep from a
- certain color in the middle to another color at the border. If the path is
- a circle, the outer color will be reached exactly at the border. If the
- shading is not a circle, the outer color will continue a bit towards the
- corners. The default inner color is gray, the default outer color is white.
- %
- \begin{key}{/tikz/inner color=\meta{color}}
- This option sets the color used at the center of a |radial| shading.
- When this option is used, the |shade| and |shading=radial| options are
- set.
- %
-\begin{codeexample}[preamble={\usepgflibrary{shadings}}]
-\tikz \draw[inner color=red] (0,0) rectangle (2,1);
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/outer color=\meta{color}}
- This option sets the color used at the border and outside of a |radial|
- shading.
- %
-\begin{codeexample}[preamble={\usepgflibrary{shadings}}]
-\tikz \draw[outer color=red,inner color=white]
- (0,0) rectangle (2,1);
-\end{codeexample}
- \end{key}
-\end{shading}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-shadows.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-shadows.tex
deleted file mode 100644
index 9d1ae581d5..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-shadows.tex
+++ /dev/null
@@ -1,291 +0,0 @@
-% Copyright 2019 by Till Tantau and Mark Wibrow
-%
-% 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{Shadows Library}
-\label{section-libs-shadows}
-
-\begin{tikzlibrary}{shadows}
- This library defines styles that help adding a (partly) transparent shadow
- to a path or node.
-\end{tikzlibrary}
-
-
-\subsection{Overview}
-
-A \emph{shadow} is usually a black or gray area that is drawn behind a path or
-a node, thereby adding visual depth to a picture. The |shadows| library defines
-options that make it easy to add shadows to paths. Internally, these options
-are based on using the |preaction| option to use a path twice: Once for drawing
-the shadow (slightly shifted) and once for actually using the path.
-
-Note that you can only add shadows to \emph{paths}, not to whole scopes.
-
-In addition to the general |shadow| option, there exist special options like
-|circular shadow|. These can only (sensibly) be used with a special kind of
-path (for |circular shadow|, a circle) and, thus, they are not as general. The
-advantage is, however, that they are more visually pleasing since these shadows
-blend smoothly with the background. Note that these special shadows use
-fadings, which few printers will support.
-
-
-\subsection{The General Shadow Option}
-
-The shadows are internally created by using a single option called
-|general shadow|. The different options like |drop shadow| or |copy shadow|
-only differ in the commands that they preset.
-
-You will not need to use this option directly under normal circumstances.
-
-\begin{key}{/tikz/general shadow=\meta{shadow options} (default \normalfont empty)}
- This option should be given to a |\path| or a |node|. It has the following
- effect: Before the path is used normally, it is used once with the
- \meta{shadow options} in force. Furthermore, when the path is ``preused''
- in this way, it is shifted and scaled a little bit.
-
- In detail, the following happens: A |preaction| is used to paint the path
- in a special manner before it is actually painted. This ``special'' manner
- is as follows: The options in \meta{shadow options} are used for painting
- this path. Typically, the \meta{shadow options} will contain options like
- |fill=black| to create, say, a black shadow. Furthermore, after the
- \meta{shadow options} have been set up, the following extra canvas
- transformations are applied to the path: It is scaled by |shadow scale|
- (with the origin of scaling at the path's center) and it is shifted by
- |shadow xshift| and |shadow yshift|.
-
- Note that since scaling and shifting is done using canvas transformations,
- shadows are not taken into account when the picture's bounding box is
- computed.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
-\tikz [even odd rule]
- \draw [general shadow={fill=red}] (0,0) circle (.5) (0.5,0) circle (.5);
-\end{codeexample}
-
- \begin{key}{/tikz/shadow scale=\meta{factor} (initially 1)}
- Shadows are scaled by \meta{factor}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
-\tikz [even odd rule]
- \draw [general shadow={fill=red,shadow scale=1.25}]
- (0,0) circle (.5) (0.5,0) circle (.5);
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/shadow xshift=\meta{dimension} (initially 0pt)}
- Shadows are shifted horizontally by \meta{dimension}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
-\tikz [even odd rule]
- \draw [general shadow={fill=red,shadow xshift=-5pt}]
- (0,0) circle (.5) (0.5,0) circle (.5);
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/shadow yshift=\meta{dimension} (initially 0pt)}
- Shadows are shifted vertically by \meta{dimension}.
- \end{key}
-\end{key}
-
-
-\subsection{Shadows for Arbitrary Paths and Shapes}
-
-\subsubsection{Drop Shadows}
-
-\begin{key}{/tikz/drop shadow=\meta{shadow options} (default \normalfont empty)}
- This option adds a drop shadow to a |\path| or a |node|. It uses the
- |general shadow| and passes the \meta{shadow options} to it, plus, before
- them, the following extra options:
- %
-\begin{codeexample}[code only]
- shadow scale=1, shadow xshift=.5ex, shadow yshift=-.5ex,
- opacity=.5, fill=black!50, every shadow
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
-\tikz [even odd rule]
- \filldraw [drop shadow,fill=white] (0,0) circle (.5) (0.5,0) circle (.5);
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{shadows,shapes.symbols}}]
-\begin{tikzpicture}
- \foreach \i in {1,...,4}
- \node[starburst,drop shadow,fill=white,draw] at (0,\i) {Burst \i};
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- \filldraw [drop shadow={opacity=1},fill=white]
- (1,2) circle (.5) (1.5,2) circle (.5);
-
- \filldraw [drop shadow={opacity=0.25},fill=white]
- (1,.5) circle (.5) (1.5,.5) circle (.5);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{stylekey}{/tikz/every shadow (initially \normalfont empty)}
- This style is executed in addition to any \meta{shadow options} for each
- shadow. Use this style to reconfigure the way shadows are drawn.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
-\begin{tikzpicture}[every shadow/.style={opacity=.8,fill=blue!50!black}]
- \filldraw [drop shadow,fill=white] (0,0) circle (.5) (0.5,0) circle (.5);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsubsection{Copy Shadows}
-
-A \emph{copy shadow} is not really a shadow. Rather, it looks like another copy
-of the path drawn behind the path and a little bit offset. This creates the
-visual impression of having multiple copies of the path/object present.
-
-\begin{key}{/tikz/copy shadow=\meta{shadow options} (default \normalfont empty)}
- This shadow installs the following default options:
- %
-\begin{codeexample}[code only]
- shadow scale=1, shadow xshift=.5ex, shadow yshift=-.5ex, every shadow
-\end{codeexample}
- %
- Furthermore, the options |fill=|\meta{fill color} and |draw=|\meta{draw
- color} are also set, where the \meta{fill color} and \meta{draw color} are
- the fill and draw colors used for the main path.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shadows,shapes.symbols}}]
-\begin{tikzpicture}
- \node [copy shadow,fill=blue!20,draw=blue,thick] {Hello World!};
-
- \node at (0,-1) [copy shadow={shadow xshift=1ex,shadow yshift=1ex},
- fill=blue!20,draw=blue,thick]
- {Hello World!};
-
- \node at (0,-2) [copy shadow={opacity=.5},tape,
- fill=blue!20,draw=blue,thick]
- {Hello World!};
-
- % We have to repeat the left color since shadings are not
- % automatically applied to shadows
- \node at (0,-3) [copy shadow={left color=blue!50},
- left color=blue!50,draw=blue,thick]
- {Hello World!};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/double copy shadow=\meta{shadow options} (default \normalfont empty)}
- This shadow works like a |copy shadow|, only the shadow is added twice, the
- second time with the double |xshift| and |yshift|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shadows,shapes.symbols}}]
-\begin{tikzpicture}
- \node [double copy shadow,fill=blue!20,draw=blue,thick] {Hello World!};
-
- \node at (0,-1) [double copy shadow={shadow xshift=1ex,shadow yshift=1ex},
- fill=blue!20,draw=blue,thick]
- {Hello World!};
-
- \node at (0,-2) [double copy shadow={opacity=.5},tape,
- fill=blue!20,draw=blue,thick]
- {Hello World!};
-
- \node at (0,-3) [double copy shadow={left color=blue!50},
- left color=blue!50,draw=blue,thick]
- {Hello World!};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Shadows for Special Paths and Nodes}
-
-The shadows in this section should normally be added only to paths that have a
-special shape. They will look strange with other shapes.
-
-\begin{key}{/tikz/circular drop shadow=\meta{shadow options}}
- This shadow works like a drop shadow, only it adds a circular fading to the
- shadow. This means that the shadow will fade out at the border. The
- following options are preset for this shadow:
- %
-\begin{codeexample}[code only]
- shadow scale=1.1, shadow xshift=.3ex, shadow yshift=-.3ex,
- fill=black, path fading={circle with fuzzy edge 15 percent},
- every shadow,
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
-\begin{tikzpicture}
- \foreach \i in {1,...,8}
- \node[circle,circular drop shadow,draw=blue,fill=blue!20,thick]
- at (\i*45:1) {Circle \i};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/circular glow=\meta{shadow options}}
- This shadow works much like the |circular shadow|, only it is not shifted.
- This creates a visual effect of a ``glow'' behind the circle. The following
- options are preset for this shadow:
- %
-\begin{codeexample}[code only]
- shadow scale=1.25, shadow xshift=0pt, shadow yshift=0pt,
- fill=black, path fading={circle with fuzzy edge 15 percent},
- every shadow,
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
-\begin{tikzpicture}
- \foreach \i in {1,...,8}
- \node[circle,circular glow,fill=red!20,draw=red,thick]
- at (\i*45:1) {Circle \i};
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
-\begin{tikzpicture}
- \foreach \i in {1,...,8}
- \node[circle,circular glow={fill=white},fill=red!20,draw=red,thick]
- at (\i*45:1) {Circle \i};
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
-\begin{tikzpicture}
- \foreach \i in {1,...,8}
- \node[circle,circular glow={fill=green},fill=black,text=green!50!black]
- at (\i*45:1) {Circle \i};
-\end{tikzpicture}
-\end{codeexample}
- %
- An especially interesting effect can be achieved by only using the glow and
- not filling the path:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shadows}}]
-\begin{tikzpicture}
- \foreach \i in {1,...,8}
- \node[circle,circular glow={fill=red!\i0}]
- at (\i*45:1) {Circle \i};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-shapes.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-shapes.tex
deleted file mode 100644
index a248294ad2..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-shapes.tex
+++ /dev/null
@@ -1,2295 +0,0 @@
-% Copyright 2019 by Till Tantau and Mark Wibrow
-%
-% 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{Shape Library}
-\label{section-libs-shapes}
-
-\subsection{Overview}
-
-In addition to the standard shapes |rectangle|, |circle| and |coordinate|,
-there exist a number of additional shapes defined in different shape libraries.
-Most of these shapes have been contributed by Mark Wibrow. In the present
-section, these shapes are described. Note that the library |shapes| is provided
-for compatibility only. Please include sublibraries like |shapes.geometric| or
-|shapes.misc| directly.
-
-The appearance of shapes is influenced by numerous parameters like
-|minimum height| or |inner xsep|. These general parameters are documented in
-Section~\ref{section-shape-common-options}
-
-In all of the examples presented in this section, the following |shape example|
-style is used:
-%
-\begin{codeexample}[code only,setup code]
-\tikzset{
- shape example/.style= {color = black!30,
- draw,
- fill = yellow!30,
- line width = .5cm,
- inner xsep = 2.5cm,
- inner ysep = 0.5cm}
-}
-\end{codeexample}
-
-
-\subsection{Predefined Shapes}
-\label{section-predefined-shapes}
-
-The three shapes |rectangle|, |circle|, and |coordinate| are always defined and
-no library needs to be loaded for them. While the |coordinate| shape defines
-only the |center| anchor, the other two shapes define a standard set of
-anchors.
-
-\begin{shape}{circle}
- This shape draws a tightly fitting circle around the text. The following
- figure shows the anchors this shape defines; the anchors |10| and |130| are
- example of border anchors.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=circle,shape example] {Circle\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {north west/above left, north/above, north east/above right,
- west/left, center/above, east/right,
- mid west/right, mid/above, mid east/left,
- base west/left, base/below, base east/right,
- south west/below left, south/below, south east/below right,
- text/left, 10/right, 130/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{rectangle}
- This shape, which is the standard, is a rectangle around the text. The
- inner and outer separations (see Section~\ref{section-shape-seps})
- influence the white space around the text. The following figure shows the
- anchors this shape defines; the anchors |10| and |130| are example of
- border anchors.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=rectangle,shape example] {Rectangle\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {north west/above left, north/above, north east/above right,
- west/left, center/above, east/right,
- mid west/right, mid/above, mid east/left,
- base west/left, base/below, base east/right,
- south west/below left, south/below, south east/below right,
- text/left, 10/right, 130/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-
-\subsection{Geometric Shapes}
-
-\begin{pgflibrary}{shapes.geometric}
- This library defines different shapes that correspond to basic geometric
- objects like ellipses or polygons.
-\end{pgflibrary}
-
-\begin{shape}{diamond}
- This shape is a diamond tightly fitting the text box. The ratio between
- width and height is 1 by default, but can be changed by setting the shape
- aspect ratio using the following \pgfname{} key (to use this key in
- \tikzname{} simply remove the \declare{|/pgf/|} path).
-
- \begin{key}{/pgf/aspect=\meta{value} (initially 1.0)}
- The aspect is a recommendation for the quotient of the width and the
- height of a shape. This key calls the macro |\pgfsetshapeaspect|.
- \end{key}
-
- The following figure shows the anchors this shape defines; the anchors |10|
- and |130| are example of border anchors.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=diamond,shape example] {Diamond\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {north west/above left, north/above, north east/above right,
- west/left, center/above, east/right,
- mid/above,
- base/below,
- south west/below left, south/below, south east/below right,
- text/left, 10/right, 130/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{ellipse}
- This shape is an ellipse tightly fitting the text box, if no inner
- separation is given. The following figure shows the anchors this shape
- defines; the anchors |10| and |130| are example of border anchors.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=ellipse,shape example] {Ellipse\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {north west/above left, north/above, north east/above right,
- west/left, center/above, east/right,
- mid west/right, mid/above, mid east/left,
- base west/left, base/below, base east/right,
- south west/below left, south/below, south east/below right,
- text/left, 10/right, 130/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{trapezium}
- This shape is a trapezium, that is, a quadrilateral with a single pair of
- parallel lines (this can sometimes be known as a trapezoid). The trapezium
- shape supports the rotation of the shape border, as described in
- Section~\ref{section-rotating-shape-borders}.
-
- The lower internal angles at the lower corners of the trapezium can be
- specified independently, and the resulting extensions are in addition to
- the natural dimensions of the node contents (which includes any
- |inner sep|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[every node/.style={trapezium, draw}]
- \node at (0,2) {A};
- \node[trapezium left angle=75, trapezium right angle=45]
- at (0,1) {B};
- \node[trapezium left angle=120, trapezium right angle=60]
- at (0,0) {C};
-\end{tikzpicture}
-\end{codeexample}
-
- The \pgfname{} keys to set the lower internal angles of the trapezium are
- shown below. To use these keys in \tikzname, simply remove the
- \declare{|/pgf/|} path.
-
- \begin{key}{/pgf/trapezium left angle=\meta{angle} (initially 60)}
- Sets the lower internal angle of the left side.
- \end{key}
-
- \begin{key}{/pgf/trapezium right angle=\meta{angle} (initially 60)}
- Sets the lower internal angle of the right side.
- \end{key}
-
- \begin{stylekey}{/pgf/trapezium angle=\meta{angle}}
- This key stores no value itself, but sets the value of the previous two
- keys to \meta{angle}.
- \end{stylekey}
-
- Regardless of the rotation of the shape border, the width and height of the
- trapezium are as follows:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[>=stealth, every node/.style={text=black},
- shape border uses incircle, shape border rotate=60]
- \node [trapezium, fill=gray!25, minimum width=2cm] (t) {};
- \draw [red, <->] (t.bottom left corner) -- (t.bottom right corner)
- node [midway, below right] {width};
- \draw [red, <->] (t.top side) -- (t.bottom side)
- node [at start, above] {height};
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{key}{/pgf/trapezium stretches=\meta{boolean} (default true)}
- This key controls whether \pgfname{} allows the width and the height of
- the trapezium to be enlarged independently, when considering any
- minimum size specification. This is initially |false|, ensuring that
- the shape ``looks the same but bigger'' when enlarged.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\tikzset{my node/.style={trapezium, fill=#1!20, draw=#1!75, text=black}}
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \node [my node=red] {A};
- \node [my node=green, minimum height=1.5cm] at (1, 1.25) {B};
- \node [my node=blue, minimum width=1.5cm] at (2, 0) {C};
-\end{tikzpicture}
-\end{codeexample}
-
- By setting \meta{boolean} to |true|, the trapezium can be stretched
- horizontally or vertically.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\tikzset{my node/.style={trapezium, fill=#1!20, draw=#1!75, text=black}}
-\begin{tikzpicture}
-\tikzset{trapezium stretches=true}
- \draw [help lines] grid (3,2);
- \node [my node=red] {A};
- \node [my node=green, minimum height=1.5cm] at (1, 1.25) {B};
- \node [my node=blue, minimum width=1.5cm] at (2, 0) {C};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/trapezium stretches body=\meta{boolean} (default true)}
- This is similar to the |trapezium stretches| key except that when
- \meta{boolean} is |true|, \pgfname{} enlarges only the body of the
- trapezium when applying minimum width.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\tikzset{my node/.style={trapezium, fill=#1!20, draw=#1!75, text=black}}
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \node [my node=red] at (1.5,.25) {A};
- \node [my node=green, minimum width=3cm, trapezium stretches]
- at (1.5,1) {B};
- \node [my node=blue, minimum width=3cm, trapezium stretches body]
- at (1.5,1.75) {C};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- The anchors for the trapezium are shown below. The anchor |160| is an
- example of a border anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=trapezium, shape example, inner sep=1cm]
- {Trapezium\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {bottom left corner/below, top right corner/right,
- top left corner/left, bottom right corner/below,
- bottom side/below, left side/left,
- right side/right, top side/above,
- center/above, text/below, mid/right, base/below,
- mid west/right, base west/below, mid east/left, base east/below,
- west/above, east/above, north/below, south/above,
- north west/above, north east/above,
- south west/below, south east/below, 160/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{semicircle}
- This shape is a semicircle, which tightly fits the node contents. This
- shape supports the rotation of the shape border, as described in
- Section~\ref{section-rotating-shape-borders}. The anchors for the
- |semicircle| shape are shown below. Anchor |30| is an example of a border
- anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=semicircle,shape border rotate=0,shape example, inner sep=1cm]
- {Semicircle\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {apex/above, arc start/below, arc end/below, chord center/below,
- center/above, base/below, mid/right, text/left,
- base west/below, base east/below, mid west/left, mid east/right,
- north/below, south/above, east/above, west/above,
- north west/above left, north east/above right,
- south west/below, south east/below, 30/right}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{regular polygon}
- This shape is a regular polygon, which, by default, is drawn so that a side
- (rather than a corner) is always at the bottom. This shape supports the
- rotation as described in Section~\ref{section-rotating-shape-borders}, but
- the border of the polygon is \emph{always} constructed using the incircle,
- whose radius is calculated to tightly fit the node contents (including any
- |inner sep|).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}
- \foreach \a in {3,...,7}{
- \draw[red, dashed] (\a*2,0) circle(0.5cm);
- \node[regular polygon, regular polygon sides=\a, draw,
- inner sep=0.3535cm] at (\a*2,0) {};
- }
-\end{tikzpicture}
-\end{codeexample}
-
- If the node is enlarged to any specified minimum size, this is interpreted
- as the diameter of the circumcircle, that is, the circle that passes
- through all the corners of the polygon border.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}
- \foreach \a in {3,...,7}{
- \draw[blue, dashed] (\a*2,0) circle(0.5cm);
- \node[regular polygon, regular polygon sides=\a, minimum size=1cm, draw] at (\a*2,0) {};
- }
-\end{tikzpicture}
-\end{codeexample}
-
- There is a \pgfname{} key to set the number of sides for the regular
- polygon. To use this key in \tikzname, simply remove the \declare{|/pgf/|}
- path.
-
- \begin{key}{/pgf/regular polygon sides=\meta{integer} (initially 5)}
- \end{key}
-
- The anchors for a regular polygon shape are shown below. The anchor |75| is
- an example of a border anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=regular polygon, shape example, inner sep=.5cm]
- {Regular Polygon\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {corner 1/above, corner 2/above, corner 3/left, corner 4/right, corner 5/above,
- side 1/above, side 2/left, side 3/below, side 4/right, side 5/above,
- center/above, text/left, mid/right, base/below, 75/above,
- west/above, east/above, north/below, south/above,
- north east/below, south east/above, north west/below, south west/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{star}
- This shape is a star, which by default (minus any transformations) is drawn
- with the first point pointing upwards. This shape supports the rotation as
- described in Section~\ref{section-rotating-shape-borders}, but the border
- of the star is \emph{always} constructed using the incircle.
-
- A star should be thought of as having a set of ``inner points'' and ``outer
- points''. The inner points of the border are based on the radius of the
- circle which tightly fits the node contents, and the outer points are based
- on the circumcircle, the circle that passes through every outer point. Any
- specified minimum size, width or height, is interpreted as the diameter of
- the circumcircle.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (2,2);
- \draw [blue, dashed] (1,1) circle(1cm);
- \draw [red, dashed] (1,1) circle(.5cm);
- \node [star, star point height=.5cm, minimum size=2cm, draw]
- at (1,1) {S};
-\end{tikzpicture}
-\end{codeexample}
-
- The \pgfname{} keys to set the number of star points, and the height of the
- star points, are shown below. To use these keys in \tikzname, simply remove
- the \declare{|/pgf/|} path.
-
- \begin{key}{/pgf/star points=\meta{integer} (initially 5)}
- Sets the number of points for the star.
- \end{key}
-
- \begin{key}{/pgf/star point height=\meta{distance} (initially .5cm)}
- Sets the height of the star points. This is the distance between the
- inner point and outer point radii. If the star is enlarged to some
- specified minimum size, the inner radius is increased to maintain the
- point height.
- \end{key}
-
- \begin{key}{/pgf/star point ratio=\meta{number} (initially 1.5)}
- Sets the ratio between the inner point and outer point radii. If the
- star is enlarged to some specified minimum size, the inner radius is
- increased to maintain the ratio.
- \end{key}
-
- The inner and outer points form the principal anchors for the star, as
- shown below (anchor |75| is an example of a border anchor).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=star, star points=5, star point ratio=1.65, shape example, inner sep=1.5cm]
- {Star\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {inner point 1/above, inner point 2/above, inner point 3/below, inner point 4/right,
- inner point 5/above, outer point 1/above, outer point 2/above, outer point 3/left,
- outer point 4/right, outer point 5/above,
- center/above, text/left, mid/right, base/below, 75/above,
- west/above, east/above, north/below, south/above,
- north east/below, south east/above, north west/below, south west/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{isosceles triangle}
- This shape is an isosceles triangle, which supports the rotation of the
- shape border, as described in Section~\ref{section-rotating-shape-borders}.
- The angle of rotation determines the direction in which the apex of the
- triangle points (provided no other transformations are applied). However,
- regardless of the rotation of the shape border, the width and height are
- always considered as follows:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[>=stealth, every node/.style={text=black},
- shape border uses incircle, shape border rotate=-30]
- \node [isosceles triangle, fill=gray!25, minimum width=1.5cm] (t) {};
- \draw [red, <->] (t.left corner) -- (t.right corner)
- node [midway, above left] {width};
- \draw [red, <->] (t.apex) -- (t.lower side)
- node [midway, above right] {height};
-\end{tikzpicture}
-\end{codeexample}
-
- There are \pgfname{} keys to customize this shape. To use these keys in
- \tikzname, simply remove the \declare{|/pgf/|} path.
-
- \begin{key}{/pgf/isosceles triangle apex angle=\meta{angle} (initially 30)}
- Sets the angle of the apex of the isosceles triangle.
- \end{key}
-
- \begin{key}{/pgf/isosceles triangle stretches=\meta{boolean} (default true)}
- By default \meta{boolean} is |false|. This means, that when applying
- any minimum width or minimum height requirements, increasing the height
- will increase the width (and vice versa), in order to keep the apex
- angle the same.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[paint/.style={draw=#1!75, fill=#1!20}]
- \tikzset{every node/.style={isosceles triangle, draw, inner sep=0pt,
- anchor=left corner, shape border rotate=90}}
- \draw[help lines] grid(4,2);
- \foreach \a/\c in {1.5/blue, 1/green, 0.5/red}{
- \node[paint=\c, minimum height=\a cm] at (0,0) {};
- \node[paint=\c, minimum width=\a cm] at (2,0) {};
- }
-\end{tikzpicture}
-\end{codeexample}
-
- However, by setting \meta{boolean} to |true|, minimum width and height
- can be applied independently.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[paint/.style={draw=#1!75, fill=#1!20}]
- \tikzset{every node/.style={isosceles triangle, draw, inner sep=0pt,
- anchor=south, shape border rotate=90, isosceles triangle stretches}}
- \draw[help lines] grid(4,2);
- \foreach \a/\c in {1.5/blue, 1/green, 0.5/red}{
- \node[paint=\c, minimum height=\a cm, minimum width=1.5cm] at (0.75,0) {};
- \node[paint=\c, minimum width=\a cm, minimum height=1.5cm] at (3,0) {};
- }
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- The anchors for the |isosceles triangle| are shown below (anchor |150| is
- an example of a border anchor). Note that, somewhat confusingly, the anchor
- names such as |left side| and |right corner| are named as if the triangle
- is rotated to 90 degrees. Note also that the |center| anchor does not
- necessarily correspond to any kind of geometric center.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=isosceles triangle, shape example, inner xsep=1cm]
- {Isosceles Triangle\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {apex/above, left corner/right, right corner/right,
- left side/above, right side/below, lower side/right,
- center/above, text/right, 150/above,
- mid/right, mid west/above, mid east/right,
- base/below, base west/below, base east/below,
- west/above, east/below, north/below, south/above,
- north west/below, north east/below,
- south west/above, south east/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\par\leavevmode
-\begin{shape}{kite}
- This shape is a kite, which supports the rotation of the shape border, as
- described in Section~\ref{section-rotating-shape-borders}. There are
- \pgfname{} keys to specify the upper and lower vertex angles of the kite.
- To use these keys in \tikzname, simply remove the \declare{|/pgf/|} path.
-
- \begin{key}{/pgf/kite upper vertex angle=\meta{angle} (initially 120)}
- Sets the upper internal angle of the kite.
- \end{key}
-
- \begin{key}{/pgf/kite lower vertex angle=\meta{angle} (initially 60)}
- Sets the lower internal angle of the kite.
- \end{key}
-
- \begin{key}{/pgf/kite vertex angles=\meta{angle specification}}
- This key sets the keys for both the upper and lower vertex angles (it
- stores no value itself). \meta{angle specification} can be pair of
- angles in the form \meta{upper angle} |and| \meta{lower angle}, or a
- single angle. In this latter case, both the upper and lower vertex
- angles will be the same.
- \end{key}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[every node/.style={kite, draw}]
- \node[kite upper vertex angle=135, kite lower vertex angle=70] at (0,0) {A};
- \node[kite vertex angles=90 and 45] at (1,0) {B};
- \node[kite vertex angles=60] at (2,0) {C};
-\end{tikzpicture}
-\end{codeexample}
-
- The anchors for the |kite| are shown below. Anchor |110| is an example of a
- border anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=kite, shape example, inner sep=1.5cm]
- {Kite\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {upper vertex/above, left vertex/above, lower vertex/below,
- right vertex/above, upper left side/above, upper right side/above,
- lower left side/below, lower right side/below,
- center/above, text/left, mid/right, base/below,
- mid west/left, base west/below, mid east/right, base east/below,
- west/above, east/above, north/below, south/above,
- north west/left, north east/right,
- south west/above, south east/above, 110/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{dart}
- This shape is a dart (which can also be known as an arrowhead or concave
- kite). This shape supports the rotation of the shape border, as described
- in Section~\ref{section-rotating-shape-borders}. The angle of the border
- rotation determines the direction in which the dart points (unless other
- transformations have been applied).
-
- There are \pgfname{} keys to set the angle for the `tip' of the dart and
- the angle between the `tails' of the dart. To use these keys in \tikzname,
- simply remove the \declare{|/pgf/|} path.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}
- \node[dart, draw, gray, shape border uses incircle, shape border rotate=45]
- (d) {dart};
- \draw [<->] (d.tip)++(202.5:.5cm) arc(202.5:247.5:.5cm);
- \node [left=.5cm] at (d.tip) {tip angle};
- \draw [<->] (d.tail center)++(157.5:.5cm) arc(157.5:292.5:.5cm);
- \node [right] at (d.tail center) {tail angle};
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{key}{/pgf/dart tip angle=\meta{angle} (initially 45)}
- Sets the angle at the tip of the dart.
- \end{key}
-
- \begin{key}{/pgf/dart tail angle=\meta{angle} (initially 135)}
- Sets the angle between the tails of the dart.
- \end{key}
-
- The anchors for the |dart| shape are shown below (note that the shape is
- rotated 90 degrees anti-clockwise). Anchor |110| is an example of a border
- anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=dart, shape border rotate=90, shape example, inner sep=1.25cm]
- {Dart\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {tip/above, tail center/below, right tail/below,
- left tail/below, right tail/below, left side/left, right side/right,
- center/above, text/left, mid/right, base/below,
- mid west/left, base west/below, mid east/right, base east/below,
- west/above, east/above, north/below, south/above,
- north west/left, north east/right, south west/above, south east/above,
- 110/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{circular sector}
- This shape is a circular sector (which can also be known as a wedge). This
- shape supports the rotation of the shape border, as described in
- Section~\ref{section-rotating-shape-borders}. The angle of the border
- rotation determines the direction in which the `apex' of the sector points
- (unless other transformations have been applied).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[
- every node/.style={circular sector, shape border uses incircle, draw},
-]
- \node at (0,0) {A};
- \node [shape border rotate=30] at (1.5,0) {A};
-\end{tikzpicture}
-\end{codeexample}
-
- There is a \pgfname{} key to set the central angle of the sector, which is
- expected to be less than 180 degrees. To use this key in \tikzname, simply
- remove the \declare{|/pgf/|} path.
-
- \begin{key}{/pgf/circular sector angle=\meta{angle} (initially 60)}
- Sets the central angle of the sector.
- \end{key}
-
- The anchors for the circular sector shape are shown below. Anchor |30| is
- an example of a border anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=circular sector, style=shape example, inner sep=1cm]
- {Circular Sector\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {sector center/above, arc start/below, arc end/below, arc center/below,
- center/above, base/below, mid/right, text/below,
- north/below, south/above, east/below, west/above,
- north west/above left, north east/above right,
- south west/below, south east/below, 30/right}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{cylinder}
- This shape is a 2-dimensional representation of a cylinder, which supports
- the rotation of the shape border as described in
- Section~\ref{section-rotating-shape-borders}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}
- \node[cylinder, draw, shape aspect=.5] {ABC};
-\end{tikzpicture}
-\end{codeexample}
-
- Regardless the rotation of the shape border, the height is always the
- distance between the curved ends, and the width is always the distance
- between the straight sides.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[>=stealth]
- \node [cylinder, gray!50, rotate=30, draw,
- minimum height=2cm, minimum width=1cm] (c) {Cylinder};
- \draw[red, <->] (c.top) -- (c.bottom)
- node [at end, below, black] {height};
- \draw[red, <->] (c.north) -- (c.south)
- node [at start, above, black] {width};
-\end{tikzpicture}
-\end{codeexample}
-
- Enlarging the shape to some minimum height will stretch only the body of
- the cylinder. By contrast, enlarging the shape to some minimum width will
- stretch the curved ends.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[shape aspect=.5]
- \tikzset{every node/.style={cylinder, shape border rotate=90, draw}}
- \node [minimum height=1.5cm] {A};
- \node [minimum width=1.5cm] at (1.5,0) {B};
-\end{tikzpicture}
-\end{codeexample}
-
- There are various keys to customize this shape (to use \pgfname{} keys in
- \tikzname{}, simply remove the \declare{|/pgf/|} path).
-
- \begin{key}{/pgf/aspect=\meta{value} (initially 1.0)}
- The aspect is a recommendation for the quotient of the radii of the
- cylinder end. This may be ignored if the shape is enlarged to some
- minimum width.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[]
- \tikzset{every node/.style={cylinder, shape border rotate=90, draw}}
- \node [aspect=1.0] {A};
- \node [aspect=0.5] at (1,0) {B};
- \node [aspect=0.25] at (2,0) {C};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/cylinder uses custom fill=\meta{boolean} (default true)}
- This enables the use of a custom fill for the body and the end of the
- cylinder. The background path for the shape should not be filled (e.g.,
- in \tikzname{}, the |fill| option for the node must be implicity or
- explicitly set to |none|). Internally, this key sets the \TeX-if
- |\ifpgfcylinderusescustomfill| appropriately.
- \end{key}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[aspect=0.5]
- \node [cylinder, cylinder uses custom fill, cylinder end fill=red!50,
- cylinder body fill=red!25] {Cylinder};
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{key}{/pgf/cylinder end fill=\meta{color} (initially white)}
- Sets the color for the end of the cylinder.
- \end{key}
-
- \begin{key}{/pgf/cylinder body fill=\meta{color} (initially white)}
- Sets the color for the body of the cylinder.
- \end{key}
-
- The anchors of this shape are shown below (anchor |160| is an example of a
- border anchor). Note that the cylinder shape does not distinguish between
- |outer xsep| and |outer ysep|. Only the larger of the two values is used
- for the shape. Note also the difference between the |center| and
- |shape center| anchors: |center| is the center of the cylinder body and
- also the center of rotation. The |shape center| is the center of the shape
- which includes the 2-dimensional representation of the cylinder top.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=cylinder, shape example, aspect=.5, inner xsep=3cm,
- inner ysep=1cm] {Cylinder\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {before top/above, top/above, after top/below,
- before bottom/below, bottom/above, after bottom/above,
- mid/right, mid west/right, mid east/left,
- base/below, base west/below, base east/below,
- center/above, text/above, shape center/right,
- west/right, east/left, north/above, south/below,
- north west/below, north east/above,
- south west/above, south east/below, 160/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-
-\subsection{Symbol Shapes}
-
-\begin{pgflibrary}{shapes.symbols}
- This library defines shapes that can be used for drawing symbols like a
- forbidden sign or a cloud.
-\end{pgflibrary}
-
-\begin{shape}{correct forbidden sign}
- This shape places the node inside a circle with a diagonal from the upper
- left to the lower right added. The circle is part of the background, the
- diagonal line part of the foreground path; thus, the diagonal line is on
- top of the text.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- \node [correct forbidden sign,line width=1ex,draw=red,fill=white] {Smoking};
-\end{tikzpicture}
-\end{codeexample}
-
- The shape inherits all anchors from the |circle| shape.
-\end{shape}
-
-\begin{shape}{forbidden sign}
- This shape is like |correct forbidden sign|, only the line goes from the
- lower left to the upper right. The strange naming of these shapes is for
- historical reasons.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- \node [forbidden sign,line width=1ex,draw=red,fill=white] {Smoking};
-\end{tikzpicture}
-\end{codeexample}
-
- The shape inherits all anchors from the |circle| shape.
-\end{shape}
-
-\begin{shape}{magnifying glass}
- This shape places the node inside a circle with a handle attached to the
- node. The angle of the handle and its length can be adjusted using two
- keys:
-
- \begin{key}{/pgf/magnifying glass handle angle fill=\meta{degree} (default -45)}
- The angle of the handle.
- \end{key}
-
- \begin{key}{/pgf/magnifying glass handle angle aspect=\meta{factor} (default 1.5)}
- The length of the handle as a multiple of the circle radius.
- \end{key}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- \node [magnifying glass,line width=1ex,draw] {huge};
-\end{tikzpicture}
-\end{codeexample}
- %
- The shape inherits all anchors from the |circle| shape.
-\end{shape}
-
-\begin{shape}{cloud}
- This shape is a cloud, drawn to tightly fit the node contents (strictly
- speaking, using an ellipse which tightly fits the node contents --
- including any |inner sep|).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- \node[cloud, draw, fill=gray!20, aspect=2] {ABC};
- \node[cloud, draw, fill=gray!20] at (1.5,0) {D};
-\end{tikzpicture}
-\end{codeexample}
-
- A cloud should be thought of as having a number of ``puffs'', which are the
- individual arcs drawn around the border. There are \pgfname{} keys to
- specify how the cloud is drawn (to use these keys in \tikzname{}, simply
- remove the \declare{|/pgf/|} path).
-
- \begin{key}{/pgf/cloud puffs=\meta{integer} (initially 10)}
- Sets the number of puffs for the cloud.
- \end{key}
-
- \begin{key}{/pgf/cloud puff arc=\meta{angle} (initially 135)}
- Sets the length of the puff arc (in degrees). A shorter arc can produce
- better looking joins between puffs for larger line widths.
- \end{key}
-
- Like the diamond shape, the cloud shape also uses the \declare{|aspect|}
- key to determine the ratio of the width and the height of the cloud.
- However, there may be circumstances where it may be undesirable to
- continually specify the |aspect| for the cloud. Therefore, the following
- key is implemented:
-
- \begin{key}{/pgf/cloud ignores aspect=\meta{boolean} (default true)}
- Instruct \pgfname{} to ignore the |aspect| key. Internally, the \TeX-if
- |\ifpgfcloudignoresaspect| is set appropriately. The initial value is
- |false|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}[aspect=1, every node/.style={cloud, cloud puffs=11, draw}]
- \node [fill=gray!20] {rain};
- \node [cloud ignores aspect, fill=white] at (1.5,0) {snow};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- Any minimum size requirements are applied to the ``circum-ellipse'', which
- is the ellipse which passes through all the midpoints of the puff arcs.
- These requirements are considered \emph{after} any aspect specification is
- applied.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \draw [blue, dashed] (1.5, 1) ellipse (1.5cm and 1cm);
- \node [cloud, cloud puffs=9, draw, minimum width=3cm, minimum height=2cm]
- at (1.5, 1) {};
-\end{tikzpicture}
-\end{codeexample}
-
- The anchors for the cloud shape are shown below for a cloud with eleven
- puffs. Anchor 70 is an example of a border anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=cloud, style=shape example, cloud puffs=11, aspect=1.5,
- cloud puff arc=120,inner ysep=1cm] {Cloud\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {puff 1/above, puff 2/above, puff 3/above, puff 4/below,
- puff 5/left, puff 6/below, puff 7/below, puff 8/right,
- puff 9/below, puff 10/above, puff 11/above, 70/right,
- center/above, base/below, mid/right, text/left,
- north/below, south/below, east/above, west/above,
- north west/left, north east/right,
- south west/below, south east/below}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{starburst}
- This shape is a randomly generated elliptical star, which supports the
- rotation of the shape border as described in
- Section~\ref{section-rotating-shape-borders}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- \node[starburst, fill=yellow, draw=red, line width=2pt] {\bf BANG!};
-\end{tikzpicture}
-\end{codeexample}
- %
- Like the |star| shape, the starburst should be thought of as having a set
- of inner points and outer points. The inner points lie on the ellipse which
- tightly fits the node contents (including any |inner sep|).
-
- Using a specified `starburst point height' value, the outer points are
- generated randomly between this value and one quarter of this value. For a
- given starburst shape, the angle between each point is fixed, and is
- determined by the number of points specified for the starburst.
-
- It is important to note that, whilst the maximum possible point height is
- used to calculate minimum width or height requirements, the outer points
- are randomly generated, so there is (unfortunately) no guarantee that any
- such requirements will be fully met.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- \draw[help lines] grid(3,2);
- \node[starburst, draw, minimum width=3cm, minimum height=2cm]
- at (1.5, 1) {\bf BOOM!};
-\end{tikzpicture}
-\end{codeexample}
-
- There are \pgfname{} keys to control the drawing of the starburst shape. To
- use these keys in \tikzname, simply remove the \declare{|/pgf/|} path.
-
- \begin{key}{/pgf/starburst points=\meta{integer} (initially 17)}
- Sets the number of outer points for the starburst.
- \end{key}
- %
- \begin{key}{/pgf/starburst point height=\meta{length} (initially .5cm)}
- Sets the \emph{maximum} distance between the inner point radius and the
- outer point radius.
- \end{key}
-
- \begin{key}{/pgf/random starburst=\meta{integer} (initially 100)}
- Sets the seed for the random number generator for creating the
- starburst. The maximum value for \meta{integer} is |16383|. If
- \meta{integer}|=0|, the random number generator will not be used, and
- the maximum point height will be used for all outer points. If
- \meta{integer} is omitted, a seed will be randomly chosen.
- \end{key}
-
- The basic anchors for a nine point |starburst| shape are shown below.
- Anchor |80| is an example of a border anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=starburst, starburst points=9, starburst point height=3.5cm,
- style=shape example,inner sep=1cm]
- {Starburst\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {outer point 1/above, outer point 2/above, outer point 3/right,
- outer point 4/above, outer point 5/below, outer point 6/above,
- outer point 7/left, outer point 8/above, outer point 9/above,
- inner point 1/below, inner point 2/above, inner point 3/left,
- inner point 4/above, inner point 5/above, inner point 6/above,
- inner point 7/below, inner point 8/above, inner point 9/below,
- center/above, text/left, mid/right, base/below, 80/above,
- north/below, south/below, east/left, west/right,
- north east/below, south west/below, south east/below, north west/below}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{signal}
- This shape is a ``signal'' or sign shape, that is, a rectangle, with
- optionally pointed sides. A signal can point ``to'' somewhere, with outward
- points in that direction. It can also be ``from'' somewhere, with inward
- points from that direction. The resulting points extend the node contents
- (which include the |inner sep|).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- [every node/.style={signal, draw, text=white, signal to=nowhere}]
- \node[fill=green!65!black, signal to=east] at (0,1) {To East};
- \node[fill=red!65!black, signal from=east] at (0,0) {From East};
-\end{tikzpicture}
-\end{codeexample}
-
- There are \pgfname{} keys for drawing the signal shape (to use these keys
- in \tikzname{}, simply remove the \declare{|/pgf/|} path):
-
- \begin{key}{/pgf/signal pointer angle=\meta{angle} (initially 90)}
- Sets the angle for the pointed sides of the shape. This angle is
- maintained when enforcing any minimum size requirements, so
- any adjustment to the width will affect the height, and vice versa.
- \end{key}
-
- \begin{key}{/pgf/signal from=\meta{direction}\space\opt{and \meta{opposite direction}} (initially nowhere)}
- Sets which sides take an inward pointer (i.e., that points towards the
- center of the shape). The possible values for \meta{direction} and
- \meta{opposite direction} are the compass point directions |north|,
- |south|, |east| and |west| (or |above|, |below|, |right| and |left|).
- An additional keyword |nowhere| can be used to reset the sides so they
- have no pointers. When used with |signal from| key, this only resets
- inward pointers; used with the |signal to| key, it only resets outward
- pointers.
- \end{key}
-
- \begin{key}{/pgf/signal to=\meta{direction}\space\opt{and \meta{opposite direction}} (initially east)}
- Sets which sides take an outward pointer (i.e., that points away from
- the shape).
- \end{key}
-
- Note that \pgfname{} will ignore any instruction to use directions that are
- not opposites (so using the value |east and north|, will result in only
- |north| being assigned a pointer). This is also the case if non-opposite
- values are used in the |signal to| and |signal from| keys at the same time.
- So, for example, it is not possible for a signal to have an outward point
- to the left, and also have an inward point from below.
-
- The anchors for the signal shape are shown below. Anchor |70| is an example
- of a border anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=signal, signal from=west, shape example, inner sep=2cm]
- {Signal\vrule width1pt height2cm};
- \foreach \anchor/\placement in
- {text/left, center/above, 70/above,
- base/below, base east/below, base west/below,
- mid/right, mid east/above left, mid west/above left,
- north/above, south/below,
- east/above, west/above,
- north west/above, north east/above,
- south west/below, south east/below}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{tape}
- This shape is a rectangle with optional, ``bendy'' top and bottom sides,
- which tightly fits the node contents (including the |inner sep|).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- \node[tape, draw]{ABCD};
- \node[tape, draw, tape bend top=none] at (1.5, 0) {EFGH};
-\end{tikzpicture}
-\end{codeexample}
-
- There are \pgfname{} keys to specify which sides bend and how high the
- bends are (to use these keys in \tikzname{}, simply remove the
- \declare{|/pgf/|} path):
-
- \begin{key}{/pgf/tape bend top=\meta{bend style} (initially in and out)}
- Specifies how the top side bends. The \meta{bend style} is either
- |in and out|, |out and in| or |none| (i.e., a straight line). The
- bending sides are drawn in a clockwise direction, and using the bend
- style |in and out| will mean the side will first bend inwards and then
- bend outwards. The opposite holds true for |out and in|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}[-stealth]
- \node[tape, draw, gray, minimum width=2cm](t){Tape};
- \draw [blue]([yshift=5pt] t.north west) -- ([yshift=5pt]t.north east)
- node[midway, above, black]{in and out};
- \draw [blue]([yshift=-5pt]t.south east) -- ([yshift=-5pt]t.south west)
- node[sloped, allow upside down, midway, above, black]{in and out};
-\end{tikzpicture}
-\end{codeexample}
-
- This might take a bit of getting used to, but just remember that when
- you want the bendy sides to be parallel, the sides take the same bend
- style. It is possible for the top and bottom sides to take opposite
- bend styles, but the author of this shape cannot think of a single use
- for such a combination.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}[every node/.style={tape, draw}]
- \node [tape bend top=out and in, tape bend bottom=out and in] {Parallel};
- \node at (2,0) [tape bend bottom=out and in] {Why?};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/tape bend bottom=\meta{bend style} (initially in and out)}
- Specifies how the bottom side bends.
- \end{key}%
-
- \begin{key}{/pgf/tape bend height=\meta{length} (initially 5pt)}
- Sets the total height for a side with a bend.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}[>=stealth]
- \draw [help lines] grid(3,2);
- \node [tape, fill, minimum size=2cm, red!50, tape bend top=none,
- tape bend height=1cm] at (1.5,1.5) (t) {};
- \draw [|<->|, blue] (1.5,0) -- (1.5,1)
- node [at end, above, black]{tape bend height};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- The anchors for the tape shape are shown below. Anchor |60| is an example
- of a border anchor. Note that border anchors will snap to the center of
- convex curves (i.e.\ when bending in).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=tape, tape bend height=1cm, shape example, inner xsep=3cm]
- {Tape\vrule width1pt height2cm};
- \foreach \anchor/\placement in
- {text/left, center/above, 60/above,
- base/below, base east/below, base west/below,
- mid/right, mid east/left, mid west/right,
- north/above, south/below, east/above, west/above,
- north west/above, north east/above,
- south west/below, south east/below}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{magnetic tape}
- This shape represents a `magnetic tape' or any sequential data store that
- is sometimes used in flowcharts. It is essentially a circle with a little
- tail:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\tikz\node [magnetic tape, draw] (A) {A};
-\end{codeexample}
-
- The following keys can be used to customise the |magnetic tape| shape:
-
- \begin{key}{/pgf/magnetic tape tail extend=\meta{distance} (initially 0cm)}
- This key sets how far the tail extends beyond the radius of the tape.
- Negative values will be ignored.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}[every node/.style={magnetic tape, draw}]
- \node [magnetic tape tail extend=0cm] at (0,0) {A};
- \node [magnetic tape tail extend=0.25cm] at (0,1) {B};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/magnetic tape tail=\meta{proportion} (initially 0.15)}
- This key sets the thickness of the `tail' to be \meta{proportion} times
- the radius of the shape. The \meta{proportion} should be between |0.0|
- and |1.0|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}[every node/.style={magnetic tape, draw}]
- \node [magnetic tape tail=0.5, magnetic tape tail extend=0.5cm] {A};
- \node [magnetic tape tail=0.25] at (0,1) {B};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- The following figure shows the anchors this shape defines; the anchors 10
- and 130 are example of border anchors.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\Huge
-\begin{tikzpicture}
-\node[name=s,shape=magnetic tape,shape example,inner sep=0.75cm,
-magnetic tape tail extend=0.5cm]
- {Magnetic Tape\vrule width 1pt height 2cm};
-\foreach \anchor/\placement in
- {north west/above left, north/above, north east/above right,
- west/left, center/above, east/right,
- mid west/right, mid/right, mid east/left,
- base west/below, base/below, base east/right,
- south west/below left, south/below, south east/left,
- text/left, 10/right, 130/above,
- tail east/right, tail south east/below, tail north east/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-
-\subsection{Arrow Shapes}
-
-\begin{pgflibrary}{shapes.arrows}
- This library defines arrow shapes. Note that an arrow shape is something
- quite different from a (normal) arrow tip: It is a shape that just
- ``happens'' to ``look like'' an arrow. In particular, you cannot use these
- shapes as arrow tips.
-\end{pgflibrary}
-
-\begin{shape}{single arrow}
- This shape is an arrow, which tightly fits the node contents (including any
- |inner sep|). This shape supports the rotation of the shape border, as
- described in Section~\ref{section-rotating-shape-borders}. The angle of
- rotation determines in which direction the arrow points (provided no other
- rotational transformations are applied).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\begin{tikzpicture}[every node/.style={single arrow, draw},
- rotate border/.style={shape border uses incircle, shape border rotate=#1}]
- \node {right};
- \node at (2,0) [shape border rotate=90]{up};
- \node at (1,1) [rotate border=37, inner sep=0pt]{$37^\circ$};
-\end{tikzpicture}
-\end{codeexample}
-
- Regardless of the rotation of the arrow border, the width is measured
- between the back ends of the arrow head, and the height is measured from
- the arrow tip to the end of the arrow tail.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\begin{tikzpicture}[>=stealth,
- rotate border/.style={shape border uses incircle, shape border rotate=#1}]
- \node[rotate border=-30, fill=gray!25, minimum height=3cm, single arrow,
- single arrow head extend=.5cm, single arrow head indent=.25cm] (arrow) {};
- \draw[red, <->] (arrow.before tip) -- (arrow.after tip)
- node [near end, left, black] {width};
- \draw[red, <->] (arrow.tip) -- (arrow.tail)
- node [near end, below left, black] {height};
-\end{tikzpicture}
-\end{codeexample}
-
- There are \pgfname{} keys that can be used to customize this shape (to use
- these keys in \tikzname{}, simply remove the \declare{|/pgf/|} path).
-
- \begin{key}{/pgf/single arrow tip angle=\meta{angle} (initially 90)}
- Sets the angle for the arrow tip. Enlarging the arrow to some minimum
- width may increase the height of the shape to maintain this angle.
- \end{key}
-
- \begin{key}{/pgf/single arrow head extend=\meta{length} (initially .5cm)}
- This sets the distance between the tail of the arrow and the outer end
- of the arrow head. This may change if the shape is enlarged to some
- minimum width.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\begin{tikzpicture}
- \node[single arrow, draw, single arrow head extend=.5cm, gray!50, rotate=60]
- (a) {Arrow};
- \draw[red, |<->|] (a.before tip) -- (a.before head)
- node [midway, below, sloped, black] {head extend};
-\end{tikzpicture}
-\end{codeexample}
-\end{key}
-
- \begin{key}{/pgf/single arrow head indent=\meta{length} (initially 0cm)}
- This moves the point where the arrow head joins the shaft of the arrow
- \emph{towards} the arrow tip, by \meta{length}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\begin{tikzpicture}[every node/.style={single arrow, draw=none, rotate=60}]
- \node [fill=red!50] {arrow 1};
- \node [fill=blue!50, single arrow head indent=1ex] at (1.5,0) {arrow 2};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- The anchors for this shape are shown below (anchor |20| is an example of a
- border anchor).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=single arrow, shape example, single arrow head extend=1.5cm]
- {Single Arrow\vrule width1pt height2cm};
- \foreach \anchor/\placement in
- {text/above, center/above, 20/above,
- mid west/left, mid/above, mid east/above left,
- base west/below, base/below, base east/below,
- tip/above, before tip/above, after tip/below, before head/above,
- after head/below, after tail/above, before tail/below, tail/right,
- north/above, south/below, east/below, west/above,
- north west/above, north east/below, south west/below, south east/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{double arrow}
- This shape is a double arrow, which tightly fits the node contents
- (including any |inner sep|), and supports the rotation of the shape border,
- as described in Section~\ref{section-rotating-shape-borders}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\begin{tikzpicture}[every node/.style={double arrow, draw}]
- \node [double arrow, draw] {Left or Right};
-\end{tikzpicture}
-\end{codeexample}
-
- The double arrow behaves exactly like the single arrow, so you need to
- remember that the width is \emph{always} the distance between the back ends
- of the arrow heads, and the height is \emph{always} the tip-to-tip
- distance.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\begin{tikzpicture}[>=stealth,
- rotate border/.style={shape border uses incircle, shape border rotate=#1}]
- \node[rotate border=210, fill=gray!25, minimum height=3cm, double arrow,
- double arrow head extend=.5cm, double arrow head indent=.25cm] (arrow) {};
- \draw[red, <->] (arrow.before tip 1) -- (arrow.after tip 1)
- node [near start, right, black] {width};
- \draw[red, <->] (arrow.tip 1) -- (arrow.tip 2)
- node [near end, above left, black] {height};
-\end{tikzpicture}
-\end{codeexample}
-
- The \pgfname{} keys that can be used to customize the double arrow behave
- similarly to the keys for the single arrow (to use these keys in
- \tikzname{}, simply remove the \declare{|/pgf/|} path).
-
- \begin{key}{/pgf/double arrow tip angle=\meta{angle} (initially 90)}
- Sets the angle for the arrow tip. Enlarging the arrow to some minimum
- width may increase the height of the shape to maintain this angle.
- \end{key}
-
- \begin{key}{/pgf/double arrow head extend=\meta{length} (initially .5cm)}
- This sets the distance between the shaft of the arrow and the outer end
- of the arrow heads. This may change if the shape is enlarged to some
- minimum width.
- \end{key}
-
- \begin{key}{/pgf/double arrow head indent=\meta{length} (initially 0cm)}
- This moves the point where the arrow heads join the shaft of the arrow
- \emph{towards} the arrow tips, by \meta{length}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\begin{tikzpicture}[every node/.style={double arrow, draw=none, rotate=-60}]
- \node [fill=red!50] {arrow 1};
- \node [fill=blue!50, double arrow head indent=1ex] at (1.5,0) {arrow 2};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- The anchors for this shape are shown below (anchor |20| is an example of a
- border anchor).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=double arrow, double arrow head extend=1.5cm, shape example, inner xsep=2cm]
- {Double Arrow\vrule width1pt height2cm};
- \foreach \anchor/\placement in
- {text/above, center/above, 20/above,
- mid west/above right, mid/above, mid east/above left,
- base west/below, base/below, base east/below,
- before head 1/above, before tip 1/above, tip 1/above, after tip 1/below, after head 1/below,
- before head 2/above, before tip 2/below, tip 2/above, after tip 2/above, after head 2/below,
- north/above, south/below, east/below, west/below,
- north west/below, north east/below, south west/above, south east/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{arrow box}
- This shape is a rectangle with optional arrows which extend from the four
- sides.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\begin{tikzpicture}
- \node[arrow box, draw] {A};
- \node[arrow box, draw, arrow box arrows={north:.5cm, west:0.75cm}]
- at (2,0) {B};
-\end{tikzpicture}
-\end{codeexample}
-
- Any minimum size requirements are applied to the main rectangle
- \emph{only}. This does not pose too many problems if you wish to
- accommodate the length of the arrows, as it is possible to specify the
- length of each arrow independently, from either the border of the rectangle
- (the default) or the center of the rectangle.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\begin{tikzpicture}
- \tikzset{box/.style={arrow box, fill=#1}}
- \draw [help lines] grid(3,2);
- \node[box=blue!50, arrow box arrows={east:2cm}] at (1,1.5){One};
- \node[box=red!50, arrow box arrows={east:2cm from center}] at (1,0.5){Two};
-\end{tikzpicture}
-\end{codeexample}
-
- There are various \pgfname{} keys for drawing this shape (to use these keys
- in \tikzname, simply remove the \declare{/pgf/} path).
-
-\begin{key}{/pgf/arrow box tip angle=\meta{angle} (initially 90)}
- Sets the angle at the arrow tip for all four arrows.
-\end{key}
-
-\begin{key}{/pgf/arrow box head extend=\meta{length} (initially .125cm)}
- Sets the distance the arrow head extends away from the shaft of the arrow.
- This applies to all arrows.
-\end{key}
-
-\begin{key}{/pgf/arrow box head indent=\meta{length} (initially 0cm)}
- Moves the point where the arrow head joins the shaft of the arrow
- \emph{towards} the arrow tip. This applies to all arrows.
-\end{key}
-
-\begin{key}{/pgf/arrow box shaft width=\meta{length} (initially .125cm)}
- Sets the width of the shaft of all arrows.
-\end{key}
-
-\begin{key}{/pgf/arrow box north arrow=\meta{distance} (initially .5cm)}
- Sets the distance the north arrow extends from the node. By default this is
- from the border of the shape, but by using the additional keyword
- |from center|, the distance will be measured from the center of the shape.
- If \meta{distance} is |0pt| or a negative distance, the arrow will not be
- drawn.
-\end{key}
-
-\begin{key}{/pgf/arrow box south arrow=\meta{distance} (initially .5cm)}
- Sets the distance the south arrow extends from the node.
-\end{key}
-
-\begin{key}{/pgf/arrow box east arrow=\meta{distance} (initially .5cm)}
- Sets the distance the east arrow extends from the node.
-\end{key}
-
-\begin{key}{/pgf/arrow box west arrow=\meta{distance} (initially .5cm)}
- Sets the distance the west arrow extends from the node.
-\end{key}
-
-\begin{key}{/pgf/arrow box arrows={\ttfamily\char`\{}\meta{list}{\ttfamily\char`\}}}
- Sets the distance that all arrows extend from the node. The specification
- in \meta{list} consists of the four compass points |north|, |south|, |east|
- or |west|, separated by commas (so the list must be contained within
- braces). The distances can be specified after each side separated by a
- colon (e.g., |north:1cm|, or |west:5cm from center|). If an item specifies
- no distance, the most recently specified distance will be used (at the
- start of the list this is |0cm|, so the first item in the list should
- specify a distance). Any sides not specified will not be drawn with an
- arrow.
-\end{key}
-
-The anchors for this shape are shown below (unfortunately, due to its size,
-this example must be rotated). Anchor |75| is an example of a border anchor. If
-a side is drawn without an arrow, the anchors for that arrow should be
-considered unavailable. They are (unavoidably) defined, but default to the
-center of the appropriate side.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.arrows}}]
-\Huge
-\begin{tikzpicture}
- \node[shape=arrow box, shape example, inner xsep=1cm, inner ysep=1.5cm, arrow box shaft width=2cm,
- arrow box arrows={north:3.5cm from border, south, east:5cm from border, west},
- arrow box head extend=0.75cm, rotate=-90](s) {Arrow Box\vrule width1pt height2cm};
- \foreach \anchor/\placement in
- {center/above, text/above, mid/right, base/below, 75/above,
- mid east/right, mid west/left, base east/right, base west/left,
- north/below, south/below, east/below, west/below,
- north east/above, south east/above, south west/below, north west/below,
- north arrow tip/above,south arrow tip/above, east arrow tip/above, west arrow tip/above,
- before north arrow/above, before north arrow head/below left, before north arrow tip/above left,
- after north arrow tip/above right, after north arrow head/below right, after north arrow/below,
- before south arrow/below, before south arrow head/above right, before south arrow tip/below right,
- after south arrow tip/below left, after south arrow head/above left, after south arrow/above,
- before east arrow/above, before east arrow head/above right, before east arrow tip/above,
- after east arrow tip/below, after east arrow head/below right, after east arrow/below,
- before west arrow/below, before west arrow head/below left, before west arrow tip/below,
- after west arrow tip/above, after west arrow head/above left, after west arrow/below}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement, rotate=-90] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
-%
-\end{shape}
-
-
-\subsection{Shapes with Multiple Text Parts}
-
-\begin{pgflibrary}{shapes.multipart}
- This library defines general-purpose shapes that are composed of multiple
- (text) parts.
-\end{pgflibrary}
-
-
-\begin{shape}{circle split}
- This shape is a multi-part shape consisting of a circle with a line in the
- middle. The upper part is the main part (the |text| part), the lower part
- is the |lower| part.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\begin{tikzpicture}
- \node [circle split,draw,double,fill=red!20]
- {
- $q_1$
- \nodepart{lower}
- $00$
- };
-\end{tikzpicture}
-\end{codeexample}
-
- The shape inherits all anchors from the |circle| shape and defines the
- |lower| anchor in addition. See also the following figure:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=circle split,shape example] {text\nodepart{lower}lower};
- \foreach \anchor/\placement in
- {north west/above left, north/above, north east/above right,
- west/left, center/below, east/right,
- mid west/right, mid/above, mid east/left,
- base west/left, base/below, base east/right,
- south west/below left, south/below, south east/below right,
- text/left, lower/left, 130/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{circle solidus}
- This shape (due to Manuel Lacruz) is similar to the split circle, but the
- two text parts are arranged diagonally.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\begin{tikzpicture}
- \node [circle solidus,draw,double,fill=red!20]
- {
- $q_1$
- \nodepart{lower}
- $00$
- };
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=circle solidus,shape example,inner xsep=1cm] {text\nodepart{lower}lower};
- \foreach \anchor/\placement in
- {north west/above left, north/above, north east/above right,
- west/left, center/below, east/right,
- mid west/right, mid/above, mid east/left,
- base west/left, base/below, base east/right,
- south west/below left, south/below, south east/below right,
- text/left, lower/left, 130/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{ellipse split}
- This shape is a multi-part shape consisting of an ellipse with a line in
- the middle. The upper part is the main part (the |text| part), the lower
- part is the |lower| part. The anchors for this shape are shown below.
- Anchor |60| is a border anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=ellipse split,shape example] {text\nodepart{lower}lower};
- \foreach \anchor/\placement in
- {center/below, text/left, lower/left, 60/above right,
- mid/above, mid east/above, mid west/above,
- base/right, base east/left, base west/right,
- north/above, south/below, east/below, west/below,
- north east/above, south east/below, south west/below, north west/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{rectangle split}
- This shape is a rectangle which can be split either horizontally or
- vertically into several parts.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\begin{tikzpicture}[my shape/.style={
- rectangle split, rectangle split parts=#1, draw, anchor=center}]
- \node [my shape=5] at (0,1)
- {a\nodepart{two}b\nodepart{three}c\nodepart{four}d\nodepart{five}e};
- \node [my shape=5, rectangle split horizontal] at (2,2)
- {1\nodepart{two}2\nodepart{three}3\nodepart{four}4\nodepart{five}5};
- \node [my shape=3] at (3,0.5)
- {A\nodepart{two}B\nodepart{three}C};
- \node [my shape=4, rectangle split horizontal] at (1.5,0.5)
- {1\nodepart{two}2\nodepart{three}3\nodepart{four}4};
-\end{tikzpicture}
-\end{codeexample}
-
- The shape can be split into a maximum of twenty parts. However, to avoid
- allocating a lot of unnecessary boxes, \pgfname{} only allocates four boxes
- by default. To use the |rectangle| |split| shape with more than four boxes,
- the extra boxes must be allocated manually in advance (perhaps using
- |\newbox| or |\let|). The boxes take the form
- |\pgfnodepart|\meta{number}|box|, where \meta{number} is from the cardinal
- numbers |one|, |two|, |three|, \ldots{} and so on. |\pgfnodepartonebox| is
- special in that it is synonymous with |\pgfnodeparttextbox|. For
- compatibility with earlier versions of this shape, the boxes
- |\pgfnodeparttwobox|, |\pgfnodepartthreebox| and |\pgfnodepartfourbox|, can
- be referred to using the ordinal numbers: |\pgfnodepartsecondbox|,
- |\pgfnodepartthirdbox| and |\pgfnodepartfourthbox|. In order to facilitate
- the allocation of these extra boxes, the following key is provided:
-
- \begin{key}{/pgf/rectangle split allocate boxes=\meta{number}}
- This key checks if \meta{number} boxes have been allocated, and if not,
- it allocates the required boxes using |\newbox| (some ``magic'' is
- performed to get around the fact that |\newbox| is declared |\outer| in
- plain \TeX).
- \end{key}
-
- When split vertically, the rectangle split will meet any |minimum width|
- requirements, but any |minimum height| will be ignored. Conversely when
- split horizontally, |minimum height| requirements will be met, but any
- |minimum width| will be ignored. In addition, |inner sep| is applied to
- every part that is used, so it cannot be specified independently for a
- particular part.
-
- There are several \pgfname{} keys to specify how the shape is drawn. To use
- these keys in \tikzname, simply remove the \declare{|/pgf/|} path:
-
- \begin{key}{/pgf/rectangle split parts=\meta{number} (initially 4)}
- Split the rectangle into \meta{number} parts, which should be in the
- range |1| to |20|. If more than four parts are needed, the boxes should
- be allocated in advance as described above.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\begin{tikzpicture}[every text node part/.style={align=center}]
- \node[rectangle split, rectangle split parts=3, draw, text width=2.75cm]
- {Student
- \nodepart{two}
- age:int \\
- name:String
- \nodepart{three}
- getAge():int \\
- getName():String};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/rectangle split horizontal=\opt{\meta{boolean}} (default true)}
- This key determines whether the rectangle is split horizontally or
- vertically
- \end{key}
-
- \begin{key}{/pgf/rectangle split ignore empty parts=\opt{\meta{boolean}} (default true)}
- When \meta{boolean} is true, \pgfname{} will ignore any part that is
- empty \emph{except the text part}. This effectively overrides the
- |rectangle split parts| key in that, if 3 parts (for example) are
- specified, but one is empty, only two will be shown.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\begin{tikzpicture}[every node/.style={draw, anchor=text, rectangle split,
- rectangle split parts=3}]
- \node {text \nodepart{second} \nodepart{third}third};
- \node [rectangle split ignore empty parts] at (2,0)
- {text \nodepart{second} \nodepart{third}third};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/rectangle split empty part width=\meta{length} (initially 1ex)}
- Sets the default width for a node part box if it is empty and empty
- parts are not ignored.
- \end{key}
-
- \begin{key}{/pgf/rectangle split empty part height=\meta{length} (initially 1ex)}
- Sets the default height for a node part box if it is empty and empty
- parts are not ignored.
- \end{key}
-
- \begin{key}{/pgf/rectangle split empty part depth=\meta{length} (initially 0ex)}
- Sets the default depth for a node part box if it is empty and empty
- parts are not ignored.
- \end{key}
-
- \begin{key}{/pgf/rectangle split part align={\ttfamily\char`\{}\meta{list}{\ttfamily\char`\}} (initially center)}
- Sets the alignment of the boxes inside the node parts. Each item in
- \meta{list} should be separated by commas (so if there is more than one
- item in \meta{list}, it must be surrounded by braces).
-
- When the rectangle is split vertically, the entries in \meta{list} must
- be one of |left|, |right|, or |center|. If \meta{list} has less entries
- than node parts then the remaining boxes are aligned according to the
- last entry in the list. Note that this only aligns the boxes in each
- part and \emph{does not} affect the alignment of the contents of the
- boxes.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\def\x{one \nodepart{two} 2 \nodepart{three} three \nodepart{four} 4}
-\begin{tikzpicture}[
- every node/.style={rectangle split, rectangle split parts=4,
- draw}
- ]
- \node[rectangle split part align={center, left, right}] at (0,0) {\x};
- \node[rectangle split part align={center, left}] at (1.25,0) {\x};
- \node[rectangle split part align={center}] at (2.5,0) {\x};
-\end{tikzpicture}
-\end{codeexample}
-
- When the rectangle is split horizontally, the entries in \meta{list}
- must be one of |top|, |bottom|, |center| or |base|. Note that using the
- value |base| will only make sense if all the node part boxes are being
- aligned in this way. This is because the |base| value aligns the boxes
- in relation to each other, whereas the other values align the boxes in
- relation to the part of the shape they occupy.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\def\x{\Large w\nodepart{two}x\nodepart{three}\Huge y\nodepart{four}\tiny z}
-\begin{tikzpicture}[
- every node/.style={rectangle split, rectangle split parts=4,
- draw, rectangle split horizontal}
- ]
- \node[rectangle split part align={center, top, bottom}] at (0,0) {\x};
- \node[rectangle split part align={center, top}] at (0,-1.25) {\x};
- \node[rectangle split part align={center}] at (0,-2.5) {\x};
- \node[rectangle split part align=base] at (0,-3.75) {\x};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/rectangle split draw splits=\opt{\meta{boolean}} (default true)}
- Sets whether the line or lines between node parts will be drawn.
- Internally, this sets the \TeX-if |\ifpgfrectanglesplitdrawsplits|
- appropriately.
- \end{key}
-
- \begin{key}{/pgf/rectangle split use custom fill=\opt{\meta{boolean}} (default true)}
- This enables the use of a custom fill for each of the node parts
- (including the area covered by the |inner sep|). The background path
- for the shape should not be filled (e.g., in \tikzname{}, the |fill|
- option for the node must be implicity or explicitly set to |none|).
- Internally, this key sets the \TeX-if
- |\ifpgfrectanglesplitusecustomfill| appropriately.
- \end{key}
-
- \begin{key}{/pgf/rectangle split part fill={\ttfamily\char`\{}\meta{list}{\ttfamily\char`\}} (initially white)}
- Sets the custom fill color for each node part shape. The items in
- \meta{list} should be separated by commas (so if there is more than one
- item in \meta{list}, it must be surrounded by braces). If \meta{list}
- has less entries than node parts, then the remaining node parts use the
- color from the last entry in the list. This key will automatically set
- |/pgf/rectangle split use custom fill|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\begin{tikzpicture}
- \tikzset{every node/.style={rectangle split, draw, minimum width=.5cm}}
- \node[rectangle split part fill={red!50, green!50, blue!50, yellow!50}] {};
- \node[rectangle split part fill={red!50, green!50, blue!50}] at (0.75,0) {};
- \node[rectangle split part fill={red!50, green!50}] at (1.5,0) {};
- \node[rectangle split part fill={red!50}] at (2.25,0) {};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- The anchors for the |rectangle split| shape split vertically into four, are
- shown below (anchor |70| is an example of a border angle). When a node part
- is missing, the anchors prefixed with the name of that node part should be
- considered unavailable. They are (unavoidably) defined, but default to
- other anchor positions.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.multipart}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=rectangle split, rectangle split parts=4, shape example,
- inner ysep=0.75cm]
- {\nodepart{text}text\nodepart{two}two
- \nodepart{three}three\nodepart{four}four};
- \foreach \anchor/\placement in
- {text/left, text east/above, text west/above,
- two/left, two east/above, two west/above,
- three/left, three east/below, three west/below,
- four/left, four east/below, four west/below,
- text split/left, text split east/above, text split west/above,
- two split/left, two split east/above, two split west/above,
- three split/left, three split east/below, three split west/below,
- north/above, south/below, east/below, west/below,
- north west/above, north east/above, south west/below, south east/below,
- center/above, 70/above, mid/above, base/below}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-
-\subsection{Callout Shapes}
-
-\begin{pgflibrary}{shapes.callouts}
- Producing basic callouts can be done quite easily in \pgfname{} and
- \tikzname{} by creating a node and then subsequently drawing a path from
- the border of the node to the required point. This library provides more
- fancy, `balloon'-style callouts.
-\end{pgflibrary}
-
-Callouts consist of a main shape and a pointer (which is part of the shape)
-which points to something in (or outside) the picture. The position on the
-border of the main shape to which the pointer is connected is determined
-automatically. However, the pointer is ignored when calculating the minimum
-size of the shape, and also when positioning anchors.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.callouts}}]
-\begin{tikzpicture}[remember picture]
- \node[ellipse callout, draw] (hallo) {Hallo!};
-\end{tikzpicture}
-\end{codeexample}
-
-There are two kinds of pointer: the ``relative'' pointer and the ``absolute''
-pointer. The relative pointer calculates the angle of a specified coordinate
-relative to the center of the main shape, locates the point on the border to
-which this angle corresponds, and then adds the coordinate to this point. This
-seemingly over-complex approach means than you do not have to guess the size of
-the main shape: the relative pointer will always be outside. The absolute
-pointer, on the other hand, is much simpler: it points to the specified
-coordinate absolutely (and can even point to named coordinates in different
-pictures).
-%
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.callouts}}]
-\begin{tikzpicture}[remember picture, note/.style={rectangle callout, fill=#1}]
- \draw [help lines] grid(3,2);
- \node [note=red!50, callout relative pointer={(0,1)}] at (3,1) {Relative};
- \node [note=blue!50, callout absolute pointer={(0,1)}] at (1,0) {Absolute};
- \node [note=green!50, opacity=.5, overlay,
- callout absolute pointer={(hallo.south)}] at (1,2) {Outside};
-\end{tikzpicture}
-\end{codeexample}
-
-The following keys are common to all callouts. Please remember that the
-|callout| |relative| |pointer|, and |callout| |absolute| |pointer| keys take a
-different format for their value depending on whether they are being used in
-\pgfname{} or \tikzname{}.
-
-\begin{key}{/pgf/callout relative pointer=\meta{coordinate} (initially {\ttfamily\char`\\pgfpointpolar\char`\{315\char`\}\char`\{.5cm\char`\}})}
- Sets the vector of the callout pointer `relative' to the callout shape.
-\end{key}
-
-\begin{key}{/pgf/callout absolute pointer=\meta{coordinate}}
- Sets the vector of the callout pointer absolutely within the picture.
-\end{key}
-
-\begin{key}{/tikz/callout relative pointer=\meta{coordinate} (initially {(315:.5cm)})}
- The \tikzname{} version of the |callout relative pointer| key. Here,
- \meta{coordinate} can be specified using the \tikzname{} format for
- coordinates.
-\end{key}
-
-\begin{key}{/tikz/callout absolute pointer=\meta{coordinate}}
- The \tikzname{} version of the |callout absolute pointer| key. Here,
- \meta{coordinate} can be specified using the \tikzname{} format for
- coordinates.
-\end{key}
-
-It is also possible to shorten the pointer by some distance, using the
-following key:
-
-\begin{key}{/pgf/callout pointer shorten=\meta{distance} (initially 0cm)}
- Moves the callout pointer towards the center of the callout's main shape by
- \meta{distance}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.callouts}}]
-\begin{tikzpicture}
- \tikzset{callout/.style={ellipse callout, callout pointer arc=30,
- callout absolute pointer={#1}}}
- \draw (0,0) grid (3,2);
- \node[callout={(3,1.5)}, fill=red!50] at (0,1.5) {A};
- \node[callout={(3,.5)}, fill=green!50, callout pointer shorten=1cm]
- at (0,.5) {B};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{shape}{rectangle callout}
- This shape is a callout whose main shape is a rectangle, which tightly fits
- the node contents (including any |inner sep|). It supports the keys
- described above and also the following key:
-
- \begin{key}{/pgf/callout pointer width=\meta{length} (initially .25cm)}
- Sets the width of the pointer at the border of the rectangle.
- \end{key}
-
- The anchors for this shape are shown below (anchor |60| is an example of a
- border anchor). The pointer direction is ignored when placing anchors.
- Additionally, when using an absolute pointer, the |pointer| anchor should
- not to be used to used to position the shape as it is calculated whilst the
- shape is being drawn.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.callouts}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=rectangle callout, callout relative pointer={(1.25cm,-1cm)},
- callout pointer width=2cm, shape example, inner xsep=2cm, inner ysep=1cm]
- {Rectangle Callout\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {center/above, text/below, 60/above,
- mid/right, mid west/left, mid east/right,
- base/below, base west/below, base east/below,
- north/above, south/below, east/above, west/above,
- north west/above, north east/above,
- south west/below, south east/below,
- pointer/below}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{ellipse callout}
- This shape is a callout whose main shape is an ellipse, which tightly fits
- the node contents (including any |inner sep|). It uses the
- |absolute callout pointer|, |relative callout pointer| and
- |callout pointer shorten| keys, and also the following key:
-
- \begin{key}{/pgf/callout pointer arc=\meta{angle} (initially 15)}
- Sets the width of the pointer at the border of the ellipse according to
- an arc of length \meta{angle}.
- \end{key}
-
- The anchors for this shape are shown below (anchor |60| is an example of a
- border anchor). The pointer direction is ignored when placing anchors and
- the |pointer| anchor can only be used to position the shape when the
- relative anchor is specified.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.callouts}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=ellipse callout, callout relative pointer={(1.25cm,-1cm)},
- callout pointer width=2cm, shape example, inner xsep=1cm, inner ysep=.5cm]
- {Ellipse Callout\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {center/above, text/below, 60/above,
- mid/above, mid west/right, mid east/left,
- base/below, base west/below, base east/below,
- north/above, south/below, east/above, west/above,
- north west/above left, north east/above right,
- south west/below left, south east/below right,
- pointer/below}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{cloud callout}
- This shape is a callout whose main shape is a cloud which fits the node
- contents. The pointer is segmented, consisting of a series of shrinking
- ellipses. This callout requires the |shapes.callouts| library (for the cloud
- shape). If this library is not loaded an error will result.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.callouts}}]
-\begin{tikzpicture}
- \node[cloud callout, cloud puffs=15, aspect=2.5, cloud puff arc=120,
- shading=ball,text=white] {\bf Imagine...};
-\end{tikzpicture}
-\end{codeexample}
-
- The |cloud callout| supports the |absolute callout pointer|,
- |relative callout pointer| and |callout pointer shorten| keys, as described
- above. The main shape can be modified using the same keys as the |cloud|
- shape. The following keys are also supported:
-
- \begin{key}{/pgf/callout pointer start size=\meta{value} (initially .2 of callout)}
- Sets the size of the first segment in the pointer (i.e., the segment
- nearest the main cloud shape). There are three possible forms for
- \meta{value}:
- %
- \begin{itemize}
- \item A single dimension (e.g., |5pt|), in which case the first
- ellipse will have equal diameters of 5pt.
- \item Two dimensions (e.g., |10pt and 2.5pt|), which sets the $x$
- and $y$ diameters of the first ellipse.
- \item A decimal fraction (e.g., |.2 of callout|), in which case the
- $x$ and $y$ diameters of the first ellipse will be set as
- fractions of the width and height of the main shape. The
- keyword |of callout| cannot be omitted.
- \end{itemize}
- \end{key}
-
- \begin{key}{/pgf/callout pointer end size=\meta{value} (initially .1 of callout)}
- Sets the size of the last ellipse in the pointer.
- \end{key}
-
- \begin{key}{/pgf/callout pointer segments=\meta{number} (initially 2)}
- Sets the number of segments in the pointer. Note that \pgfname{} will
- happily overlap segments if too many are specified.
- \end{key}
-
- The anchors for this shape are shown below (anchor |70| is an example of a
- border anchor). The pointer direction is ignored when placing anchors and
- the pointer anchor can only be used to position the shape when the relative
- anchor is specified. Note that the center of the last segment is drawn at
- the |pointer| anchor.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.callouts}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s, shape=cloud callout, style=shape example, cloud puffs=11, aspect=1.5,
- cloud puff arc=120,inner xsep=.5cm, callout pointer start size=.25 of callout,
- callout pointer end size=.15 of callout, callout relative pointer={(315:4cm)},
- callout pointer segments=2] {Cloud Callout\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {puff 1/above, puff 2/above, puff 3/above, puff 4/below,
- puff 5/left, puff 6/below, puff 7/below, puff 8/right,
- puff 9/below, puff 10/above, puff 11/above, 70/right,
- center/above, base/below, mid/right, text/left,
- north/below, south/below, east/above, west/above,
- north west/left, north east/right,
- south west/below, south east/below,pointer/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-
-\subsection{Miscellaneous Shapes}
-
-\begin{pgflibrary}{shapes.misc}
- This library defines general-purpose shapes that do not fit into the
- previous categories.
-\end{pgflibrary}
-
-\begin{shape}{cross out}
- This shape ``crosses out'' the node. Its foreground path are simply two
- diagonal lines between the corners of the node's bounding box. Here is an
- example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- \node [cross out,draw=red] at (1.5,1) {cross out};
-\end{tikzpicture}
-\end{codeexample}
-
- A useful application is inside text as in the following example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-Cross \tikz[baseline] \node [cross out,draw,anchor=text] {me}; out!
-\end{codeexample}
-
- This shape inherits all anchors from the |rectangle| shape, see also the
- following figure:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=cross out,shape example] {cross out\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {north west/above left, north/above, north east/above right,
- west/left, center/above, east/right,
- mid west/right, mid/above, mid east/left,
- base west/left, base/below, base east/right,
- south west/below left, south/below, south east/below right,
- text/left, 10/right, 130/above}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{strike out}
- This shape is identical to the |cross out| shape, only its foreground path
- consists of a single line from the lower left to the upper right.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-Strike \tikz[baseline] \node [strike out,draw,anchor=text] {me}; out!
-\end{codeexample}
-
- See the |cross out| shape for the anchors.
-\end{shape}
-
-\begin{shape}{rounded rectangle}
- This shape is a rectangle which can have optionally rounded sides.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\begin{tikzpicture}
- \node[rounded rectangle, draw, fill=red!20]{Hallo};
-\end{tikzpicture}
-\end{codeexample}
-
- There are keys to specify how the sides are rounded (to use these keys in
- \tikzname, simply remove the \declare{|/pgf/|} path).
-
- \begin{key}{/pgf/rounded rectangle arc length=\meta{angle} (initially 180)}
- Sets the length of the arcs for the rounded ends. Recommended values
- for \meta{angle} are between |90| and |180|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\begin{tikzpicture}
- \matrix[row sep=5pt, every node/.style={draw, rounded rectangle}]{
- \node[rounded rectangle arc length=180] {180}; \\
- \node[rounded rectangle arc length=120] {120}; \\
- \node[rounded rectangle arc length=90] {90}; \\};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/rounded rectangle west arc=\meta{arc type} (initially convex)}
- Sets the style of the rounding for the left side. The permitted values
- for \meta{arc type} are |concave|, |convex|, or |none|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\begin{tikzpicture}
- \matrix[row sep=5pt, every node/.style={draw, rounded rectangle}]{
- \node[rounded rectangle west arc=concave] {Concave}; \\
- \node[rounded rectangle west arc=convex] {Convex}; \\
- \node[rounded rectangle left arc=none] {None}; \\};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{stylekey}{/pgf/rounded rectangle left arc=\meta{arc type}}
- Alternative key for specifying the west arc.
- \end{stylekey}
-
- \begin{key}{/pgf/rounded rectangle east arc=\meta{arc type} (initially convex)}
- Sets the style of the rounding for the east side.
- \end{key}
-
- \begin{stylekey}{/pgf/rounded rectangle right arc=\meta{arc type}}
- Alternative key for specifying the east arc.
- \end{stylekey}
-
- The anchors for this shape are shown below (anchor |10| is an example of a
- border angle). Note that if only one side is rounded, the |center| anchor
- will not be the precise center of the shape.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=rounded rectangle, shape example, inner xsep=1.5cm, inner ysep=1cm]
- {Rounded Rectangle\vrule width 1pt height 2cm};
- \foreach \anchor/\placement in
- {center/above, text/below, 10/above,
- mid/above, mid west/right, mid east/left,
- base/below, base west/below, base east/below,
- north/above, south/below, east/above, west/above,
- north west/above left, north east/above right,
- south west/below left, south east/below right}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-\begin{shape}{chamfered rectangle}
- This shape is a rectangle with optionally chamfered corners.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\begin{tikzpicture}
- \node[chamfered rectangle, white, fill=red, double=red, draw, very thick]
- {\bf STOP!};
-\end{tikzpicture}
-\end{codeexample}
-
- There are \pgfname{} keys to specify how this shape is drawn (to use these
- keys in \tikzname{} simply remove the \declare{|/pgf/|} path).
-
- \begin{key}{/pgf/chamfered rectangle angle=\meta{angle} (initially 45)}
- Sets the angle \emph{from the vertical} for the chamfer.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\begin{tikzpicture}
- \tikzset{every node/.style={chamfered rectangle, draw}}
- \node[chamfered rectangle angle=30] {abc};
- \node[chamfered rectangle angle=60] at (1.5,0) {123};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/chamfered rectangle xsep=\meta{length} (initially .666ex)}
- Sets the distance that the chamfer extends horizontally beyond the node
- contents (which includes the |inner sep|). If \meta{length} is large,
- such that the top and bottom chamfered edges would cross, then
- \meta{length} is ignored and the chamfered edges are drawn so that they
- meet in the middle.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\begin{tikzpicture}
- \tikzset{every node/.style={chamfered rectangle, draw}}
- \node[chamfered rectangle xsep=2pt] {def};
- \node[chamfered rectangle xsep=2cm] at (1.5,0) {456};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/chamfered rectangle ysep=\meta{length} (initially .666ex)}
- Sets the distance that the chamfer extends vertically beyond the node
- contents. If \meta{length} is large, such that the left and right
- chamfered edges would cross, then \meta{length} is ignored and the
- chamfered edges are drawn so that they meet in the middle.
- \end{key}
-
- \begin{key}{/pgf/chamfered rectangle sep=\meta{length} (initially .666ex)}
- Sets both the |xsep| and |ysep| simultaneously.
- \end{key}
-
- \begin{key}{/pgf/chamfered rectangle corners=\meta{list} (initially chamfer all)}
- Specifies which corners are chamfered. The corners are identified by
- their ``compass point'' directions (i.e.\ |north east|, |north west|,
- |south west|, and |south east|), and must be separated by commas (so if
- there is more than one corner in the list, it must be surrounded by
- braces). Any corners not mentioned in \meta{list} are automatically not
- chamfered. Two additional values |chamfer all| and |chamfer none|, are
- also permitted.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\begin{tikzpicture}
- \tikzset{every node/.style={chamfered rectangle, draw}}
- \node[chamfered rectangle corners=north west] {ghi};
- \node[chamfered rectangle corners={north east, south east}] at (1.5,0) {789};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- The anchors for this shape are shown below (anchor |60| is an example of a
- border angle.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\Huge
-\begin{tikzpicture}
- \node[name=s,shape=chamfered rectangle, chamfered rectangle sep=1cm,
- shape example, inner ysep=1cm, inner xsep=.75cm]
- {Chamfered Rectangle\vrule width1pt height2cm};
- \foreach \anchor/\placement in
- {text/right, center/above, 70/above,
- base/below, base east/left, base west/right,
- mid/right, mid east/above, mid west/above,
- north/above, south/below, east/above, west/above,
- before north east/above, north east/above, after north east/above,
- before north west/above, north west/above, after north west/above,
- before south west/below, south west/below, after south west/below,
- before south east/below, south east/below, after south east/below}
- \draw[shift=(s.\anchor)] plot[mark=x] coordinates{(0,0)}
- node[\placement] {\scriptsize\texttt{(s.\anchor)}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{shape}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-spy.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-spy.tex
deleted file mode 100644
index a85ff6a515..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-spy.tex
+++ /dev/null
@@ -1,463 +0,0 @@
-% 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{Spy Library: Magnifying Parts of Pictures}
-\label{section-library-spy}
-
-\begin{tikzlibrary}{spy}
- The package defines options for creating pictures in which some part of the
- picture is repeated in another area in a magnified way (as if you were
- looking through a spyglass, hence the name).
-\end{tikzlibrary}
-
-
-\subsection{Magnifying a Part of a Picture}
-
-The idea behind the |spy| library is to make it easy to create high-density
-pictures in which some important parts are repeated somewhere, but magnified as
-if you were looking through a spyglass:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
-\begin{tikzpicture}
- [spy using outlines={circle, magnification=4, size=2cm, connect spies}]
-
- \draw [help lines] (0,0) grid (3,2);
-
- \draw [decoration=Koch curve type 1]
- decorate { decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}};
-
- \spy [red] on (1.6,0.3)
- in node [left] at (3.5,-1.25);
-
- \spy [blue, size=1cm] on (1,1)
- in node [right] at (0,-1.25);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
-\begin{tikzpicture}[spy using overlays={size=12mm}]
- \draw [decoration=Koch snowflake]
- decorate { decorate{ decorate{ decorate{ (0,0) -- (2,0) }}}};
-
- \spy [green,magnification=3] on (0.6,0.1) in node at (-0.3,-1);
- \spy [blue,magnification=5] on (1,0.5) in node at (1,-1);
- \spy [red,magnification=10] on (1.6,0.1) in node at (2.3,-1);
-\end{tikzpicture}
-\end{codeexample}
-
-Note that this magnification uses what is called a \emph{canvas transformation}
-in this manual: Everything is magnified, including line width and text.
-
-In order for ``spying'' to work, the picture obviously has to be drawn several
-times: Once at its normal size and then again for each ``magnifying glass''.
-Several keys and commands work in concert to make this possible:
-%
-\begin{itemize}
- \item You need to make \tikzname\ aware of the fact that a picture (or just
- a scope) is to be magnified. This is done by adding the special key
- |spy scope| to a |{scope}| or |{tikzpicture}| (which is also just a
- scope). Some special keys like |spy using outlines| implicitly set the
- |spy scope|.
- \item Inside this scope you may then use the command |\spy|, which is only
- available inside such scopes (so there is no danger of you
- inadvertently using this command outside such a scope). This command
- has a special syntax and will (at some point) create two nodes: One
- node that shows the magnified picture (called the \emph{spy-in node})
- and another node showing which part of the original picture is
- magnified (called the \emph{spy-on} node). The spy-in node is, indeed,
- a normal node, so it can have any shape or border that you like and you
- can apply all of \tikzname's advanced features to it. The only
- difference compared to a normal node is that instead of some ``text''
- it contains a magnified version of the picture, clipped to the size of
- the node.
-
- The |\spy| command does not create the nodes immediately. Rather, the
- creation of these nodes is postponed till the end of the |spy scope| in
- which the |\spy| command is used. This is necessary since in order to
- repeat the whole scope inside the node containing the magnified
- version, the whole picture needs to be available when this node is
- created.
-\end{itemize}
-
-A basic question any library for ``magnifying things'' has to address is how
-you specify which part of the picture is to be magnified (the spy-on node) and
-where this magnified part is to be shown (the spy-in node). There are two
-possible ways:
-%
-\begin{enumerate}
- \item You specify the size and position of the spy-on node. Then the size
- of the spy-in node is determined by the size of the spy-on node and the
- magnification factor -- you can still decide where the spy-in node
- should be placed, but not its size.
- \item Alternatively, you specify the size and position of the spy-in node.
- Then, similarly to the first case, the size of the spy-on node is
- determined implicitly and you can only decide where the spy-on node
- should be placed, but not its size.
-\end{enumerate}
-
-The |spy| library uses the second method: You specify the size and position of
-the spy-in nodes, the sizes of the spy-on nodes are then computed
-automatically.
-
-
-\subsection{Spy Scopes}
-
-\begin{key}{/tikz/spy scope=\meta{options} (default \normalfont empty)}
- This option may be used with a |{scope}| or any environment that creates
- such a scope internally (like |{tikzpicture}|). It has the following
- effects:
- %
- \begin{itemize}
- \item It resets a number of graphic state parameters, including the
- color, line style, and others. This is necessary for technical
- reasons.
- \item It tells \tikzname\ that the content of the scope should be saved
- internally in a special box.
- \item It defines the command |\spy| so that it can be used inside the
- scope.
- \item At the end of the scope, the nodes belonging to the |\spy|
- commands used inside the scope are created.
- \item The \meta{options} are saved in an internal style. Each time
- |\spy| is used, these \meta{options} will be used.
- \item Three keys are defined that provide useful shortcuts:
- %
- \begin{key}{/tikz/size=\meta{dimension}}
- Inside a |spy scope|, this is a shortcut for |minimum size|.
- \end{key}
- %
- \begin{key}{/tikz/height=\meta{dimension}}
- Inside a |spy scope|, this is a shortcut for |minimum height|.
- \end{key}
- %
- \begin{key}{/tikz/width=\meta{dimension}}
- Inside a |spy scope|, this is a shortcut for |minimum width|.
- \end{key}
- \end{itemize}
- %
- It is permissible to nest |spy scopes|. In this case, all |\spy| commands
- inside the inner |spy scope| only have an effect on material inside the
- scope, whereas |\spy| commands outside the inner |spy scope| but inside the
- outer |spy scope| allow you to ``spy on the spy''.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
-\begin{tikzpicture}
- [spy using outlines={rectangle, red, magnification=5,
- size=1.5cm, connect spies}]
-
- \begin{scope}
- [spy using outlines={circle, blue,
- magnification=3, size=1.5cm, connect spies}]
- \draw [help lines] (0,0) grid (3,2);
-
- \draw [decoration=Koch curve type 1]
- decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
-
- \spy on (1.6,0.3) in node (zoom) [left] at (3.5,-1.25);
- \end{scope}
-
- \spy on (zoom.north west) in node [right] at (0,-1.25);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{The Spy Command}
-
-\begin{command}{\spy \opt{\oarg{options}} |on| \meta{coordinate} \texttt{in node} \meta{node options}|;|}
- This command can only be used inside a |spy scope|. Let us start with the
- syntax:
- %
- \begin{itemize}
- \item The |\spy| command is not a special case of |\path|. Rather, it
- has a small parser of its own.
- \item Following the optional \meta{options}, you must write |on|,
- followed by a coordinate. This coordinate will be the center of the
- area that is to be magnified.
- \item Following the \meta{coordinate}, you must write |in node|
- followed by some \meta{node options}. The syntax for these options
- is the same as for a normal |node| path command, such as |[left]|
- or |(foo) [red] at (bar)|. \emph{However}, \meta{node options} are
- \emph{not} followed by a curly brace. Rather, the \meta{node
- options} must directly be followed by a semicolon.
- \end{itemize}
- %
- The effect of this command is the following: The \meta{options},
- \meta{coordinate}, and \meta{node options} are stored internally till the
- end of the current |spy scope|. This means that, in particular, you can
- reference any node inside the |spy scope|, even if it is not yet defined
- when the |\spy| command is given. At the end of the current |spy scope|,
- two nodes are created, called the \emph{spy-in node} and the \emph{spy-on
- node}.
- %
- \begin{itemize}
- \item The \emph{spy-in node} is the node that contains a magnified part
- of the picture (the node \emph{in} which we see on what we spy).
- This node is, indeed, a normal \tikzname\ node, so you can use all
- standard options to style this node. In particular, you can specify
- a shape or a border color or a drop shadow or whatever. The only
- thing that is special about this node is that instead of containing
- some normal text, its ``text'' is the magnified picture.
-
- To be precise, the picture of the |spy scope| is scaled by a
- certain factor, specified by the |lens| or |magnification| options
- discussed below, and is shifted in such a way that the
- \meta{coordinate} lies at the center of the spy-on node.
- \item The \emph{spy-on node} is a node that is centered on the
- \meta{coordinate} and whose size reflects exactly the area shown
- inside the spy-in node (the node containing \emph{on} what we spy).
- \end{itemize}
-
- Let us now go over what happens in detail when the two nodes are
- created:
- %
- \begin{enumerate}
- \item A scope is started. Two sets of options are used with this scope:
- First, the options passed to the enclosing |spy scope| and then the
- \meta{options} (which will, thus, overrule the options of the
- |spy scope|).
- \item Then, the spy-on node is created. However, we will first discuss
- the spy-in node.
- \item The spy-in node is created after the spy-on node (and, hence,
- will cover the spy-on node in case they overlap). When this node is
- created, the \meta{node options} are used in addition to the effect
- caused by the \meta{options} and the options of the |{spy scope}|.
- Additionally, the following style is used:
- %
- \begin{stylekey}{/tikz/every spy in node}
- This style is used with every spy-in node.
- \end{stylekey}
- %
- The position of the node (the |at| option) is set to the
- \meta{coordinate} by default, so that it will cover the
- to-be-magnified area. You can change this by providing the |at|
- option yourself:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
-\begin{tikzpicture}
- [spy using outlines={circle, magnification=3, size=1cm}]
-
- \draw [decoration=Koch curve type 1]
- decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
-
- \spy [red] on (1.6,0.3) in node;
- \spy [blue] on (1,1) in node at (1,-1);
-\end{tikzpicture}
-\end{codeexample}
- %
- No ``text'' can be specified for the node. Rather, the ``text''
- shown inside this node is the picture of the current |spy scope|,
- but canvas-transformed according to the following key:
- %
- \begin{key}{/tikz/lens=\meta{options}}
- The \meta{options} should contain transformation commands like
- |scale| or |rotate|. These transformations are applied to the
- picture when it is shown inside the spy-on node.
- \end{key}
- %
- Since the most common transformation is undoubtedly a simple
- scaling, there is a special style for this:
- %
- \begin{key}{/tikz/magnification=\meta{number}}
- This has the same effect as saying
- |lens={scale=|\meta{number}|}|.
- \end{key}
- %
- Now, usually the size of a node is determined in such a way that it
- ``fits'' around the text of the node. For a spy-on node this is not
- a good approach since the ``text'' of this node would contain ``the
- whole picture''. Because of this, \tikzname\ acts as if the
- ``text'' of the node has zero size. You must then use keys like
- |minimum size| to cause the node to have a certain size. Note that
- the key |size| is an abbreviation for |minimum size| inside a spy
- scope.
-
- You can name the spy-on node in the usual ways. Additionally, the
- node is (also) always named |tikzspyinnode|. Following the spy
- scope, you can use this node like any other node:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
-\begin{tikzpicture}
- \begin{scope}
- [spy using outlines={circle, magnification=3, size=2cm, connect spies}]
-
- \draw [decoration=Koch curve type 1]
- decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
-
- \spy [red] on (1.6,0.3) in node (a) [left] at (3.5,-1.25);
-
- \spy [blue, size=1cm] on (1,1) in node (b) [right] at (0,-1.25);
- \end{scope}
- \draw [ultra thick, green!50!black] (b) -- (a.north west);
-\end{tikzpicture}
-\end{codeexample}
- %
- \item Once both nodes have been created, the current value of the
- following key is used to connect them:
- %
- \begin{key}{/tikz/spy connection path=\meta{code} (initially \normalfont empty)}
- The \meta{code} is executed after the spy-on and spy-in nodes
- have just been created. Inside this \meta{code}, the two nodes
- can be accessed as |tikzspyinnode| and |tikzspyonnode|. For
- example, the key |connect spies| sets this command to
- %
-\begin{codeexample}[code only]
-\draw[thin] (tikzspyonnode) -- (tikzspyinnode);
-\end{codeexample}
- \end{key}
- \end{enumerate}
- %
- Returning to the creation of the spy-in node: This node is centered on
- \meta{coordinate} (more precisely, its anchor is set to |center| and the
- |at| option is set to \meta{coordinate}). Its size and shape are initially
- determined in the same way as the size and shape of the spy-on node
- (unless, of course, you explicitly provide a different shape for, say, the
- spy-on node locally, which is not really a good idea). Then, additionally,
- the \emph{inverted} transformation done by the |lens| option is applied,
- resulting in a node whose size and shape exactly corresponds to the area in
- the picture that is shown in the spy-on node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
-\begin{tikzpicture}
- [spy using outlines={lens={scale=3,rotate=20}, size=2cm, connect spies}]
-
- \draw [decoration=Koch curve type 1]
- decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
-
- \spy [red] on (1.6,0.3) in node at (2.5,-1.25);
-\end{tikzpicture}
-\end{codeexample}
-
- Like for the spy-in node, a style can be used to format the spy-on node:
- %
- \begin{stylekey}{/tikz/every spy on node}
- This style is used with every spy-on node.
- \end{stylekey}
- %
- The spy-on node is named |tikzspyonnode| (but, as always, this node is only
- available after the spy scope). If you have multiple spy-on nodes and you
- would like to access all of them, you need to use the |name| key inside the
- |every spy on node| style.
-
- The |inner sep| and |outer sep| of both spy-in and spy-on nodes are set to
- |0pt|.
-\end{command}
-
-
-\subsection{Predefined Spy Styles}
-
-There are some predefined styles that make using the |spy| library easier. The
-following two styles can be used instead of |spy scope|, they pass their
-\meta{options} directly to |spy scope|. They additionally set up the graphic
-styles to be used for the spy-in nodes and the spy-on nodes in some special
-way.
-
-\begin{key}{/tikz/spy using outlines=\meta{options} (default \normalfont empty)}
- This key creates a |spy scope| in which the spy-in node is drawn, but not
- filled, using a thick line; and the spy-on node is drawn, but not filled,
- using a very thin line.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
-\begin{tikzpicture}
- [spy using outlines={circle, magnification=3, size=1cm, connect spies}]
-
- \draw [decoration=Koch curve type 1]
- decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
-
- \spy [red] on (1.6,0.3) in node at (3,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/spy using overlays=\meta{options} (default \normalfont empty)}
- This key creates a |spy scope| in which both the spy-in and spy-on nodes
- are filled, but with the fill opacity set to 20\%.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
-\begin{tikzpicture}
- [spy using overlays={circle, magnification=3, size=1cm, connect spies}]
-
- \draw [decoration=Koch curve type 1]
- decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
-
- \spy [green] on (1.6,0.3) in node at (3,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-The following style is useful for connecting the spy-in and the spy-on nodes:
-
-\begin{key}{/tikz/connect spies}
- Causes the spy-in and the spy-on nodes to be connected by a thin line.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,spy}}]
-\begin{tikzpicture}
- [spy using overlays={circle, magnification=3, size=1cm}]
-
- \draw [decoration=Koch curve type 2]
- decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
-
- \spy [green] on (1.6,0.1) in node at (3,1);
- \spy [red,connect spies] on (0.5,0.4) in node at (1,1.5);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Examples}
-
-Usually, the spy-in node and the spy-on node should have the same shape.
-However, you might also wish to use the |circle| shape for the spy-on node and
-the |magnifying glass| shape for the spy-in node:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,shadows,shapes.symbols,spy}}]
-\tikzset{spy using mag glass/.style={
- spy scope={
- every spy on node/.style={
- circle,
- fill, fill opacity=0.2, text opacity=1},
- every spy in node/.style={
- magnifying glass, circular drop shadow,
- fill=white, draw, ultra thick, cap=round},
- #1
- }}}
-\begin{tikzpicture}[spy using mag glass={magnification=3, size=1cm}]
- \draw [decoration=Koch curve type 2]
- decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
-
- \spy [green!50!black] on (1.6,0.1) in node at (2.5,-0.5);
-\end{tikzpicture}
-\end{codeexample}
-
-With the magnifying glass, you can also put it ``on top'' of the picture
-itself:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals,shadows,shapes.symbols,spy}}]
-\begin{tikzpicture}
- [spy scope={magnification=4, size=1cm},
- every spy in node/.style={
- magnifying glass, circular drop shadow,
- fill=white, draw, ultra thick, cap=round}]
-
- \draw [decoration=Koch curve type 2]
- decorate{ decorate{ decorate{ (0,0) -- (2,0) }}};
-
- \spy on (1.6,0.1) in node;
-\end{tikzpicture}
-\end{codeexample}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-svg-path.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-svg-path.tex
deleted file mode 100644
index ec45ca4435..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-svg-path.tex
+++ /dev/null
@@ -1,58 +0,0 @@
-% 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{SVG-Path Library}
-\label{section-library-svg-path}
-
-\begin{pgflibrary}{svg.path}
- This library defines a command that allows you to specify a path using the
- \textsc{svg}-syntax.
-\end{pgflibrary}
-
-\begin{command}{\pgfpathsvg\marg{path}}
- This command extends the current path by a \meta{path} given in the
- \textsc{svg}-path-data syntax. This syntax is described in detail in
- Section~8.3 of the \textsc{svg}-specification, Version~1.1.
-
- In principle, the complete syntax is supported and the library just
- provides a parser and a mapping to basic layer commands. For instance,
- |M 0 10| is mapped to |\pgfpathmoveto{\pgfpoint{0pt}{10pt}}|. There are,
- however, a few things to be aware of:
- %
- \begin{itemize}
- \item The computation underlying the arc commands |A| and |a| are not
- numerically stable, which may result in quite imprecise arcs.
- Bézier curves, both quadratic and cubic, are not affected, neither
- are arcs spanning degrees that are multiples of $90^{\circ}$.
- \item The dimensionless units of \textsc{svg} are always interpreted as
- points (|pt|). This is a problem with paths like |M 20000 0|, which
- will raise an error message since \TeX\ cannot handle dimensions
- larger than about 16\,000 points.
- \item All coordinate and canvas transformations apply to the path in
- the usual fashion.
- \item The |\pgfpathsvg| command can be freely intermixed with other
- path commands.
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usepgflibrary{svg.path}}]
-\begin{pgfpicture}
- \pgfpathsvg{M 0 0 l 20 0 0 20 -20 0 q 10 0 10 10
- t 10 10 10 10 h -50 z}
- \pgfusepath{stroke}
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-through.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-through.tex
deleted file mode 100644
index 55a4f934ea..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-through.tex
+++ /dev/null
@@ -1,43 +0,0 @@
-% 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{Through Library}
-\label{section-through-library}
-
-\begin{tikzlibrary}{through}
- This library defines keys for creating shapes that go through given points.
-\end{tikzlibrary}
-
-\begin{key}{/tikz/circle through=\meta{coordinate}}
- When this key is given as an option to a node, the following happens:
- %
- \begin{enumerate}
- \item The |inner sep| and the |outer sep| are set to zero.
- \item The shape is set to |circle|.
- \item The |minimum size| is set such that the circle around the center
- of the node (which is specified using |at|), goes through
- \meta{coordinate}.
- \end{enumerate}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{through}}]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \node (a) at (2,1.5) {$a$};
- \node [draw] at (1,1) [circle through={(a)}] {$c$};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-trees.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-trees.tex
deleted file mode 100644
index ccb5eb53dc..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-trees.tex
+++ /dev/null
@@ -1,196 +0,0 @@
-% 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{Tree Library}
-\label{section-tree-library}
-
-\begin{tikzlibrary}{trees}
- This packages defines styles to be used when drawing trees.
-\end{tikzlibrary}
-
-
-\subsection{Growth Functions}
-
-The package |trees| defines two new growth functions. They are installed using
-the following options:
-
-\begin{key}{/tikz/grow via three points=\texttt{one child at (}\meta{x}
- \texttt{) and two children at (}\meta{y}\texttt{) and (}\meta{z}|)|%
-}
- This option installs a growth function that works as follows: If a parent
- node has just one child, this child is placed at \meta{x}. If the parent
- node has two children, these are placed at \meta{y} and \meta{z}. If the
- parent node has more than two children, the children are placed at points
- that are linearly extrapolated from the three points \meta{x}, \meta{y},
- and \meta{z}. In detail, the position is $x + \frac{n-1}{2}(y-x) +
- (c-1)(z-y)$, where $n$ is the number of children and $c$ is the number of
- the current child (starting with~$1$).
-
- The net effect of all this is that if you have a certain ``linear
- arrangement'' in mind and use this option to specify the placement of a
- single child and of two children, then any number of children will be
- placed correctly.
-
- Here are some arrangements based on this growth function. We start with a
- simple ``above'' arrangement:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{trees}}]
-\begin{tikzpicture}[grow via three points={%
- one child at (0,1) and two children at (-.5,1) and (.5,1)}]
- \node at (0,0) {one} child;
- \node at (0,-1.5) {two} child child;
- \node at (0,-3) {three} child child child;
- \node at (0,-4.5) {four} child child child child;
-\end{tikzpicture}
-\end{codeexample}
-
- The next arrangement places children above, but ``grows only to the
- right''.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{trees}}]
-\begin{tikzpicture}[grow via three points={%
- one child at (0,1) and two children at (0,1) and (1,1)}]
- \node at (0,0) {one} child;
- \node at (0,-1.5) {two} child child;
- \node at (0,-3) {three} child child child;
- \node at (0,-4.5) {four} child child child child;
-\end{tikzpicture}
-\end{codeexample}
-
- In the final arrangement, the children are placed along a line going down
- and right.
-\begin{codeexample}[preamble={\usetikzlibrary{trees}}]
-\begin{tikzpicture}[grow via three points={%
- one child at (-1,-.5) and two children at (-1,-.5) and (0,-.75)}]
- \node at (0,0) {one} child;
- \node at (0,-1.5) {two} child child;
- \node at (0,-3) {three} child child child;
- \node at (0,-4.5) {four} child child child child;
-\end{tikzpicture}
-\end{codeexample}
-
- These examples should make it clear how you can create new styles to
- arrange your children along a line.
-\end{key}
-
-\begin{key}{/tikz/grow cyclic}
- This style causes the children to be arranged ``on a circle''. For this,
- the children are placed at distance |\tikzleveldistance| from the parent
- node, but not on a straight line, but on points on a circle. Instead of a
- sibling distance, there is a |sibling angle| that denotes the angle between
- two given children.
- %
- \begin{key}{/tikz/sibling angle=\meta{angle}}
- Sets the angle between siblings in the |grow cyclic| style.
- \end{key}
- %
- Note that this function will rotate the coordinate system of the children
- to ensure that the grandchildren will grow in the right direction.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{trees}}]
-\begin{tikzpicture}
- [grow cyclic,
- level 1/.style={level distance=8mm,sibling angle=60},
- level 2/.style={level distance=4mm,sibling angle=45},
- level 3/.style={level distance=2mm,sibling angle=30}]
- \coordinate [rotate=-90] % going down
- child foreach \x in {1,2,3}
- {child foreach \x in {1,2,3}
- {child foreach \x in {1,2,3}}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/clockwise from=\meta{angle}}
- This option also causes children to be arranged on a circle. However, the
- rule for placing children is simpler than with the |grow cyclic| style: The
- first child is placed at \meta{angle} at a distance of
- |\tikzleveldistance|. The second child is placed at the same distance from
- the parent, but at angle \meta{angle}${}-{}$|\tikzsiblingangle|. The third
- child is displaced by another |\tikzsiblingangle| in a clockwise fashion,
- and so on.
-
- Note that this function will not rotate the coordinate system.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{trees}}]
-\begin{tikzpicture}
- \node {root}
- [clockwise from=30,sibling angle=30]
- child {node {$30$}}
- child {node {$0$}}
- child {node {$-30$}}
- child {node {$-60$}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/counterclockwise from=\meta{angle}}
- Works the same way as |clockwise from|, but sibling angles are added
- instead of subtracted.
-\end{key}
-
-
-\subsection{Edges From Parent}
-
-The following styles can be used to modify how the edges from parents are
-drawn:
-
-\begin{stylekey}{/tikz/edge from parent fork down}
- This style will draw a line from the parent downwards (for half the level
- distance) and then on to the child using only horizontal and vertical
- lines.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{trees}}]
-\begin{tikzpicture}
- \node {root}
- [edge from parent fork down]
- child {node {left}}
- child {node {right}
- child[child anchor=north east] {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/edge from parent fork right}
- This style behaves similarly, only it will first draw its edge to the
- right.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{trees}}]
-\begin{tikzpicture}
- \node {root}
- [edge from parent fork right,grow=right]
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/edge from parent fork left}
- Behaves similarly to the previous styles.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/edge from parent fork up}
- Behaves similarly to the previous styles.
-\end{stylekey}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-turtle.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-turtle.tex
deleted file mode 100644
index cea9271069..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-turtle.tex
+++ /dev/null
@@ -1,117 +0,0 @@
-% Copyright 2019 by Mark Wibrow
-%
-% 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{Turtle Graphics Library}
-\label{section-library-tutrle}
-
-\begin{tikzlibrary}{turtle}
- This little library defines some keys to create simple turtle graphics in
- the tradition of the Logo programming language. These commands are mostly
- for fun, but they can also be used for more ``serious'' business.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{turtle}}]
-\tikz[turtle/distance=2mm]
- \draw [turtle={home,forward,right,forward,left,forward,left,forward}];
-\end{codeexample}
- %
-\end{tikzlibrary}
-
-Even though the |turtle| keys looks like an option, it uses the |insert path|
-option internally to produce a path.
-
-The basic drawing model behind the turtle graphics is very simple: There is a
-(virtual) \emph{turtle} that crawls around the page, thereby extending the
-path. The turtle always heads in a certain direction. When you move the turtle
-forward, you extend the path in that direction; turning the turtle just changes
-the direction, it does not cause anything to be drawn.
-
-The turtle always moves relative to the last current point of the path and you
-can mix normal path commands with turtle commands. However, the direction of
-the turtle is managed independently of other path commands.
-
-\begin{key}{/tikz/turtle=\meta{keys}}
- This key executes the \meta{keys} with the current key path set to
- |/tikz/turtle|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{turtle}}]
-\tikz[turtle/distance=2mm]
- \draw [turtle={home,fd,rt,fd,lt,fd,lt,fd}];
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/turtle/home}
- Places the turtle at the origin and lets it head upward.
-\end{key}
-
-\begin{key}{/tikz/turtle/forward=\meta{distance} (default \normalfont see text)}
- Makes the turtle move forward by the given \meta{distance}. If no
- \meta{distance} is specified, the current value of the following key is
- used:
- %
- \begin{key}{/tikz/turtle/distance=\meta{distance} (initially 1cm)}
- The default distance by which the turtle advances.
- \end{key}
- %
- ``Moving forward the turtle'' actually means that, relative to the current
- last point on the path, a point at the given \meta{distance} in the
- direction the turtle is currently heading is computed. Then, the operation
- |to[turtle/how]| is used to extend the path to this point.
- %
- \begin{stylekey}{/tikz/turtle/how (initially \normalfont empty)}
- This style can set up the |to path| used by turtles. By setting this
- style you can change the to-path:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{turtle}}]
-\tikz \draw [turtle={how/.style={bend left},home,forward,right,forward}];
-\end{codeexample}
- \end{stylekey}
-\end{key}
-
-\begin{key}{/tikz/turtle/fd}
- An abbreviation for the |forward| key.
-\end{key}
-
-\begin{key}{/tikz/turtle/back=\meta{distance} (default \normalfont see text)}
- This has the same effect as a |turtle/forward| for the negated
- \meta{distance} value.
-\end{key}
-
-\begin{key}{/tikz/turtle/bk}
- An abbreviation for the |back| key.
-\end{key}
-
-\begin{key}{/tikz/turtle/left=\meta{angle} (default 90)}
- Turns the turtle left by the given angle.
-\end{key}
-
-\begin{key}{/tikz/turtle/lt}
- An abbreviation for the |left| key.
-\end{key}
-
-\begin{key}{/tikz/turtle/right=\meta{angle} (default 90)}
- Turns the turtle right by the given angle.
-\end{key}
-
-\begin{key}{/tikz/turtle/rt}
- An abbreviation for the |right| key.
-\end{key}
-
-Turtle graphics are especially nice in conjunction with the |\foreach|
-statement:
-
-\begin{codeexample}[preamble={\usetikzlibrary{turtle}}]
-\tikz \filldraw [thick,blue,fill=blue!20]
- [turtle=home]
- \foreach \i in {1,...,5}
- {
- [turtle={forward,right=144}]
- };
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-views.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-views.tex
deleted file mode 100644
index a080042808..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-library-views.tex
+++ /dev/null
@@ -1,127 +0,0 @@
-% 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{Views Library}
-\label{section-library-views}
-
-\begin{tikzlibrary}{views}
- This library is used for creating \emph{views}, which are transformations
- of a part of a picture so that this part ``fits'' into a ``viewbox''.
- Mostly, views are useful in conjunction with animations.
-\end{tikzlibrary}
-
-A \emph{view} is essentially a ``window'' through which you see a graphic. To
-establish a view, you specify a rectangle -- which is the window -- and another
-rectangle surrounding the to-be-viewed graphic. The graphic will then be
-rescaled and shifted in such a way that the to-be-viewed rectangle matches the
-view's rectangle as well as possible. Note that establishing a view causes a
-\emph{canvas} transformation to be installed, not a coordinate transformation.
-
-View boxes are only seldom needed in normal graphics; you may prefer to use
-coordinate transformations or the |spy| library. Their main application is with
-animations since you can \emph{animate} the to-be-viewed rectangle. This makes
-it easy to create animations in which you zoom in, zoom out, and pan a graphic.
-
-\begin{key}{/tikz/meet=\meta{to-be-viewed corner}
- \opt{|rectangle|} \meta{to-be-viewed corner} \opt{|at|
- \meta{window corner} |rectangle| \meta{window corner}}%
-}
- Use this key with a scope to establish a view for the scope. In the
- argument to the |meet| key, both |rectangle| texts are optional. Also,
- everything following |at| is optional; when it is missing, the \meta{window
- corner}s are assumed to be the same as the \meta{to-be-viewed corner}s. The
- latter are two corners of a rectangle that should be transformed in such a
- way that it fits inside the rectangle described by the two window corners.
-
- More precisely, at the beginning of the scope a canvas transformation is
- installed that scales and translates the canvas is such a way that
- %
- \begin{enumerate}
- \item the center of the to-be-viewed rectangle lies at the center of
- the window rectangle and
- \item the to-be-viewed rectangle has maximum size that it still fits
- inside the window rectangle.
- \end{enumerate}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{views}}]
-\tikz {
- \draw [red, very thick] (0,0) rectangle (20mm,20mm);
- \begin{scope}[meet = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}]
- \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
- \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi};
- \end{scope} }
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{views}}]
-\tikz {
- \draw [red, very thick] (0,0) rectangle (20mm,20mm);
- \begin{scope}[slice = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}]
- \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
- \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi};
- \end{scope} }
-\end{codeexample}
-
- As mentioned earlier, the main use of views is in conjunction with
- animations. In order to animate a view, you specify the scope containing
- the |meet| command as the target object and then animate its |:view|
- attribute:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{animations,views}}]
-\tikz [animate = {
- my scope:view = {
- begin on = { click, of next = here },
- 0s = "{(0.5,0.5) (2.5,1.5)}",
- 2s = "{(0.5,0) (1.5,2)}", forever
- }}] {
- \draw [red, fill=red!20, very thick, name=here]
- (0,0) rectangle (20mm,20mm);
- \begin{scope}[name = my scope,
- meet = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}]
- \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
- \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi};
- \end{scope} }
-\end{codeexample}
- %
- You can, of course, also specify the animation using the |animate myself:|
- key when you specify the animation inside the scope:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{animations,views}}]
-\tikz [animate = {
- my scope:view = {
- }}] {
- \draw [red, fill=red!20, very thick, name=here]
- (0,0) rectangle (20mm,20mm);
- \begin{scope}[animate = { myself: = { :view = {
- begin on = { click, of = here },
- 0s = "{(0.5,0.5) (2.5,1.5)}",
- 2s = "{(0.5,0) (1.5,2)}", forever }}},
- slice = {(0.5,0.5) (2.5,1.5) at (0,0) (2,2)}]
- \draw [blue, very thick] (5mm,5mm) rectangle (25mm,15mm);
- \draw [thick] (1,1) circle [x radius=5mm, y radius=10mm] node {Hi};
- \end{scope} }
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/view}
- This is an alias for |/tikz/meet|.
-\end{key}
-
-\begin{key}{/tikz/slice=\meta{to-be-viewed corner}
- \opt{|rectangle|} \meta{to-be-viewed corner} \opt{|at|
- \meta{window corner} |rectangle| \meta{window corner}}%
-}
- This key works exactly like |meet|, only the second rule is changed:
- %
- \begin{enumerate}
- \item[$2'$.] the to-be-viewed rectangle has minimal size that it
- encompasses all of the window rectangle.
- \end{enumerate}
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-license.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-license.tex
deleted file mode 100644
index ca56481b8d..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-license.tex
+++ /dev/null
@@ -1,1229 +0,0 @@
-% Copyright 2018 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{Licenses and Copyright}
-\label{section-license}
-
-\subsection{Which License Applies?}
-
-Different parts of the \pgfname\ package are distributed under different
-licenses:
-%
-\begin{enumerate}
- \item The \emph{code} of the package is dual-license. This means that you
- can decide which license you wish to use when using the \pgfname\
- package. The two options are:
- %
- \begin{enumerate}
- \item You can use the \textsc{gnu} Public License, version 2.
- \item You can use the \LaTeX\ Project Public License, version
- 1.3c.
- \end{enumerate}
- \item The \emph{documentation} of the package is also dual-license.
- Again, you can choose between two options:
- %
- \begin{enumerate}
- \item You can use the \textsc{gnu} Free Documentation License,
- version 1.2.
- \item You can use the \LaTeX\ Project Public License, version
- 1.3c.
- \end{enumerate}
-\end{enumerate}
-
-The ``documentation of the package'' refers to all files in the subdirectory
-|doc| of the |pgf| package. A detailed listing can be found in the file
-|doc/generic/pgf/licenses/manifest-documentation.txt|. All files in other
-directories are part of the ``code of the package''. A detailed listing can be
-found in the file |doc/generic/pgf/licenses/manifest-code.txt|.
-
-In the rest of this section, the licenses are presented. The following text is
-copyrighted, see the plain text versions of these licenses in the directory
-|doc/generic/pgf/licenses| for details.
-
-The example picture used in this manual, the Brave \textsc{gnu} World logo, is
-taken from the Brave \textsc{gnu} World homepage, where it is copyrighted as
-follows: ``Copyright (C) 1999, 2000, 2001, 2002, 2003, 2004 Georg C.~F.\ Greve.
-Permission is granted to make and distribute verbatim copies of this transcript
-as long as the copyright and this permission notice appear.''
-
-
-\subsection{The GNU Public License, Version 2}
-
-\subsubsection{Preamble}
-
-The licenses for most software are designed to take away your freedom to share
-and change it. By contrast, the \textsc{gnu} General Public License is
-intended to guarantee your freedom to share and change free software---to make
-sure the software is free for all its users. This General Public License
-applies to most of the Free Software Foundation's software and to any other
-program whose authors commit to using it. (Some other Free Software Foundation
-software is covered by the \textsc{gnu} Library General Public License
-instead.) You can apply it to your programs, too.
-
-When we speak of free software, we are referring to freedom, not price. Our
-General Public Licenses are designed to make sure that you have the freedom to
-distribute copies of free software (and charge for this service if you wish),
-that you receive source code or can get it if you want it, that you can change
-the software or use pieces of it in new free programs; and that you know you
-can do these things.
-
-To protect your rights, we need to make restrictions that forbid anyone to deny
-you these rights or to ask you to surrender the rights. These restrictions
-translate to certain responsibilities for you if you distribute copies of the
-software, or if you modify it.
-
-For example, if you distribute copies of such a program, whether gratis or for
-a fee, you must give the recipients all the rights that you have. You must
-make sure that they, too, receive or can get the source code. And you must
-show them these terms so they know their rights.
-
-We protect your rights with two steps: (1) copyright the software, and (2)
-offer you this license which gives you legal permission to copy, distribute
-and/or modify the software.
-
-Also, for each author's protection and ours, we want to make certain that
-everyone understands that there is no warranty for this free software. If the
-software is modified by someone else and passed on, we want its recipients to
-know that what they have is not the original, so that any problems introduced
-by others will not reflect on the original authors' reputations.
-
-Finally, any free program is threatened constantly by software patents. We wish
-to avoid the danger that redistributors of a free program will individually
-obtain patent licenses, in effect making the program proprietary. To prevent
-this, we have made it clear that any patent must be licensed for everyone's
-free use or not licensed at all.
-
-The precise terms and conditions for copying, distribution and modification
-follow.
-
-
-\subsubsection{Terms and Conditions For Copying, Distribution and Modification}
-
-\begin{enumerate}
- \addtocounter{enumi}{-1}
- \item This License applies to any program or other work which contains a
- notice placed by the copyright holder saying it may be distributed
- under the terms of this General Public License. The ``Program'',
- below, refers to any such program or work, and a ``work based on the
- Program'' means either the Program or any derivative work under
- copyright law: that is to say, a work containing the Program or a
- portion of it, either verbatim or with modifications and/or
- translated into another language. (Hereinafter, translation is
- included without limitation in the term ``modification''.) Each
- licensee is addressed as ``you''.
-
- Activities other than copying, distribution and modification are not
- covered by this License; they are outside its scope. The act of
- running the Program is not restricted, and the output from the
- Program is covered only if its contents constitute a work based on
- the Program (independent of having been made by running the Program).
- Whether that is true depends on what the Program does.
- \item You may copy and distribute verbatim copies of the Program's source
- code as you receive it, in any medium, provided that you
- conspicuously and appropriately publish on each copy an appropriate
- copyright notice and disclaimer of warranty; keep intact all the
- notices that refer to this License and to the absence of any
- warranty; and give any other recipients of the Program a copy of this
- License along with the Program.
-
- You may charge a fee for the physical act of transferring a copy, and
- you may at your option offer warranty protection in exchange for a
- fee.
- \item You may modify your copy or copies of the Program or any portion of
- it, thus forming a work based on the Program, and copy and distribute
- such modifications or work under the terms of Section 1 above,
- provided that you also meet all of these conditions:
- %
- \begin{enumerate}
- \item You must cause the modified files to carry prominent
- notices stating that you changed the files and the date of
- any change.
- \item You must cause any work that you distribute or publish,
- that in whole or in part contains or is derived from the
- Program or any part thereof, to be licensed as a whole at
- no charge to all third parties under the terms of this
- License.
- \item If the modified program normally reads commands
- interactively when run, you must cause it, when started
- running for such interactive use in the most ordinary way,
- to print or display an announcement including an
- appropriate copyright notice and a notice that there is no
- warranty (or else, saying that you provide a warranty) and
- that users may redistribute the program under these
- conditions, and telling the user how to view a copy of this
- License. (Exception: if the Program itself is interactive
- but does not normally print such an announcement, your work
- based on the Program is not required to print an
- announcement.)
- \end{enumerate}
- %
- These requirements apply to the modified work as a whole. If
- identifiable sections of that work are not derived from the Program,
- and can be reasonably considered independent and separate works in
- themselves, then this License, and its terms, do not apply to those
- sections when you distribute them as separate works. But when you
- distribute the same sections as part of a whole which is a work based
- on the Program, the distribution of the whole must be on the terms of
- this License, whose permissions for other licensees extend to the
- entire whole, and thus to each and every part regardless of who wrote
- it.
-
- Thus, it is not the intent of this section to claim rights or contest
- your rights to work written entirely by you; rather, the intent is to
- exercise the right to control the distribution of derivative or
- collective works based on the Program.
-
- In addition, mere aggregation of another work not based on the
- Program with the Program (or with a work based on the Program) on a
- volume of a storage or distribution medium does not bring the other
- work under the scope of this License.
- \item You may copy and distribute the Program (or a work based on it,
- under Section~2) in object code or executable form under the terms of
- Sections~1 and 2 above provided that you also do one of the
- following:
- %
- \begin{enumerate}
- \item Accompany it with the complete corresponding
- machine-readable source code, which must be distributed
- under the terms of Sections~1 and 2 above on a medium
- customarily used for software interchange; or,
- \item Accompany it with a written offer, valid for at least
- three years, to give any third party, for a charge no more
- than your cost of physically performing source
- distribution, a complete machine-readable copy of the
- corresponding source code, to be distributed under the
- terms of Sections~1 and 2 above on a medium customarily
- used for software interchange; or,
- \item Accompany it with the information you received as to the
- offer to distribute corresponding source code. (This
- alternative is allowed only for noncommercial distribution
- and only if you received the program in object code or
- executable form with such an offer, in accord with
- Subsubsection~b above.)
- \end{enumerate}
- %
- The source code for a work means the preferred form of the work for
- making modifications to it. For an executable work, complete source
- code means all the source code for all modules it contains, plus any
- associated interface definition files, plus the scripts used to
- control compilation and installation of the executable. However, as
- a special exception, the source code distributed need not include
- anything that is normally distributed (in either source or binary
- form) with the major components (compiler, kernel, and so on) of the
- operating system on which the executable runs, unless that component
- itself accompanies the executable.
-
- If distribution of executable or object code is made by offering
- access to copy from a designated place, then offering equivalent
- access to copy the source code from the same place counts as
- distribution of the source code, even though third parties are not
- compelled to copy the source along with the object code.
- \item You may not copy, modify, sublicense, or distribute the Program
- except as expressly provided under this License. Any attempt
- otherwise to copy, modify, sublicense or distribute the Program is
- void, and will automatically terminate your rights under this
- License. However, parties who have received copies, or rights, from
- you under this License will not have their licenses terminated so
- long as such parties remain in full compliance.
- \item You are not required to accept this License, since you have not
- signed it. However, nothing else grants you permission to modify or
- distribute the Program or its derivative works. These actions are
- prohibited by law if you do not accept this License. Therefore, by
- modifying or distributing the Program (or any work based on the
- Program), you indicate your acceptance of this License to do so, and
- all its terms and conditions for copying, distributing or modifying
- the Program or works based on it.
- \item Each time you redistribute the Program (or any work based on the
- Program), the recipient automatically receives a license from the
- original licensor to copy, distribute or modify the Program subject
- to these terms and conditions. You may not impose any further
- restrictions on the recipients' exercise of the rights granted
- herein. You are not responsible for enforcing compliance by third
- parties to this License.
- \item If, as a consequence of a court judgment or allegation of patent
- infringement or for any other reason (not limited to patent issues),
- conditions are imposed on you (whether by court order, agreement or
- otherwise) that contradict the conditions of this License, they do
- not excuse you from the conditions of this License. If you cannot
- distribute so as to satisfy simultaneously your obligations under
- this License and any other pertinent obligations, then as a
- consequence you may not distribute the Program at all. For example,
- if a patent license would not permit royalty-free redistribution of
- the Program by all those who receive copies directly or indirectly
- through you, then the only way you could satisfy both it and this
- License would be to refrain entirely from distribution of the
- Program.
-
- If any portion of this section is held invalid or unenforceable under
- any particular circumstance, the balance of the section is intended
- to apply and the section as a whole is intended to apply in other
- circumstances.
-
- It is not the purpose of this section to induce you to infringe any
- patents or other property right claims or to contest validity of any
- such claims; this section has the sole purpose of protecting the
- integrity of the free software distribution system, which is
- implemented by public license practices. Many people have made
- generous contributions to the wide range of software distributed
- through that system in reliance on consistent application of that
- system; it is up to the author/donor to decide if he or she is
- willing to distribute software through any other system and a
- licensee cannot impose that choice.
-
- This section is intended to make thoroughly clear what is believed to
- be a consequence of the rest of this License.
- \item If the distribution and/or use of the Program is restricted in
- certain countries either by patents or by copyrighted interfaces, the
- original copyright holder who places the Program under this License
- may add an explicit geographical distribution limitation excluding
- those countries, so that distribution is permitted only in or among
- countries not thus excluded. In such case, this License incorporates
- the limitation as if written in the body of this License.
- \item The Free Software Foundation may publish revised and/or new
- versions of the General Public License from time to time. Such new
- versions will be similar in spirit to the present version, but may
- differ in detail to address new problems or concerns.
-
- Each version is given a distinguishing version number. If the
- Program specifies a version number of this License which applies to
- it and ``any later version'', you have the option of following the
- terms and conditions either of that version or of any later version
- published by the Free Software Foundation. If the Program does not
- specify a version number of this License, you may choose any version
- ever published by the Free Software Foundation.
- \item If you wish to incorporate parts of the Program into other free
- programs whose distribution conditions are different, write to the
- author to ask for permission. For software which is copyrighted by
- the Free Software Foundation, write to the Free Software Foundation;
- we sometimes make exceptions for this. Our decision will be guided
- by the two goals of preserving the free status of all derivatives of
- our free software and of promoting the sharing and reuse of software
- generally.
-\end{enumerate}
-
-
-\subsubsection{No Warranty}
-
-\begin{enumerate}
- \addtocounter{enumi}{9}
- \item Because the program is licensed free of charge, there is no
- warranty for the program, to the extent permitted by applicable law.
- Except when otherwise stated in writing the copyright holders and/or
- other parties provide the program ``as is'' without warranty of any
- kind, either expressed or implied, including, but not limited to, the
- implied warranties of merchantability and fitness for a particular
- purpose. The entire risk as to the quality and performance of the
- program is with you. Should the program prove defective, you assume
- the cost of all necessary servicing, repair or correction.
- \item In no event unless required by applicable law or agreed to in
- writing will any copyright holder, or any other party who may modify
- and/or redistribute the program as permitted above, be liable to you
- for damages, including any general, special, incidental or
- consequential damages arising out of the use or inability to use the
- program (including but not limited to loss of data or data being
- rendered inaccurate or losses sustained by you or third parties or a
- failure of the program to operate with any other programs), even if
- such holder or other party has been advised of the possibility of
- such damages.
-\end{enumerate}
-
-
-\providecommand{\LPPLsection}{\subsection}
-\providecommand{\LPPLsubsection}{\subsubsection}
-\providecommand{\LPPLsubsubsection}{\subsubsection}
-\providecommand{\LPPLparagraph}{\paragraph}
-
-
-% The file lppl.tex, some minor typographic changes:
-
-%
-% $Id$
-%
-% Copyright 1999 2002-2018 LaTeX3 Project
-% Everyone is allowed to distribute verbatim copies of this
-% license document, but modification of it is not allowed.
-%
-%
-% If you wish to load it as part of a ``doc'' source, you have to
-% ensure that a) % is a comment character and b) that short verb
-% characters are being turned off, i.e.,
-%
-% \DeleteShortVerb{\'} % or whatever was made a shorthand
-% \MakePercentComment
-% \input{lppl}
-% \MakePercentIgnore
-% \MakeShortVerb{\'} % turn it on again if necessary
-%
-%
-% By default the license is produced with \section* as the highest
-% heading level. If this is not appropriate for the document in which
-% it is included define the commands listed below before loading this
-% document, e.g., for inclusion as a separate chapter define:
-%
-% \providecommand{\LPPLsection}{\chapter*}
-% \providecommand{\LPPLsubsection}{\section*}
-% \providecommand{\LPPLsubsubsection}{\subsection*}
-% \providecommand{\LPPLparagraph}{\subsubsection*}
-%
-%
-% To allow cross-referencing the headings \label's have been attached
-% to them, all starting with ``LPPL:''. As by default headings without
-% numbers are produced, this will only allow page references.
-% However, you can use the titleref package to produce textual
-% references or you change the definitions of \LPPLsection, and
-% friends to generated numbered headings.
-%
-%
-% We want it to be possible that this file can be processed by
-% (pdf)LaTeX on its own, or that this file can be included in another
-% LaTeX document without any modification whatsoever.
-% Hence the little test below.
-%
-%
-\makeatletter
-\ifx\@preamblecmds\@notprerr
- % In this case the preamble has already been processed so this file
- % is loaded as part of another document; just enclose everything in
- % a group
- \let\LPPLicense\bgroup
- \let\endLPPLicense\egroup
-\else
- % In this case the preamble has not been processed yet so this file
- % is processed by itself.
- \documentclass{article}
- \let\LPPLicense\document
- \let\endLPPLicense\enddocument
-\fi
-\makeatother
-
-
-\begin{LPPLicense}
- \providecommand{\LPPLsection}{\section*}
- \providecommand{\LPPLsubsection}{\subsection*}
- \providecommand{\LPPLsubsubsection}{\subsubsection*}
- \providecommand{\LPPLparagraph}{\paragraph*}
- \providecommand*{\LPPLfile}[1]{\texttt{#1}}
- \providecommand*{\LPPLdocfile}[1]{`\LPPLfile{#1.tex}'}
- \providecommand*{\LPPL}{\textsc{lppl}}
-
- \LPPLsection{The \LaTeX\ Project Public License, Version 1.3c 2006-05-20}
- \label{LPPL:LPPL}
-
-% \textbf{Copyright 1999, 2002--2006 \LaTeX3 Project}
-% \begin{quotation}
-% Everyone is allowed to distribute verbatim copies of this
-% license document, but modification of it is not allowed.
-% \end{quotation}
-
- \LPPLsubsection{Preamble}
- \label{LPPL:Preamble}
-
- The \LaTeX\ Project Public License (\LPPL) is the primary license under
- which the \LaTeX\ kernel and the base \LaTeX\ packages are distributed.
-
- You may use this license for any work of which you hold the copyright and
- which you wish to distribute. This license may be particularly suitable if
- your work is \TeX-related (such as a \LaTeX\ package), but it is written in
- such a way that you can use it even if your work is unrelated to \TeX.
-
- The section `\textsc{whether and how to distribute works under this
- license}', below, gives instructions, examples, and recommendations for
- authors who are considering distributing their works under this license.
-
- This license gives conditions under which a work may be distributed and
- modified, as well as conditions under which modified versions of that work
- may be distributed.
-
- We, the \LaTeX3 Project, believe that the conditions below give you the
- freedom to make and distribute modified versions of your work that conform
- with whatever technical specifications you wish while maintaining the
- availability, integrity, and reliability of that work. If you do not see
- how to achieve your goal while meeting these conditions, then read the
- document \LPPLdocfile{cfgguide} and \LPPLdocfile{modguide} in the base
- \LaTeX\ distribution for suggestions.
-
-
- \LPPLsubsection{Definitions}
- \label{LPPL:Definitions}
-
- In this license document the following terms are used:
-
- \begin{description}
- \item[Work] Any work being distributed under this License.
- \item[Derived Work] Any work that under any applicable law is
- derived from the Work.
- \item[Modification] Any procedure that produces a Derived Work under
- any applicable law -- for example, the production of a file
- containing an original file associated with the Work or a
- significant portion of such a file, either verbatim or with
- modifications and/or translated into another language.
- \item[Modify] To apply any procedure that produces a Derived Work
- under any applicable law.
- \item[Distribution] Making copies of the Work available from one
- person to another, in whole or in part. Distribution includes (but
- is not limited to) making any electronic components of the Work
- accessible by file transfer protocols such as \textsc{ftp} or
- \textsc{http} or by shared file systems such as Sun's Network File
- System (\textsc{nfs}).
- \item[Compiled Work] A version of the Work that has been processed
- into a form where it is directly usable on a computer system.
- This processing may include using installation facilities provided
- by the Work, transformations of the Work, copying of components of
- the Work, or other activities. Note that modification of any
- installation facilities provided by the Work constitutes
- modification of the Work.
- \item[Current Maintainer] A person or persons nominated as such
- within the Work. If there is no such explicit nomination then it
- is the `Copyright Holder' under any applicable law.
- \item[Base Interpreter] A program or process that is normally needed
- for running or interpreting a part or the whole of the Work.
-
- A Base Interpreter may depend on external components but these are
- not considered part of the Base Interpreter provided that each
- external component clearly identifies itself whenever it is used
- interactively. Unless explicitly specified when applying the
- license to the Work, the only applicable Base Interpreter is a
- `\LaTeX-Format' or in the case of files belonging to the
- `\LaTeX-format' a program implementing the `\TeX{} language'.
- \end{description}
-
-
- \LPPLsubsection{Conditions on Distribution and Modification}
- \label{LPPL:Conditions}
-
- \begin{enumerate}
- \item Activities other than distribution and/or modification of the
- Work are not covered by this license; they are outside its scope.
- In particular, the act of running the Work is not restricted and
- no requirements are made concerning any offers of support for the
- Work.
- \item\label{LPPL:item:distribute} You may distribute a complete,
- unmodified copy of the Work as you received it. Distribution of
- only part of the Work is considered modification of the Work, and
- no right to distribute such a Derived Work may be assumed under the
- terms of this clause.
- \item You may distribute a Compiled Work that has been generated from
- a complete, unmodified copy of the Work as distributed under
- Clause~\ref{LPPL:item:distribute} above, as long as that Compiled
- Work is distributed in such a way that the recipients may install
- the Compiled Work on their system exactly as it would have been
- installed if they generated a Compiled Work directly from the Work.
- \item\label{LPPL:item:currmaint} If you are the Current Maintainer of
- the Work, you may, without restriction, modify the Work, thus
- creating a Derived Work. You may also distribute the Derived Work
- without restriction, including Compiled Works generated from the
- Derived Work. Derived Works distributed in this manner by the
- Current Maintainer are considered to be updated versions of the
- Work.
- \item If you are not the Current Maintainer of the Work, you may modify
- your copy of the Work, thus creating a Derived Work based on the
- Work, and compile this Derived Work, thus creating a Compiled Work
- based on the Derived Work.
- \item\label{LPPL:item:conditions} If you are not the Current Maintainer
- of the Work, you may distribute a Derived Work provided the
- following conditions are met for every component of the Work unless
- that component clearly states in the copyright notice that it is
- exempt from that condition. Only the Current Maintainer is allowed
- to add such statements of exemption to a component of the Work.
- %
- \begin{enumerate}
- \item If a component of this Derived Work can be a direct
- replacement for a component of the Work when that component
- is used with the Base Interpreter, then, wherever this
- component of the Work identifies itself to the user when
- used interactively with that Base Interpreter, the
- replacement component of this Derived Work clearly and
- unambiguously identifies itself as a modified version of
- this component to the user when used interactively with
- that Base Interpreter.
- \item Every component of the Derived Work contains prominent
- notices detailing the nature of the changes to that
- component, or a prominent reference to another file that is
- distributed as part of the Derived Work and that contains a
- complete and accurate log of the changes.
- \item No information in the Derived Work implies that any
- persons, including (but not limited to) the authors of the
- original version of the Work, provide any support,
- including (but not limited to) the reporting and handling
- of errors, to recipients of the Derived Work unless those
- persons have stated explicitly that they do provide such
- support for the Derived Work.
- \item You distribute at least one of the following with the
- Derived Work:
- %
- \begin{enumerate}
- \item A complete, unmodified copy of the Work; if your
- distribution of a modified component is made by
- offering access to copy the modified component from
- a designated place, then offering equivalent access
- to copy the Work from the same or some similar
- place meets this condition, even though third
- parties are not compelled to copy the Work along
- with the modified component;
- \item Information that is sufficient to obtain a
- complete, unmodified copy of the Work.
- \end{enumerate}
- \end{enumerate}
- %
- \item If you are not the Current Maintainer of the Work, you may
- distribute a Compiled Work generated from a Derived Work, as long
- as the Derived Work is distributed to all recipients of the
- Compiled Work, and as long as the conditions of
- Clause~\ref{LPPL:item:conditions}, above, are met with regard to
- the Derived Work.
- \item The conditions above are not intended to prohibit, and hence do
- not apply to, the modification, by any method, of any component so
- that it becomes identical to an updated version of that component
- of the Work as it is distributed by the Current Maintainer under
- Clause~\ref{LPPL:item:currmaint}, above.
- \item Distribution of the Work or any Derived Work in an alternative
- format, where the Work or that Derived Work (in whole or in part)
- is then produced by applying some process to that format, does not
- relax or nullify any sections of this license as they pertain to
- the results of applying that process.
- \item \null
- \begin{enumerate}
- \item A Derived Work may be distributed under a different
- license provided that license itself honors the conditions
- listed in Clause~\ref{LPPL:item:conditions} above, in
- regard to the Work, though it does not have to honor the
- rest of the conditions in this license.
- \item If a Derived Work is distributed under a different license,
- that Derived Work must provide sufficient documentation as part
- of itself to allow each recipient of that Derived Work to honor
- the restrictions in Clause~\ref{LPPL:item:conditions} above,
- concerning changes from the Work.
- \end{enumerate}
- %
- \item This license places no restrictions on works that are unrelated
- to the Work, nor does this license place any restrictions on
- aggregating such works with the Work by any means.
- \item Nothing in this license is intended to, or may be used to, prevent
- complete compliance by all parties with all applicable laws.
- \end{enumerate}
-
-
- \LPPLsubsection{No Warranty}
- \label{LPPL:Warranty}
-
- There is no warranty for the Work. Except when otherwise stated in
- writing, the Copyright Holder provides the Work `as is', without warranty
- of any kind, either expressed or implied, including, but not limited to,
- the implied warranties of merchantability and fitness for a particular
- purpose. The entire risk as to the quality and performance of the Work is
- with you. Should the Work prove defective, you assume the cost of all
- necessary servicing, repair, or correction.
-
- In no event unless required by applicable law or agreed to in writing will
- The Copyright Holder, or any author named in the components of the Work, or
- any other party who may distribute and/or modify the Work as permitted
- above, be liable to you for damages, including any general, special,
- incidental or consequential damages arising out of any use of the Work or
- out of inability to use the Work (including, but not limited to, loss of
- data, data being rendered inaccurate, or losses sustained by anyone as a
- result of any failure of the Work to operate with any other programs), even
- if the Copyright Holder or said author or said other party has been advised
- of the possibility of such damages.
-
-
- \LPPLsubsection{Maintenance of The Work}
- \label{LPPL:Maintenance}
-
- The Work has the status `author-maintained' if the Copyright Holder
- explicitly and prominently states near the primary copyright notice in the
- Work that the Work can only be maintained by the Copyright Holder or simply
- that it is `author-maintained'.
-
- The Work has the status `maintained' if there is a Current Maintainer who
- has indicated in the Work that they are willing to receive error reports
- for the Work (for example, by supplying a valid e-mail address). It is not
- required for the Current Maintainer to acknowledge or act upon these error
- reports.
-
- The Work changes from status `maintained' to `unmaintained' if there is no
- Current Maintainer, or the person stated to be Current Maintainer of the
- work cannot be reached through the indicated means of communication for a
- period of six months, and there are no other significant signs of active
- maintenance.
-
- You can become the Current Maintainer of the Work by agreement with any
- existing Current Maintainer to take over this role.
-
- If the Work is unmaintained, you can become the Current Maintainer of the
- Work through the following steps:
- %
- \begin{enumerate}
- \item Make a reasonable attempt to trace the Current Maintainer (and
- the Copyright Holder, if the two differ) through the means of an
- Internet or similar search.
- \item If this search is successful, then enquire whether the Work is
- still maintained.
- %
- \begin{enumerate}
- \item If it is being maintained, then ask the Current
- Maintainer to update their communication data within one
- month.
- \item\label{LPPL:item:intention} If the search is unsuccessful
- or no action to resume active maintenance is taken by the
- Current Maintainer, then announce within the pertinent
- community your intention to take over maintenance. (If the
- Work is a \LaTeX{} work, this could be done, for example,
- by posting to \texttt{comp.text.tex}.)
- \end{enumerate}
- %
- \item {}
- \begin{enumerate}
- \item If the Current Maintainer is reachable and agrees to
- pass maintenance of the Work to you, then this takes effect
- immediately upon announcement.
- \item\label{LPPL:item:announce} If the Current Maintainer is
- not reachable and the Copyright Holder agrees that maintenance
- of the Work be passed to you, then this takes effect
- immediately upon announcement.
- \end{enumerate}
- %
- \item\label{LPPL:item:change} If you make an `intention
- announcement' as described in~\ref{LPPL:item:intention} above and
- after three months your intention is challenged neither by the
- Current Maintainer nor by the Copyright Holder nor by other people,
- then you may arrange for the Work to be changed so as to name you
- as the (new) Current Maintainer.
- \item If the previously unreachable Current Maintainer becomes
- reachable once more within three months of a change completed under
- the terms of~\ref{LPPL:item:announce} or~\ref{LPPL:item:change},
- then that Current Maintainer must become or remain the Current
- Maintainer upon request provided they then update their
- communication data within one month.
- \end{enumerate}
- %
- A change in the Current Maintainer does not, of itself, alter the fact that
- the Work is distributed under the \LPPL\ license.
-
- If you become the Current Maintainer of the Work, you should immediately
- provide, within the Work, a prominent and unambiguous statement of your
- status as Current Maintainer. You should also announce your new status to
- the same pertinent community as in~\ref{LPPL:item:intention} above.
-
-
- \LPPLsubsection{Whether and How to Distribute Works under This License}
- \label{LPPL:Distribute}
-
- This section contains important instructions, examples, and recommendations
- for authors who are considering distributing their works under this
- license. These authors are addressed as `you' in this section.
-
-
- \LPPLsubsubsection{Choosing This License or Another License}
- \label{LPPL:Choosing}
-
- If for any part of your work you want or need to use \emph{distribution}
- conditions that differ significantly from those in this license, then do
- not refer to this license anywhere in your work but, instead, distribute
- your work under a different license. You may use the text of this license
- as a model for your own license, but your license should not refer to the
- \LPPL\ or otherwise give the impression that your work is distributed under
- the \LPPL.
-
- The document \LPPLdocfile{modguide} in the base \LaTeX\ distribution
- explains the motivation behind the conditions of this license. It
- explains, for example, why distributing \LaTeX\ under the \textsc{gnu}
- General Public License (\textsc{gpl}) was considered inappropriate. Even
- if your work is unrelated to \LaTeX, the discussion in
- \LPPLdocfile{modguide} may still be relevant, and authors intending to
- distribute their works under any license are encouraged to read it.
-
-
- \LPPLsubsubsection{A Recommendation on Modification Without Distribution}
- \label{LPPL:WithoutDistribution}
-
- It is wise never to modify a component of the Work, even for your own
- personal use, without also meeting the above conditions for distributing
- the modified component. While you might intend that such modifications
- will never be distributed, often this will happen by accident -- you may
- forget that you have modified that component; or it may not occur to you
- when allowing others to access the modified version that you are thus
- distributing it and violating the conditions of this license in ways that
- could have legal implications and, worse, cause problems for the community.
- It is therefore usually in your best interest to keep your copy of the Work
- identical with the public one. Many works provide ways to control the
- behavior of that work without altering any of its licensed components.
-
-
- \LPPLsubsubsection{How to Use This License}
- \label{LPPL:HowTo}
-
- To use this license, place in each of the components of your work both an
- explicit copyright notice including your name and the year the work was
- authored and/or last substantially modified. Include also a statement that
- the distribution and/or modification of that component is constrained by
- the conditions in this license.
-
- Here is an example of such a notice and statement:
- %
-\begin{verbatim}
- %% pig.dtx
- %% Copyright 2005 M. Y. Name
- %
- % This work may be distributed and/or modified under the
- % conditions of the LaTeX Project Public License, either version 1.3
- % of this license or (at your option) any later version.
- % The latest version of this license is in
- % http://www.latex-project.org/lppl.txt
- % and version 1.3 or later is part of all distributions of LaTeX
- % version 2005/12/01 or later.
- %
- % This work has the LPPL maintenance status `maintained'.
- %
- % The Current Maintainer of this work is M. Y. Name.
- %
- % This work consists of the files pig.dtx and pig.ins
- % and the derived file pig.sty.
-\end{verbatim}
-
- Given such a notice and statement in a file, the conditions given in this
- license document would apply, with the `Work' referring to the three files
- `\LPPLfile{pig.dtx}', `\LPPLfile{pig.ins}', and `\LPPLfile{pig.sty}' (the
- last being generated from `\LPPLfile{pig.dtx}' using `\LPPLfile{pig.ins}'),
- the `Base Interpreter' referring to any `\LaTeX-Format', and both
- `Copyright Holder' and `Current Maintainer' referring to the person `M. Y.
- Name'.
-
- If you do not want the Maintenance section of \LPPL\ to apply to your Work,
- change `maintained' above into `author-maintained'. However, we recommend
- that you use `maintained' as the Maintenance section was added in order to
- ensure that your Work remains useful to the community even when you can no
- longer maintain and support it yourself.
-
-
- \LPPLsubsubsection{Derived Works That Are Not Replacements}
- \label{LPPL:NotReplacements}
-
- Several clauses of the \LPPL\ specify means to provide reliability and
- stability for the user community. They therefore concern themselves with
- the case that a Derived Work is intended to be used as a (compatible or
- incompatible) replacement of the original Work. If this is not the case
- (e.g., if a few lines of code are reused for a completely different task),
- then clauses 6b and 6d shall not apply.
-
-
- \LPPLsubsubsection{Important Recommendations}
- \label{LPPL:Recommendations}
-
- \LPPLparagraph{Defining What Constitutes the Work}
-
- The \LPPL\ requires that distributions of the Work contain all the files of
- the Work. It is therefore important that you provide a way for the
- licensee to determine which files constitute the Work. This could, for
- example, be achieved by explicitly listing all the files of the Work near
- the copyright notice of each file or by using a line such as:
- %
-\begin{verbatim}
- % This work consists of all files listed in manifest.txt.
-\end{verbatim}
- %
- in that place. In the absence of an unequivocal list it might be
- impossible for the licensee to determine what is considered by you to
- comprise the Work and, in such a case, the licensee would be entitled to
- make reasonable conjectures as to which files comprise the Work.
-\end{LPPLicense}
-
-
-\subsection{GNU Free Documentation License, Version 1.2, November 2002}
-\label{label_fdl}
-
-% \textbf{Copyright 2000,2001,2002 Free Software Foundation, Inc.}\par
-% 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
-% \begin{quotation}
-% Everyone is allowed to distribute verbatim copies of this
-% license document, but modification of it is not allowed.
-% \end{quotation}
-
-\subsubsection{Preamble}
-
-The purpose of this License is to make a manual, textbook, or other functional
-and useful document ``free'' in the sense of freedom: to assure everyone the
-effective freedom to copy and redistribute it, with or without modifying it,
-either commercially or noncommercially. Secondarily, this License preserves for
-the author and publisher a way to get credit for their work, while not being
-considered responsible for modifications made by others.
-
-This License is a kind of ``copyleft'', which means that derivative works of
-the document must themselves be free in the same sense. It complements the GNU
-General Public License, which is a copyleft license designed for free software.
-
-We have designed this License in order to use it for manuals for free software,
-because free software needs free documentation: a free program should come with
-manuals providing the same freedoms that the software does. But this License
-is not limited to software manuals; it can be used for any textual work,
-regardless of subject matter or whether it is published as a printed book. We
-recommend this License principally for works whose purpose is instruction or
-reference.
-
-
-\subsubsection{Applicability and definitions}
-
-This License applies to any manual or other work, in any medium, that contains
-a notice placed by the copyright holder saying it can be distributed under the
-terms of this License. Such a notice grants a world-wide, royalty-free
-license, unlimited in duration, to use that work under the conditions stated
-herein. The \textbf{``Document''}, below, refers to any such manual or work.
-Any member of the public is a licensee, and is addressed as \textbf{``you''}.
-You accept the license if you copy, modify or distribute the work in a way
-requiring permission under copyright law.
-
-A \textbf{``Modified Version''} of the Document means any work containing the
-Document or a portion of it, either copied verbatim, or with modifications
-and/or translated into another language.
-
-A \textbf{``Secondary Section''} is a named appendix or a front-matter section
-of the Document that deals exclusively with the relationship of the publishers
-or authors of the Document to the Document's overall subject (or to related
-matters) and contains nothing that could fall directly within that overall
-subject. (Thus, if the Document is in part a textbook of mathematics, a
-Secondary Section may not explain any mathematics.) The relationship could be
-a matter of historical connection with the subject or with related matters, or
-of legal, commercial, philosophical, ethical or political position regarding
-them.
-
-The \textbf{``Invariant Sections''} are certain Secondary Sections whose titles
-are designated, as being those of Invariant Sections, in the notice that says
-that the Document is released under this License. If a section does not fit
-the above definition of Secondary then it is not allowed to be designated as
-Invariant. The Document may contain zero Invariant Sections. If the Document
-does not identify any Invariant Sections then there are none.
-
-The \textbf{``Cover Texts''} are certain short passages of text that are
-listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that
-the Document is released under this License. A Front-Cover Text may be at most
-5 words, and a Back-Cover Text may be at most 25 words.
-
-A \textbf{``Transparent''} copy of the Document means a machine-readable copy,
-represented in a format whose specification is available to the general public,
-that is suitable for revising the document straightforwardly with generic text
-editors or (for images composed of pixels) generic paint programs or (for
-drawings) some widely available drawing editor, and that is suitable for input
-to text formatters or for automatic translation to a variety of formats
-suitable for input to text formatters. A copy made in an otherwise Transparent
-file format whose markup, or absence of markup, has been arranged to thwart or
-discourage subsequent modification by readers is not Transparent. An image
-format is not Transparent if used for any substantial amount of text. A copy
-that is not ``Transparent'' is called \textbf{``Opaque''}.
-
-Examples of suitable formats for Transparent copies include plain ASCII without
-markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly
-available DTD, and standard-conforming simple HTML, PostScript or PDF designed
-for human modification. Examples of transparent image formats include PNG, XCF
-and JPG. Opaque formats include proprietary formats that can be read and
-edited only by proprietary word processors, SGML or XML for which the DTD
-and/or processing tools are not generally available, and the machine-generated
-HTML, PostScript or PDF produced by some word processors for output purposes
-only.
-
-The \textbf{``Title Page''} means, for a printed book, the title page itself,
-plus such following pages as are needed to hold, legibly, the material this
-License requires to appear in the title page. For works in formats which do
-not have any title page as such, ``Title Page'' means the text near the most
-prominent appearance of the work's title, preceding the beginning of the body
-of the text.
-
-A section \textbf{``Entitled XYZ''} means a named subunit of the Document whose
-title either is precisely XYZ or contains XYZ in parentheses following text
-that translates XYZ in another language. (Here XYZ stands for a specific
-section name mentioned below, such as \textbf{``Acknowledgements''},
-\textbf{``Dedications''}, \textbf{``Endorsements''}, or \textbf{``History''}.)
-To \textbf{``Preserve the Title''} of such a section when you modify the
-Document means that it remains a section ``Entitled XYZ'' according to this
-definition.
-
-The Document may include Warranty Disclaimers next to the notice which states
-that this License applies to the Document. These Warranty Disclaimers are
-considered to be included by reference in this License, but only as regards
-disclaiming warranties: any other implication that these Warranty Disclaimers
-may have is void and has no effect on the meaning of this License.
-
-
-\subsubsection{Verbatim Copying}
-
-You may copy and distribute the Document in any medium, either commercially or
-noncommercially, provided that this License, the copyright notices, and the
-license notice saying this License applies to the Document are reproduced in
-all copies, and that you add no other conditions whatsoever to those of this
-License. You may not use technical measures to obstruct or control the reading
-or further copying of the copies you make or distribute. However, you may
-accept compensation in exchange for copies. If you distribute a large enough
-number of copies you must also follow the conditions in section~3.
-
-You may also lend copies, under the same conditions stated above, and you may
-publicly display copies.
-
-
-\subsubsection{Copying in Quantity}
-
-If you publish printed copies (or copies in media that commonly have printed
-covers) of the Document, numbering more than 100, and the Document's license
-notice requires Cover Texts, you must enclose the copies in covers that carry,
-clearly and legibly, all these Cover Texts: Front-Cover Texts on the front
-cover, and Back-Cover Texts on the back cover. Both covers must also clearly
-and legibly identify you as the publisher of these copies. The front cover
-must present the full title with all words of the title equally prominent and
-visible. You may add other material on the covers in addition. Copying with
-changes limited to the covers, as long as they preserve the title of the
-Document and satisfy these conditions, can be treated as verbatim copying in
-other respects.
-
-If the required texts for either cover are too voluminous to fit legibly, you
-should put the first ones listed (as many as fit reasonably) on the actual
-cover, and continue the rest onto adjacent pages.
-
-If you publish or distribute Opaque copies of the Document numbering more than
-100, you must either include a machine-readable Transparent copy along with
-each Opaque copy, or state in or with each Opaque copy a computer-network
-location from which the general network-using public has access to download
-using public-standard network protocols a complete Transparent copy of the
-Document, free of added material. If you use the latter option, you must take
-reasonably prudent steps, when you begin distribution of Opaque copies in
-quantity, to ensure that this Transparent copy will remain thus accessible at
-the stated location until at least one year after the last time you distribute
-an Opaque copy (directly or through your agents or retailers) of that edition
-to the public.
-
-It is requested, but not required, that you contact the authors of the Document
-well before redistributing any large number of copies, to give them a chance to
-provide you with an updated version of the Document.
-
-
-\subsubsection{Modifications}
-
-You may copy and distribute a Modified Version of the Document under the
-conditions of sections 2 and 3 above, provided that you release the Modified
-Version under precisely this License, with the Modified Version filling the
-role of the Document, thus licensing distribution and modification of the
-Modified Version to whoever possesses a copy of it. In addition, you must do
-these things in the Modified Version:
-%
-\begin{itemize}
- \item[A.] Use in the Title Page (and on the covers, if any) a title
- distinct from that of the Document, and from those of previous
- versions (which should, if there were any, be listed in the History
- section of the Document). You may use the same title as a previous
- version if the original publisher of that version gives permission.
- \item[B.] List on the Title Page, as authors, one or more persons or
- entities responsible for authorship of the modifications in the
- Modified Version, together with at least five of the principal
- authors of the Document (all of its principal authors, if it has
- fewer than five), unless they release you from this requirement.
- \item[C.] State on the Title page the name of the publisher of the
- Modified Version, as the publisher.
- \item[D.] Preserve all the copyright notices of the Document.
- \item[E.] Add an appropriate copyright notice for your modifications
- adjacent to the other copyright notices.
- \item[F.] Include, immediately after the copyright notices, a license
- notice giving the public permission to use the Modified Version under
- the terms of this License, in the form shown in the Addendum below.
- \item[G.] Preserve in that license notice the full lists of Invariant
- Sections and required Cover Texts given in the Document's license
- notice.
- \item[H.] Include an unaltered copy of this License.
- \item[I.] Preserve the section Entitled ``History'', Preserve its Title,
- and add to it an item stating at least the title, year, new authors,
- and publisher of the Modified Version as given on the Title Page. If
- there is no section Entitled ``History'' in the Document, create one
- stating the title, year, authors, and publisher of the Document as
- given on its Title Page, then add an item describing the Modified
- Version as stated in the previous sentence.
- \item[J.] Preserve the network location, if any, given in the Document
- for public access to a Transparent copy of the Document, and likewise
- the network locations given in the Document for previous versions it
- was based on. These may be placed in the ``History'' section. You
- may omit a network location for a work that was published at least
- four years before the Document itself, or if the original publisher
- of the version it refers to gives permission.
- \item[K.] For any section Entitled ``Acknowledgements'' or
- ``Dedications'', Preserve the Title of the section, and preserve in
- the section all the substance and tone of each of the contributor
- acknowledgements and/or dedications given therein.
- \item[L.] Preserve all the Invariant Sections of the Document, unaltered
- in their text and in their titles. Section numbers or the equivalent
- are not considered part of the section titles.
- \item[M.] Delete any section Entitled ``Endorsements''. Such a section
- may not be included in the Modified Version.
- \item[N.] Do not retitle any existing section to be Entitled
- ``Endorsements'' or to conflict in title with any Invariant Section.
- \item[O.] Preserve any Warranty Disclaimers.
-\end{itemize}
-
-If the Modified Version includes new front-matter sections or appendices that
-qualify as Secondary Sections and contain no material copied from the Document,
-you may at your option designate some or all of these sections as invariant.
-To do this, add their titles to the list of Invariant Sections in the Modified
-Version's license notice. These titles must be distinct from any other section
-titles.
-
-You may add a section Entitled ``Endorsements'', provided it contains nothing
-but endorsements of your Modified Version by various parties--for example,
-statements of peer review or that the text has been approved by an organization
-as the authoritative definition of a standard.
-
-You may add a passage of up to five words as a Front-Cover Text, and a passage
-of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts
-in the Modified Version. Only one passage of Front-Cover Text and one of
-Back-Cover Text may be added by (or through arrangements made by) any one
-entity. If the Document already includes a cover text for the same cover,
-previously added by you or by arrangement made by the same entity you are
-acting on behalf of, you may not add another; but you may replace the old one,
-on explicit permission from the previous publisher that added the old one.
-
-The author(s) and publisher(s) of the Document do not by this License give
-permission to use their names for publicity for or to assert or imply
-endorsement of any Modified Version.
-
-
-\subsubsection{Combining Documents}
-
-You may combine the Document with other documents released under this License,
-under the terms defined in section 4 above for modified versions, provided that
-you include in the combination all of the Invariant Sections of all of the
-original documents, unmodified, and list them all as Invariant Sections of your
-combined work in its license notice, and that you preserve all their Warranty
-Disclaimers.
-
-The combined work need only contain one copy of this License, and multiple
-identical Invariant Sections may be replaced with a single copy. If there are
-multiple Invariant Sections with the same name but different contents, make the
-title of each such section unique by adding at the end of it, in parentheses,
-the name of the original author or publisher of that section if known, or else
-a unique number. Make the same adjustment to the section titles in the list of
-Invariant Sections in the license notice of the combined work.
-
-In the combination, you must combine any sections Entitled ``History'' in the
-various original documents, forming one section Entitled ``History''; likewise
-combine any sections Entitled ``Acknowledgements'', and any sections Entitled
-``Dedications''. You must delete all sections Entitled ``Endorsements''.
-
-
-\subsubsection{Collection of Documents}
-
-You may make a collection consisting of the Document and other documents
-released under this License, and replace the individual copies of this License
-in the various documents with a single copy that is included in the collection,
-provided that you follow the rules of this License for verbatim copying of each
-of the documents in all other respects.
-
-You may extract a single document from such a collection, and distribute it
-individually under this License, provided you insert a copy of this License
-into the extracted document, and follow this License in all other respects
-regarding verbatim copying of that document.
-
-
-\subsubsection{Aggregating with independent Works}
-
-A compilation of the Document or its derivatives with other separate and
-independent documents or works, in or on a volume of a storage or distribution
-medium, is called an ``aggregate'' if the copyright resulting from the
-compilation is not used to limit the legal rights of the compilation's users
-beyond what the individual works permit. When the Document is included in an
-aggregate, this License does not apply to the other works in the aggregate
-which are not themselves derivative works of the Document.
-
-If the Cover Text requirement of section 3 is applicable to these copies of the
-Document, then if the Document is less than one half of the entire aggregate,
-the Document's Cover Texts may be placed on covers that bracket the Document
-within the aggregate, or the electronic equivalent of covers if the Document is
-in electronic form. Otherwise they must appear on printed covers that bracket
-the whole aggregate.
-
-
-\subsubsection{Translation}
-
-Translation is considered a kind of modification, so you may distribute
-translations of the Document under the terms of section 4. Replacing Invariant
-Sections with translations requires special permission from their copyright
-holders, but you may include translations of some or all Invariant Sections in
-addition to the original versions of these Invariant Sections. You may include
-a translation of this License, and all the license notices in the Document, and
-any Warranty Disclaimers, provided that you also include the original English
-version of this License and the original versions of those notices and
-disclaimers. In case of a disagreement between the translation and the
-original version of this License or a notice or disclaimer, the original
-version will prevail.
-
-If a section in the Document is Entitled ``Acknowledgements'', ``Dedications'',
-or ``History'', the requirement (section 4) to Preserve its Title (section 1)
-will typically require changing the actual title.
-
-
-\subsubsection{Termination}
-
-You may not copy, modify, sublicense, or distribute the Document except as
-expressly provided for under this License. Any other attempt to copy, modify,
-sublicense or distribute the Document is void, and will automatically terminate
-your rights under this License. However, parties who have received copies, or
-rights, from you under this License will not have their licenses terminated so
-long as such parties remain in full compliance.
-
-
-\subsubsection{Future Revisions of this License}
-
-The Free Software Foundation may publish new, revised versions of the GNU Free
-Documentation License from time to time. Such new versions will be similar in
-spirit to the present version, but may differ in detail to address new problems
-or concerns. See http://www.gnu.org/copyleft/.
-
-Each version of the License is given a distinguishing version number. If the
-Document specifies that a particular numbered version of this License ``or any
-later version'' applies to it, you have the option of following the terms and
-conditions either of that specified version or of any later version that has
-been published (not as a draft) by the Free Software Foundation. If the
-Document does not specify a version number of this License, you may choose any
-version ever published (not as a draft) by the Free Software Foundation.
-
-
-\subsubsection{Addendum: How to use this License for your documents}
-
-To use this License in a document you have written, include a copy of the
-License in the document and put the following copyright and license notices
-just after the title page:
-
-\bigskip
-\begin{quote}
- Copyright \copyright \textsc{year your name}.
- Permission is granted to copy, distribute and/or modify this document
- under the terms of the GNU Free Documentation License, Version 1.2
- or any later version published by the Free Software Foundation;
- with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.
- A copy of the license is included in the section entitled ``GNU
- Free Documentation License''.
-\end{quote}
-\bigskip
-
-If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace
-the ``with \dots\ Texts''. line with this:
-
-\bigskip
-\begin{quote}
- with the Invariant Sections being \textsc{list their titles}, with the
- Front-Cover Texts being \textsc{list}, and with the Back-Cover
- Texts being \textsc{list}.
-\end{quote}
-\bigskip
-
-If you have Invariant Sections without Cover Texts, or some other combination
-of the three, merge those two alternatives to suit the situation.
-
-If your document contains nontrivial examples of program code, we recommend
-releasing these examples in parallel under your choice of free software
-license, such as the GNU General Public License, to permit their use in free
-software.
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "beameruserguide"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-main-body.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-main-body.tex
deleted file mode 100644
index fd45d90821..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-main-body.tex
+++ /dev/null
@@ -1,860 +0,0 @@
-% 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.
-
-
-\begin{document}
-
-% The titlepage
-
-\pgfmathsetseed{1}
-\newbox\mybox
-{
- \parindent0pt
- \null
- \colorlet{mintgreen}{green!50!black!50}
-
- \thispagestyle{empty}
- \vskip3cm
- \vfill
- \hfil
- \begin{tikzpicture}[overlay]
- \coordinate (front) at (0,0);
- \coordinate (horizon) at (0,.31\paperheight);
- \coordinate (bottom) at (0,-.6\paperheight);
- \coordinate (sky) at (0,.57\paperheight);
- \coordinate (left) at (-.51\paperwidth,0);
- \coordinate (right) at (.51\paperwidth,0);
-
- \shade [bottom color=blue!30!black!10,top color=blue!30!black!50]
- ([yshift=-5mm]horizon -| left) rectangle (sky -| right);
- \shade [bottom color=black!70!green!25,top color=black!70!green!10]
- (front -| left) -- (horizon -| left)
- decorate [decoration=random steps] { -- (horizon -| right) }
- -- (front -| right) -- cycle;
- \shade [top color=black!70!green!25,bottom color=black!25]
- ([yshift=-5mm-1pt]front -| left) rectangle ([yshift=1pt]front -| right);
- \fill [black!25] (bottom -| left) rectangle ([yshift=-5mm]front -| right);
-
- \def\nodeshadowed[#1]#2;{\node[scale=2,above,#1]{\global\setbox\mybox=\hbox{#2}\copy\mybox};
- \node[scale=2,above,#1,yscale=-1,scope fading=south,opacity=0.4]{\box\mybox};}
-
- \nodeshadowed [at={(-5,5 )},yslant=0.05] {\Huge Ti\textcolor{orange}{\emph{k}}Z};
- \nodeshadowed [at={( 0,5.3)}] {\huge \textcolor{mintgreen}{\&}};
- \nodeshadowed [at={( 5,5 )},yslant=-0.05] {\Huge \textsc{PGF}};
- \nodeshadowed [at={( 0,2 )}] {Manual for Version \pgftypesetversion};
-
- \foreach \where in {-9cm,9cm}
- {\nodeshadowed [at={(\where,5cm)}] {
- % TODO: Nesting tikzpictures is NOT supported
- \tikz \draw [green!20!black, rotate=90]
- [l-system={rule set={F -> FF-[-F+F]+[+F-F]}, axiom=F, order=4,
- step=2pt, randomize step percent=50, angle=30, randomize angle percent=5}]
- lindenmayer system;};}
-
- \foreach \i in {0.5,0.6,...,2}
- \fill [white,decoration=Koch snowflake,opacity=.9]
- [shift=(horizon),shift={(rand*11,rnd*7)},scale=\i]
- [double copy shadow={opacity=0.2,shadow xshift=0pt,shadow
- yshift=3*\i pt,fill=white,draw=none}]
- decorate {
- decorate {
- decorate {
- (0,0) -- ++(60:1) -- ++(-60:1) -- cycle
- }
- }
- };
-
- \node (left text) [text width=.5\paperwidth-2cm,below right,at={(-.5\paperwidth+1cm,-1.5cm)}]
- {
- \fontencoding{T1}
- \fontfamily{pcr}
- \def\textbraceleft{\char`\{}
- \def\textbraceright{\char`\}}
- \def\textbackslash{\char`\\}
- \begin{lstlisting}[basicstyle=\scriptsize\color{black},
- keywordstyle=\bfseries\color{white},
- identifierstyle=\bfseries\color{black},
- keywords={tikzpicture,shade,fill,draw,path,node},
- literate={-}{{-}}1]
-\begin{tikzpicture}
- \coordinate (front) at (0,0);
- \coordinate (horizon) at (0,.31\paperheight);
- \coordinate (bottom) at (0,-.6\paperheight);
- \coordinate (sky) at (0,.57\paperheight);
- \coordinate (left) at (-.51\paperwidth,0);
- \coordinate (right) at (.51\paperwidth,0);
-
- \shade [bottom color=white,
- top color=blue!30!black!50]
- ([yshift=-5mm]horizon -| left)
- rectangle (sky -| right);
-
- \shade [bottom color=black!70!green!25,
- top color=black!70!green!10]
- (front -| left) -- (horizon -| left)
- decorate [decoration=random steps] {
- -- (horizon -| right) }
- -- (front -| right) -- cycle;
-
- \shade [top color=black!70!green!25,
- bottom color=black!25]
- ([yshift=-5mm-1pt]front -| left)
- rectangle ([yshift=1pt]front -| right);
-
- \fill [black!25]
- (bottom -| left)
- rectangle ([yshift=-5mm]front -| right);
-
- \def\nodeshadowed[#1]#2;{
- \node[scale=2,above,#1]{
- \global\setbox\mybox=\hbox{#2}
- \copy\mybox};
- \node[scale=2,above,#1,yscale=-1,
- scope fading=south,opacity=0.4]{\box\mybox};
- }
-\end{lstlisting}
-};
-
- \node (right text) [text width=.5\paperwidth-2cm,below right,at={(1cm,-1.5cm)}]
- {
- \fontencoding{T1}
- \fontfamily{pcr}
- \def\textbraceleft{\char`\{}
- \def\textbraceright{\char`\}}
- \def\textbackslash{\char`\\}
- \begin{lstlisting}[basicstyle=\scriptsize\color{black},
- keywordstyle=\bfseries\color{white},
- identifierstyle=\bfseries\color{black},
- keywords={tikzpicture,shade,fill,draw,path,node},
- literate={-}{{-}}1]
- \nodeshadowed [at={(-5,8 )},yslant=0.05]
- {\Huge Ti\textcolor{orange}{\emph{k}}Z};
- \nodeshadowed [at={( 0,8.3)}]
- {\huge \textcolor{green!50!black!50}{\&}};
- \nodeshadowed [at={( 5,8 )},yslant=-0.05]
- {\Huge \textsc{PGF}};
- \nodeshadowed [at={( 0,5 )}]
- {Manual for Version \pgftypesetversion};
-
- \foreach \where in {-9cm,9cm} {
- \nodeshadowed [at={(\where,5cm)}] { \tikz
- \draw [green!20!black, rotate=90,
- l-system={rule set={F -> FF-[-F+F]+[+F-F]},
- axiom=F, order=4,step=2pt,
- randomize step percent=50, angle=30,
- randomize angle percent=5}] l-system; }}
-
- \foreach \i in {0.5,0.6,...,2}
- \fill
- [white,opacity=\i/2,
- decoration=Koch snowflake,
- shift=(horizon),shift={(rand*11,rnd*7)},
- scale=\i,double copy shadow={
- opacity=0.2,shadow xshift=0pt,
- shadow yshift=3*\i pt,fill=white,draw=none}]
- decorate {
- decorate {
- decorate {
- (0,0)- ++(60:1) -- ++(-60:1) -- cycle
- } } };
-
- \node (left text) ...
- \node (right text) ...
-
- \fill [decorate,decoration={footprints,foot of=gnome},
- opacity=.5,brown] (rand*8,-rnd*10)
- to [out=rand*180,in=rand*180] (rand*8,-rnd*10);
-\end{tikzpicture}
- \end{lstlisting}
- };
-
- \fill [decorate,decoration=footprints,
- decoration={footprints,foot of=gnome},
- opacity=.5,brown] (rand*8,-rnd*10)
- to [out=rand*180,in=rand*180] (rand*8,-rnd*10);
-\end{tikzpicture}
-\vfill
-\vbox{}
-\clearpage
-}
-
-{
- \vbox{}
- \vskip0pt plus 1fill
- Für meinen Vater, damit er noch viele schöne \TeX-Graphiken
- erschaffen kann.
- \vskip1em
- \hfill\emph{Till}
- \vskip0pt plus 3fill
-
- \parindent=0pt
- Copyright 2007 to 2013 by Till Tantau
-
- \medskip
- Permission is granted to copy, distribute and/or modify \emph{the
- documentation} under the terms of the \textsc{gnu} Free Documentation
- License, Version 1.2 or any later version published by the Free Software
- Foundation; with no Invariant Sections, no Front-Cover Texts, and no
- Back-Cover Texts. A copy of the license is included in the section entitled
- \textsc{gnu} Free Documentation License.
-
- \medskip
- Permission is granted to copy, distribute and/or modify \emph{the code of the
- package} under the terms of the \textsc{gnu} Public License, Version 2 or any
- later version published by the Free Software Foundation. A copy of the
- license is included in the section entitled \textsc{gnu} Public License.
-
- \medskip
- Permission is also granted to distribute and/or modify \emph{both the
- documentation and the code} under the conditions of the LaTeX Project Public
- License, either version 1.3 of this license or (at your option) any later
- version. A copy of the license is included in the section entitled \LaTeX\
- Project Public License.
-
- \vbox{}
- \clearpage
-}
-
-
-\title{\bfseries The \tikzname\ and {\Large PGF} Packages\\
- \large Manual for version \pgfversion\\[1mm]
-\large\href{https://github.com/pgf-tikz/pgf}{\texttt{https://github.com/pgf-tikz/pgf}}}
-\author{Till Tantau\footnote{Editor of this documentation. Parts of
- this documentation have been written by other authors as indicated
- in these parts or chapters and in Section~\ref{section-authors}.}\\
- \normalsize Institut für Theoretische Informatik\\[-1mm]
- \normalsize Universität zu Lübeck}
-
-\maketitle
-\label{table-of-contents}
-
-\tableofcontents
-
-\clearpage
-
-
-\include{pgfmanual-en-introduction}
-
-
-
-\part{Tutorials and Guidelines}
-
-{\Large \emph{by Till Tantau}}
-
-\bigskip
-\noindent To help you get started with \tikzname, instead of a long
-installation and configuration section, this manual starts with tutorials. They
-explain all the basic and some of the more advanced features of the system,
-without going into all the details. This part also contains some guidelines on
-how you should proceed when creating graphics using \tikzname.
-
-\vskip3cm
-
-\begin{codeexample}[graphic=white,width=0pt]
-\tikz \draw[thick,rounded corners=8pt]
- (0,0) -- (0,2) -- (1,3.25) -- (2,2) -- (2,0) -- (0,2) -- (2,2) -- (0,0) -- (2,0);
-\end{codeexample}
-
-
-\include{pgfmanual-en-tutorial}
-\include{pgfmanual-en-tutorial-nodes}
-\include{pgfmanual-en-tutorial-Euclid}
-\include{pgfmanual-en-tutorial-chains}
-\include{pgfmanual-en-tutorial-map}
-\include{pgfmanual-en-guidelines}
-
-
-
-\part{Installation and Configuration}
-
-{\Large \emph{by Till Tantau}}
-
-
-\bigskip
-\noindent This part explains how the system is installed. Typically, someone
-has already done so for your system, so this part can be skipped; but if this
-is not the case and you are the poor fellow who has to do the installation,
-read the present part.
-
-
-\vskip1cm
-
-\begin{codeexample}[graphic=white,preamble={\usetikzlibrary{arrows.meta,automata,positioning,shadows}}]
-\begin{tikzpicture}[->,>={Stealth[round]},shorten >=1pt,auto,node distance=2.8cm,on grid,semithick,
- every state/.style={fill=red,draw=none,circular drop shadow,text=white}]
-
- \node[initial,state] (A) {$q_a$};
- \node[state] (B) [above right=of A] {$q_b$};
- \node[state] (D) [below right=of A] {$q_d$};
- \node[state] (C) [below right=of B] {$q_c$};
- \node[state] (E) [below=of D] {$q_e$};
-
- \path (A) edge node {0,1,L} (B)
- edge node {1,1,R} (C)
- (B) edge [loop above] node {1,1,L} (B)
- edge node {0,1,L} (C)
- (C) edge node {0,1,L} (D)
- edge [bend left] node {1,0,R} (E)
- (D) edge [loop below] node {1,1,R} (D)
- edge node {0,1,R} (A)
- (E) edge [bend left] node {1,0,R} (A);
-
- \node [right=1cm,text width=8cm] at (C)
- {
- The current candidate for the busy beaver for five states. It is
- presumed that this Turing machine writes a maximum number of
- $1$'s before halting among all Turing machines with five states
- and the tape alphabet $\{0, 1\}$. Proving this conjecture is an
- open research problem.
- };
-\end{tikzpicture}
-\end{codeexample}
-
-
-\include{pgfmanual-en-installation}
-\include{pgfmanual-en-license}
-\include{pgfmanual-en-drivers}
-
-
-
-\part{Ti\emph{k}Z ist \emph{kein} Zeichenprogramm}
-\label{part-tikz}
-
-{\Large \emph{by Till Tantau}}
-
-
-\bigskip
-\noindent
-\vskip3cm
-\begin{codeexample}[graphic=white,preamble={\usetikzlibrary{angles,calc,quotes}}]
-\begin{tikzpicture}[angle radius=.75cm]
-
- \node (A) at (-2,0) [red,left] {$A$};
- \node (B) at ( 3,.5) [red,right] {$B$};
- \node (C) at (-2,2) [blue,left] {$C$};
- \node (D) at ( 3,2.5) [blue,right] {$D$};
- \node (E) at (60:-5mm) [below] {$E$};
- \node (F) at (60:3.5cm) [above] {$F$};
-
- \coordinate (X) at (intersection cs:first line={(A)--(B)}, second line={(E)--(F)});
- \coordinate (Y) at (intersection cs:first line={(C)--(D)}, second line={(E)--(F)});
-
- \path
- (A) edge [red, thick] (B)
- (C) edge [blue, thick] (D)
- (E) edge [thick] (F)
- pic ["$\alpha$", draw, fill=yellow] {angle = F--X--A}
- pic ["$\beta$", draw, fill=green!30] {angle = B--X--F}
- pic ["$\gamma$", draw, fill=yellow] {angle = E--Y--D}
- pic ["$\delta$", draw, fill=green!30] {angle = C--Y--E};
-
- \node at ($ (D)!.5!(B) $) [right=1cm,text width=6cm,rounded corners,fill=red!20,inner sep=1ex]
- {
- When we assume that $\color{red}AB$ and $\color{blue}CD$ are
- parallel, i.\,e., ${\color{red}AB} \mathbin{\|} \color{blue}CD$,
- then $\alpha = \gamma$ and $\beta = \delta$.
- };
-\end{tikzpicture}
-\end{codeexample}
-
-
-\include{pgfmanual-en-tikz-design}
-\include{pgfmanual-en-tikz-scopes}
-\include{pgfmanual-en-tikz-coordinates}
-\include{pgfmanual-en-tikz-paths}
-\include{pgfmanual-en-tikz-actions}
-\include{pgfmanual-en-tikz-arrows}
-\include{pgfmanual-en-tikz-shapes}
-\include{pgfmanual-en-tikz-pics}
-\include{pgfmanual-en-tikz-graphs}
-\include{pgfmanual-en-tikz-matrices}
-\include{pgfmanual-en-tikz-trees}
-\include{pgfmanual-en-tikz-plots}
-\include{pgfmanual-en-tikz-transparency}
-\include{pgfmanual-en-tikz-decorations}
-\include{pgfmanual-en-tikz-transformations}
-\include{pgfmanual-en-tikz-animations}
-
-
-
-\part{Graph Drawing}
-\label{part-gd}
-
-{\Large \emph{by Till Tantau et al.}}
-
-\bigskip
-\noindent
-\emph{Graph drawing algorithms} do the tough work of computing a layout of a
-graph for you. \tikzname\ comes with powerful such algorithms, but you can also
-implement new algorithms in the Lua programming language. \vskip1cm
-
-\ifluatex
-\begin{codeexample}[
- graphic=white,
- preamble={\usetikzlibrary{arrows.meta,graphs,graphdrawing}
-\usegdlibrary{layered}}]
-\tikz [nodes={text height=.7em, text depth=.2em,
- draw=black!20, thick, fill=white, font=\footnotesize},
- >={Stealth[round,sep]}, rounded corners, semithick]
- \graph [layered layout, level distance=1cm, sibling sep=.5em, sibling distance=1cm] {
- "5th Edition" -> { "6th Edition", "PWB 1.0" };
- "6th Edition" -> { "LSX" [>child anchor=45], "1 BSD", "Mini Unix", "Wollongong", "Interdata" };
- "Interdata" -> { "Unix/TS 3.0", "PWB 2.0", "7th Edition" };
- "7th Edition" -> { "8th Edition", "32V", "V7M", "Ultrix-11", "Xenix", "UniPlus+" };
- "V7M" -> "Ultrix-11";
- "8th Edition" -> "9th Edition";
- "1 BSD" -> "2 BSD" -> "2.8 BSD" -> { "Ultrix-11", "2.9 BSD" };
- "32V" -> "3 BSD" -> "4 BSD" -> "4.1 BSD" -> { "4.2 BSD", "2.8 BSD", "8th Edition" };
- "4.2 BSD" -> { "4.3 BSD", "Ultrix-32" };
- "PWB 1.0" -> { "PWB 1.2" -> "PWB 2.0", "USG 1.0" -> { "CB Unix 1", "USG 2.0" }};
- "CB Unix 1" -> "CB Unix 2" -> "CB Unix 3" -> { "Unix/TS++", "PDP-11 Sys V" };
- { "USG 2.0" -> "USG 3.0", "PWB 2.0", "Unix/TS 1.0" } -> "Unix/TS 3.0";
- { "Unix/TS++", "CB Unix 3", "Unix/TS 3.0" } -> "TS 4.0" -> "System V.0" -> "System V.2" -> "System V.3";
- };
-\end{codeexample}
-
-\else
- You need to use Lua\TeX\ to typeset this part of the manual (and, also, to
- use algorithmic graph drawing).
-\fi
-
-
-\include{pgfmanual-en-gd-overview}
-\include{pgfmanual-en-gd-usage-tikz}
-\include{pgfmanual-en-gd-usage-pgf}
-\include{pgfmanual-en-gd-trees}
-\include{pgfmanual-en-gd-layered}
-\include{pgfmanual-en-gd-force}
-\include{pgfmanual-en-gd-circular}
-\include{pgfmanual-en-gd-phylogenetics}
-\include{pgfmanual-en-gd-edge-routing}
-%
-% XXX : disabled because of
-% 1. compile-time dependencies which are hard to resolve
-% 2. it is "hardly usable anyway" (TT)
-%\include{pgfmanual-en-gd-ogdf}
-\include{pgfmanual-en-gd-algorithm-layer}
-\include{pgfmanual-en-gd-algorithms-in-c}
-\include{pgfmanual-en-gd-display-layer}
-\include{pgfmanual-en-gd-binding-layer}
-
-
-
-\part{Libraries}
-\label{part-libraries}
-
-{\Large \emph{by Till Tantau}}
-
-
-\bigskip
-\noindent
-In this part the library packages are documented. They provide additional
-predefined graphic objects like new arrow heads or new plot marks, but
-sometimes also extensions of the basic \pgfname\ or \tikzname\ system. The
-libraries are not loaded by default since many users will not need them.
-
-\medskip
-\noindent
-\begin{codeexample}[graphic=white,preamble={\usetikzlibrary{arrows,trees}}]
-\tikzset{
- ld/.style={level distance=#1},lw/.style={line width=#1},
- level 1/.style={ld=4.5mm, trunk, lw=1ex ,sibling angle=60},
- level 2/.style={ld=3.5mm, trunk!80!leaf a,lw=.8ex,sibling angle=56},
- level 3/.style={ld=2.75mm,trunk!60!leaf a,lw=.6ex,sibling angle=52},
- level 4/.style={ld=2mm, trunk!40!leaf a,lw=.4ex,sibling angle=48},
- level 5/.style={ld=1mm, trunk!20!leaf a,lw=.3ex,sibling angle=44},
- level 6/.style={ld=1.75mm,leaf a, lw=.2ex,sibling angle=40},
-}
-\pgfarrowsdeclare{leaf}{leaf}
- {\pgfarrowsleftextend{-2pt} \pgfarrowsrightextend{1pt}}
-{
- \pgfpathmoveto{\pgfpoint{-2pt}{0pt}}
- \pgfpatharc{150}{30}{1.8pt}
- \pgfpatharc{-30}{-150}{1.8pt}
- \pgfusepathqfill
-}
-
-\newcommand{\logo}[5]
-{
- \colorlet{border}{#1}
- \colorlet{trunk}{#2}
- \colorlet{leaf a}{#3}
- \colorlet{leaf b}{#4}
- \begin{tikzpicture}
- \scriptsize\scshape
- \draw[border,line width=1ex,yshift=.3cm,
- yscale=1.45,xscale=1.05,looseness=1.42]
- (1,0) to [out=90, in=0] (0,1) to [out=180,in=90] (-1,0)
- to [out=-90,in=-180] (0,-1) to [out=0, in=-90] (1,0) -- cycle;
-
- \coordinate (root) [grow cyclic,rotate=90]
- child {
- child [line cap=round] foreach \a in {0,1} {
- child foreach \b in {0,1} {
- child foreach \c in {0,1} {
- child foreach \d in {0,1} {
- child foreach \leafcolor in {leaf a,leaf b}
- { edge from parent [color=\leafcolor,-#5] }
- } } }
- } edge from parent [shorten >=-1pt,serif cm-,line cap=butt]
- };
-
- \node [align=center,below] at (0pt,-.5ex)
- { \textcolor{border}{T}heoretical \\ \textcolor{border}{C}omputer \\
- \textcolor{border}{S}cience };
- \end{tikzpicture}
-}
-\begin{minipage}{3cm}
- \logo{green!80!black}{green!25!black}{green}{green!80}{leaf}\\
- \logo{green!50!black}{black}{green!80!black}{red!80!green}{leaf}\\
- \logo{red!75!black}{red!25!black}{red!75!black}{orange}{leaf}\\
- \logo{black!50}{black}{black!50}{black!25}{}
-\end{minipage}
-\end{codeexample}
-
-
-\include{pgfmanual-en-library-3d}
-\include{pgfmanual-en-library-angles}
-\include{pgfmanual-en-library-arrows}
-\include{pgfmanual-en-library-automata}
-\include{pgfmanual-en-library-babel}
-\include{pgfmanual-en-library-backgrounds}
-\include{pgfmanual-en-library-calc}
-\include{pgfmanual-en-library-calendar}
-\include{pgfmanual-en-library-chains}
-\include{pgfmanual-en-library-circuits}
-\include{pgfmanual-en-library-decorations}
-\include{pgfmanual-en-library-er}
-\include{pgfmanual-en-library-external}
-\include{pgfmanual-en-library-fadings}
-\include{pgfmanual-en-library-fit}
-\include{pgfmanual-en-library-fixedpoint}
-\include{pgfmanual-en-library-fpu}
-\include{pgfmanual-en-library-lsystems}
-\include{pgfmanual-en-library-math}
-\include{pgfmanual-en-library-matrices}
-\include{pgfmanual-en-library-mindmaps}
-\include{pgfmanual-en-library-folding}
-\include{pgfmanual-en-library-patterns}
-\include{pgfmanual-en-library-perspective}
-\include{pgfmanual-en-library-petri}
-\include{pgfmanual-en-library-plot-handlers}
-\include{pgfmanual-en-library-plot-marks}
-\include{pgfmanual-en-library-profiler}
-\include{pgfmanual-en-library-rdf}
-\include{pgfmanual-en-library-shadings}
-\include{pgfmanual-en-library-shadows}
-\include{pgfmanual-en-library-shapes}
-\include{pgfmanual-en-library-spy}
-\include{pgfmanual-en-library-svg-path}
-\include{pgfmanual-en-library-edges}
-\include{pgfmanual-en-library-through}
-\include{pgfmanual-en-library-trees}
-\include{pgfmanual-en-library-turtle}
-\include{pgfmanual-en-library-views}
-
-
-
-\part{Data Visualization}
-\label{part-dv}
-
-{\Large \emph{by Till Tantau}}
-
-\bigskip
-\noindent
-
-\begin{codeexample}[graphic=white,preamble={\usetikzlibrary{datavisualization.formats.functions}}]
-\tikz \datavisualization [scientific axes=clean]
-[
- visualize as smooth line=Gaussian,
- Gaussian={pin in data={text={$e^{-x^2}$},when=x is 1}}
-]
-data [format=function] {
- var x : interval [-7:7] samples 51;
- func y = exp(-\value x*\value x);
-}
-[
- visualize as scatter,
- legend={south east outside},
- scatter={
- style={mark=*,mark size=1.4pt},
- label in legend={text={
- $\sum_{i=1}^{10} x_i$, where $x_i \sim U(-1,1) $}}}
-]
-data [format=function] {
- var i : interval [0:1] samples 20;
- func y = 0;
- func x = (rand + rand + rand + rand + rand +
- rand + rand + rand + rand + rand);
-};
-\end{codeexample}
-
-
-\include{pgfmanual-en-dv-introduction}
-\include{pgfmanual-en-dv-main}
-\include{pgfmanual-en-dv-formats}
-\include{pgfmanual-en-dv-axes}
-\include{pgfmanual-en-dv-visualizers}
-\include{pgfmanual-en-dv-stylesheets}
-\include{pgfmanual-en-dv-polar}
-\include{pgfmanual-en-dv-backend}
-
-
-
-\part{Utilities}
-\label{part-utilities}
-
-{\Large \emph{by Till Tantau}}
-
-
-\bigskip
-\noindent
-The utility packages are not directly involved in creating graphics, but you
-may find them useful nonetheless. All of them either directly depend on
-\pgfname\ or they are designed to work well together with \pgfname\ even though
-they can be used in a stand-alone way.
-
-\vskip2cm
-\medskip
-\noindent
-\begin{codeexample}[graphic=white]
-\begin{tikzpicture}[scale=2]
- \shade[top color=blue,bottom color=gray!50] (0,0) parabola (1.5,2.25) |- (0,0);
- \draw (1.05cm,2pt) node[above] {$\displaystyle\int_0^{3/2} \!\!x^2\mathrm{d}x$};
-
- \draw[help lines] (0,0) grid (3.9,3.9)
- [step=0.25cm] (1,2) grid +(1,1);
-
- \draw[->] (-0.2,0) -- (4,0) node[right] {$x$};
- \draw[->] (0,-0.2) -- (0,4) node[above] {$f(x)$};
-
- \foreach \x/\xtext in {1/1, 1.5/1\frac{1}{2}, 2/2, 3/3}
- \draw[shift={(\x,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\xtext$};
-
- \foreach \y/\ytext in {1/1, 2/2, 2.25/2\frac{1}{4}, 3/3}
- \draw[shift={(0,\y)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\ytext$};
-
- \draw (-.5,.25) parabola bend (0,0) (2,4) node[below right] {$x^2$};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\include{pgfmanual-en-pgfkeys}
-\include{pgfmanual-en-pgffor}
-\include{pgfmanual-en-pgfcalendar}
-\include{pgfmanual-en-pages}
-\include{pgfmanual-en-xxcolor}
-\include{pgfmanual-en-module-parser}
-
-
-
-\part{Mathematical and Object-Oriented Engines}
-
-{\Large \emph{by Mark Wibrow and Till Tantau}}
-
-
-\bigskip
-\noindent
-\pgfname\ comes with two useful engines: One for doing mathematics, one for
-doing object-oriented programming. Both engines can be used independently of
-the main \pgfname.
-
-The job of the mathematical engine is to support mathematical operations like
-addition, subtraction, multiplication and division, using both integers and
-non-integers, but also functions such as square-roots, sine, cosine, and
-generate pseudo-random numbers. Mostly, you will use the mathematical
-facilities of \pgfname\ indirectly, namely when you write a coordinate like
-|(5cm*3,6cm/4)|, but the mathematical engine can also be used independently of
-\pgfname\ and \tikzname.
-
-The job of the object-oriented engine is to support simple object-oriented
-programming in \TeX. It allows the definition of \emph{classes} (without
-inheritance), \emph{methods}, \emph{attributes} and \emph{objects}.
-
-\vskip1cm
-\begin{codeexample}[graphic=white]
-\pgfmathsetseed{1}
-\foreach \col in {black,red,green,blue}
-{
- \begin{tikzpicture}[x=10pt,y=10pt,ultra thick,baseline,line cap=round]
- \coordinate (current point) at (0,0);
- \coordinate (old velocity) at (0,0);
- \coordinate (new velocity) at (rand,rand);
-
- \foreach \i in {0,1,...,100}
- {
- \draw[\col!\i] (current point)
- .. controls ++([scale=-1]old velocity) and
- ++(new velocity) .. ++(rand,rand)
- coordinate (current point);
- \coordinate (old velocity) at (new velocity);
- \coordinate (new velocity) at (rand,rand);
- }
- \end{tikzpicture}
-}
-\end{codeexample}
-
-
-\include{pgfmanual-en-math-design}
-\include{pgfmanual-en-math-parsing}
-\include{pgfmanual-en-math-commands}
-\include{pgfmanual-en-math-algorithms}
-\include{pgfmanual-en-math-numberprinting}
-\include{pgfmanual-en-oo}
-
-
-
-\part{The Basic Layer}
-
-{\Large \emph{by Till Tantau}}
-
-
-\bigskip
-\noindent
-\vskip1cm
-\begin{codeexample}[graphic=white]
-\begin{tikzpicture}
- \draw[gray,very thin] (-1.9,-1.9) grid (2.9,3.9)
- [step=0.25cm] (-1,-1) grid (1,1);
- \draw[blue] (1,-2.1) -- (1,4.1); % asymptote
-
- \draw[->] (-2,0) -- (3,0) node[right] {$x(t)$};
- \draw[->] (0,-2) -- (0,4) node[above] {$y(t)$};
-
- \foreach \pos in {-1,2}
- \draw[shift={(\pos,0)}] (0pt,2pt) -- (0pt,-2pt) node[below] {$\pos$};
-
- \foreach \pos in {-1,1,2,3}
- \draw[shift={(0,\pos)}] (2pt,0pt) -- (-2pt,0pt) node[left] {$\pos$};
-
- \fill (0,0) circle (0.064cm);
- \draw[thick,parametric,domain=0.4:1.5,samples=200]
- % The plot is reparameterised such that there are more samples
- % near the center.
- plot[id=asymptotic-example] function{(t*t*t)*sin(1/(t*t*t)),(t*t*t)*cos(1/(t*t*t))}
- node[right] {$\bigl(x(t),y(t)\bigr) = (t\sin \frac{1}{t}, t\cos \frac{1}{t})$};
-
- \fill[red] (0.63662,0) circle (2pt)
- node [below right,fill=white,yshift=-4pt] {$(\frac{2}{\pi},0)$};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\include{pgfmanual-en-base-design}
-\include{pgfmanual-en-base-scopes}
-\include{pgfmanual-en-base-points}
-\include{pgfmanual-en-base-paths}
-\include{pgfmanual-en-base-decorations}
-\include{pgfmanual-en-base-actions}
-\include{pgfmanual-en-base-arrows}
-\include{pgfmanual-en-base-nodes}
-\include{pgfmanual-en-base-matrices}
-\include{pgfmanual-en-base-transformations}
-\include{pgfmanual-en-base-patterns}
-\include{pgfmanual-en-base-images}
-\include{pgfmanual-en-base-external}
-\include{pgfmanual-en-base-plots}
-\include{pgfmanual-en-base-layers}
-\include{pgfmanual-en-base-shadings}
-\include{pgfmanual-en-base-transparency}
-\include{pgfmanual-en-base-animations}
-\include{pgfmanual-en-base-internalregisters}
-\include{pgfmanual-en-base-quick}
-
-
-
-\part{The System Layer}
-\label{part-system}
-
-{\Large \emph{by Till Tantau}}
-
-
-\bigskip
-\noindent
-This part describes the low-level interface of \pgfname, called the
-\emph{system layer}. This interface provides a complete abstraction of the
-internals of the underlying drivers.
-
-Unless you intend to port \pgfname\ to another driver or unless you intend to
-write your own optimized frontend, you need not read this part.
-
-In the following it is assumed that you are familiar with the basic workings of
-the |graphics| package and that you know what \TeX-drivers are and how they
-work.
-
-\vskip1cm
-\begin{codeexample}[graphic=white]
-\begin{tikzpicture}
- [shorten >=1pt,->,
- vertex/.style={circle,fill=black!25,minimum size=17pt,inner sep=0pt}]
-
- \foreach \name/\x in {s/1, 2/2, 3/3, 4/4, 15/11, 16/12, 17/13, 18/14, 19/15, t/16}
- \node[vertex] (G-\name) at (\x,0) {$\name$};
-
- \foreach \name/\angle/\text in {P-1/234/5, P-2/162/6, P-3/90/7, P-4/18/8, P-5/-54/9}
- \node[vertex,xshift=6cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$};
-
- \foreach \name/\angle/\text in {Q-1/234/10, Q-2/162/11, Q-3/90/12, Q-4/18/13, Q-5/-54/14}
- \node[vertex,xshift=9cm,yshift=.5cm] (\name) at (\angle:1cm) {$\text$};
-
- \foreach \from/\to in {s/2,2/3,3/4,3/4,15/16,16/17,17/18,18/19,19/t}
- \draw (G-\from) -- (G-\to);
-
- \foreach \from/\to in {1/2,2/3,3/4,4/5,5/1,1/3,2/4,3/5,4/1,5/2}
- { \draw (P-\from) -- (P-\to); \draw (Q-\from) -- (Q-\to); }
-
- \draw (G-3) .. controls +(-30:2cm) and +(-150:1cm) .. (Q-1);
- \draw (Q-5) -- (G-15);
-\end{tikzpicture}
-\end{codeexample}
-
-
-\include{pgfmanual-en-pgfsys-overview}
-\include{pgfmanual-en-pgfsys-commands}
-\include{pgfmanual-en-pgfsys-paths}
-\include{pgfmanual-en-pgfsys-protocol}
-\include{pgfmanual-en-pgfsys-animations}
-
-
-
-\part{References and Index}
-
-\vskip1cm
-\begin{codeexample}[graphic=white]
-\begin{tikzpicture}
- \draw[line width=0.3cm,color=red!30,line cap=round,line join=round] (0,0)--(2,0)--(2,5);
- \draw[help lines] (-2.5,-2.5) grid (5.5,7.5);
- \draw[very thick] (1,-1)--(-1,-1)--(-1,1)--(0,1)--(0,0)--
- (1,0)--(1,-1)--(3,-1)--(3,2)--(2,2)--(2,3)--(3,3)--
- (3,5)--(1,5)--(1,4)--(0,4)--(0,6)--(1,6)--(1,5)
- (3,3)--(4,3)--(4,5)--(3,5)--(3,6)
- (3,-1)--(4,-1);
- \draw[below left] (0,0) node(s){$s$};
- \draw[below left] (2,5) node(t){$t$};
- \fill (0,0) circle (0.06cm) (2,5) circle (0.06cm);
- \draw[->,rounded corners=0.2cm,shorten >=2pt]
- (1.5,0.5)-- ++(0,-1)-- ++(1,0)-- ++(0,2)-- ++(-1,0)-- ++(0,2)-- ++(1,0)--
- ++(0,1)-- ++(-1,0)-- ++(0,-1)-- ++(-2,0)-- ++(0,3)-- ++(2,0)-- ++(0,-1)--
- ++(1,0)-- ++(0,1)-- ++(1,0)-- ++(0,-1)-- ++(1,0)-- ++(0,-3)-- ++(-2,0)--
- ++(1,0)-- ++(0,-3)-- ++(1,0)-- ++(0,-1)-- ++(-6,0)-- ++(0,3)-- ++(2,0)--
- ++(0,-1)-- ++(1,0);
-\end{tikzpicture}
-\end{codeexample}
-
-\printindex
-
-%\typeout{Examples: \the\codeexamplecount}%
-\end{document}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "~/pgf/doc/generic/pgf/version-for-luatex/en/pgfmanual"
-%%% coding: iso-latin-1-unix
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-main-preamble.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-main-preamble.tex
deleted file mode 100644
index c26b542951..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-main-preamble.tex
+++ /dev/null
@@ -1,384 +0,0 @@
-% 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.
-
-
-% pgf version is defined in \pgfversion in file
-% generic/pgf/utilities/pgfrcs.code.tex
-
-\def\xcolorversion{2.00}
-
-\usepackage[version=latest]{pgf}
-
-\usepackage{xkeyval,calc,listings,tikz,fp}
-
-\usepackage{imakeidx}
-\makeindex
-\usepackage{hyperref}
-\hypersetup{%
- colorlinks=false, % use true to enable colors below:
- linkcolor=blue,%red,
- filecolor=blue,%magenta,
- urlcolor=blue,%cyan,
- citecolor=blue,
- pdfborder=0 0 0,
-}
-
-% We need lots of libraries...
-\usetikzlibrary{
- 3d,
- arrows,
- arrows.spaced,
- arrows.meta,
- bending,
- babel,
- calc,
- fit,
- patterns,
- patterns.meta,
- plotmarks,
- shapes.geometric,
- shapes.misc,
- shapes.symbols,
- shapes.arrows,
- shapes.callouts,
- shapes.multipart,
- shapes.gates.logic.US,
- shapes.gates.logic.IEC,
- circuits.logic.US,
- circuits.logic.IEC,
- circuits.logic.CDH,
- circuits.ee.IEC,
- datavisualization,
- datavisualization.polar,
- datavisualization.formats.functions,
- er,
- automata,
- backgrounds,
- chains,
- topaths,
- trees,
- petri,
- mindmap,
- matrix,
- calendar,
- folding,
- fadings,
- shadings,
- spy,
- through,
- turtle,
- positioning,
- scopes,
- decorations.fractals,
- decorations.shapes,
- decorations.text,
- decorations.pathmorphing,
- decorations.pathreplacing,
- decorations.footprints,
- decorations.markings,
- shadows,
- lindenmayersystems,
- intersections,
- fixedpointarithmetic,
- fpu,
- svg.path,
- external,
- graphs,
- graphs.standard,
- quotes,
- math,
- angles,
- views,
- animations,
- rdf,
- perspective,
-}
-
-\usepackage{ifluatex}
-\newif\ifgdccodebasic
-\newif\ifgdccodeogdf
-
-\ifluatex
-
- \usetikzlibrary{graphdrawing}
- \usegdlibrary{trees,circular,layered,examples,force,phylogenetics,routing}
-
- % Test whether C code is available:
- \directlua{
- if pcall(require,'pgf_gd_examples_c_SimpleDemoC') then
- tex.print('\string\\gdccodebasictrue')
- end
- }
-
- \ifgdccodebasic
- \usegdlibrary{pgf_gd_examples_c_SimpleDemoC,pgf_gd_examples_c_SimpleDemoCPlusPlus}
-
- % Test whether OGDF code is available:
- \directlua{
- if pcall(require,'pgf_gd_ogdf_c_SimpleDemoOGDF') then
- tex.print('\string\\gdccodeogdftrue')
- end
- }
-
- \ifgdccodeogdf
- \usegdlibrary{pgf_gd_ogdf_c_SimpleDemoOGDF,ogdf}
- \fi
-
- \fi
-
-\fi
-
-\def\LuaTeX{Lua\TeX}%
-
-
-\newif\ifpgfmanualexternalize
-\pgfmanualexternalizefalse
-\ifpgfmanualexternalize
- \tikzexternalize[
- mode=list only,export=true,% simply skips EVERY picture -> good for debugging the text.
- ]{pgfmanual}
-
- \tikzifexternalizing{%
- \pgfkeys{/pdflinks/codeexample links=false}%
- }{}%
-\fi
-
-
-\usepackage[a4paper,left=2.25cm,right=2.25cm,top=2.5cm,bottom=2.5cm,nohead]{geometry}
-\usepackage{amsmath,amssymb}
-\usepackage{xxcolor}
-\usepackage{pifont}
-
-\ifluatex
-% \usepackage[no-math]{fontspec}
-% \usepackage{luatextra}
-
- % TT: I have commented luatextra since it loads fontspec, which
- % currently breaks "$\mathrm{\Omega}$" (nothing is
- % shown). Also, fontspec loads so much stuff, I'm not really sure
- % any of it is needed...
-
- % \filedescription is defined in expl3, required by fontspec,
- % required by luatextra. Needs to be \relaxed since
- % pgfmanual-en-macros.tex defines an environment named filedescription
- \let\filedescription\relax
- \usepackage[utf8]{luainputenc}
- % dvisvgm does not support OpenType fonts so we have to bite the bullet and
- % use T1 where quotes are weird. In LuaTeX \outputmode=0 means DVI.
- \ifnum\outputmode=0
- \usepackage[T1]{fontenc}
- \fi
-\else
- \usepackage[utf8]{inputenc}
- \usepackage[T1]{fontenc}
-\fi
-
-\graphicspath{{../../images/}}
-\input{pgfmanual-en-macros}
-
-\usepackage{todonotes}
-\newcommand\todosp[2][]{% % Stefan Pinnow
- \todo[
- disable,
- color=blue!40,
- #1]{#2}
-}
-
-\makeatletter
-\renewcommand*\l@section[2]{%
- \ifnum \c@tocdepth >\z@
- \addpenalty\@secpenalty
- \addvspace{1.0em \@plus\p@}%
- \setlength\@tempdima{2.5em}%
- \begingroup
- \parindent \z@ \rightskip \@pnumwidth
- \parfillskip -\@pnumwidth
- \leavevmode \bfseries
- \advance\leftskip\@tempdima
- \hskip -\leftskip
- #1\nobreak\hfil \nobreak\hb@xt@\@pnumwidth{\hss #2}\par
- \endgroup
- \fi}
-\renewcommand*\l@subsection{\@dottedtocline{2}{2.5em}{3.3em}}
-\renewcommand*\l@subsubsection{\@dottedtocline{3}{5.8em}{4.2em}}
-\def\@pnumwidth{2.2em}
-\makeatother
-
-%\includeonly{pgfmanual-en-library-profiler}
-
-% Global styles:
-\tikzset{
- every plot/.style={prefix=plots/pgf-},
- shape example/.style={
- color=black!30,
- draw,
- fill=yellow!30,
- line width=.5cm,
- inner xsep=2.5cm,
- inner ysep=0.5cm}
-}
-
-\index{Options for graphics|see{Graphic options and styles}}
-\index{Styles for graphics|see{Graphic options and styles}}
-\index{Options for packages|see{Package options}}
-\index{Handlers for keys|see{Key handlers}}
-\index{File|see{Packages and files}}
-\index{Layout|see{Page layout}}
-\index{Node|see{Predefined node}}
-\index{Data formats|see{Formats}}
-
-
-% Animations:
-
-\tikzset{make snapshot if necessary}
-
-% Detect changed labels
-% by David Carlisle https://tex.stackexchange.com/a/169245
-\makeatletter
-\def\@testdef#1#2#3{%
- \def\reserved@a{#3}%
- \expandafter\ifx\csname #1@#2\endcsname\reserved@a\else
- \typeout{^^JLabel `#2' changed:^^J\meaning\reserved@a^^J\expandafter\meaning\csname #1@#2\endcsname^^J}%
- \@tempswatrue
- \fi}
-\makeatother
-
-%% -----------------------------------------------------------------------------
-%\includeonly{
-%% pgfmanual-en-introduction,
-%% pgfmanual-en-tutorial,
-%% pgfmanual-en-tutorial-nodes,
-%% pgfmanual-en-tutorial-Euclid,
-%% pgfmanual-en-tutorial-chains,
-%% pgfmanual-en-tutorial-map,
-%% pgfmanual-en-guidelines,
-%% pgfmanual-en-installation,
-%% pgfmanual-en-license,
-%% pgfmanual-en-drivers,
-%% pgfmanual-en-tikz-design,
-%% pgfmanual-en-tikz-scopes,
-%% pgfmanual-en-tikz-coordinates,
-%% pgfmanual-en-tikz-paths,
-%% pgfmanual-en-tikz-actions,
-%% pgfmanual-en-tikz-arrows,
-%% pgfmanual-en-tikz-shapes,
-%% pgfmanual-en-tikz-pics,
-%% pgfmanual-en-tikz-graphs,
-%% pgfmanual-en-tikz-matrices,
-%% pgfmanual-en-tikz-trees,
-%% pgfmanual-en-tikz-plots,
-%% pgfmanual-en-tikz-transparency,
-%% pgfmanual-en-tikz-decorations,
-%% pgfmanual-en-tikz-transformations,
-%% pgfmanual-en-tikz-animations,
-%% pgfmanual-en-gd-overview,
-%% pgfmanual-en-gd-usage-tikz,
-%% pgfmanual-en-gd-usage-pgf,
-%% pgfmanual-en-gd-trees,
-%% pgfmanual-en-gd-layered,
-%% pgfmanual-en-gd-force,
-%% pgfmanual-en-gd-circular,
-%% pgfmanual-en-gd-phylogenetics,
-%% pgfmanual-en-gd-edge-routing,
-%%% pgfmanual-en-gd-ogdf,
-%% pgfmanual-en-gd-algorithm-layer,
-%% pgfmanual-en-gd-algorithms-in-c,
-%% pgfmanual-en-gd-display-layer,
-%% pgfmanual-en-gd-binding-layer,
-%% pgfmanual-en-library-angles,
-%% pgfmanual-en-library-arrows,
-%% pgfmanual-en-library-automata,
-%% pgfmanual-en-library-babel,
-%% pgfmanual-en-library-backgrounds,
-%% pgfmanual-en-library-calc,
-%% pgfmanual-en-library-calendar,
-%% pgfmanual-en-library-chains,
-%% pgfmanual-en-library-circuits,
-%% pgfmanual-en-library-decorations,
-%% pgfmanual-en-library-er,
-%% pgfmanual-en-library-external,
-%% pgfmanual-en-library-fadings,
-%% pgfmanual-en-library-fit,
-%% pgfmanual-en-library-fixedpoint,
-%% pgfmanual-en-library-fpu,
-%% pgfmanual-en-library-lsystems,
-%% pgfmanual-en-library-math,
-%% pgfmanual-en-library-matrices,
-%% pgfmanual-en-library-mindmaps,
-%% pgfmanual-en-library-folding,
-%% pgfmanual-en-library-patterns,
-%% pgfmanual-en-library-petri,
-%% pgfmanual-en-library-plot-handlers,
-%% pgfmanual-en-library-plot-marks,
-%% pgfmanual-en-library-profiler,
-%% pgfmanual-en-library-rdf,
-%% pgfmanual-en-library-shadings,
-%% pgfmanual-en-library-shadows,
-%% pgfmanual-en-library-shapes,
-%% pgfmanual-en-library-spy,
-%% pgfmanual-en-library-svg-path,
-%% pgfmanual-en-library-edges,
-%% pgfmanual-en-library-through,
-%% pgfmanual-en-library-trees,
-%% pgfmanual-en-library-turtle,
-%% pgfmanual-en-library-views,
-%% pgfmanual-en-dv-introduction,
-%% pgfmanual-en-dv-main,
-%% pgfmanual-en-dv-formats,
-%% pgfmanual-en-dv-axes,
-%% pgfmanual-en-dv-visualizers,
-%% pgfmanual-en-dv-stylesheets,
-%% pgfmanual-en-dv-polar,
-%% pgfmanual-en-dv-backend,
-%% pgfmanual-en-pgfkeys,
-%% pgfmanual-en-pgffor,
-%% pgfmanual-en-pgfcalendar,
-%% pgfmanual-en-pages,
-%% pgfmanual-en-xxcolor,
-%% pgfmanual-en-module-parser,
-%% pgfmanual-en-math-design,
-%% pgfmanual-en-math-parsing,
-%% pgfmanual-en-math-commands,
-%% pgfmanual-en-math-algorithms,
-%% pgfmanual-en-math-numberprinting,
-%% pgfmanual-en-oo,
-%% pgfmanual-en-base-design,
-%% pgfmanual-en-base-scopes,
-%% pgfmanual-en-base-points,
-%% pgfmanual-en-base-paths,
-%% pgfmanual-en-base-decorations,
-%% pgfmanual-en-base-actions,
-%% pgfmanual-en-base-arrows,
-%% pgfmanual-en-base-nodes,
-%% pgfmanual-en-base-matrices,
-%% pgfmanual-en-base-transformations,
-%% pgfmanual-en-base-patterns,
-%% pgfmanual-en-base-images,
-%% pgfmanual-en-base-external,
-%% pgfmanual-en-base-plots,
-%% pgfmanual-en-base-layers,
-%% pgfmanual-en-base-shadings,
-%% pgfmanual-en-base-transparency,
-%% pgfmanual-en-base-animations,
-%% pgfmanual-en-base-internalregisters,
-%% pgfmanual-en-base-quick,
-%% pgfmanual-en-pgfsys-overview,
-%% pgfmanual-en-pgfsys-commands,
-%% pgfmanual-en-pgfsys-paths,
-%% pgfmanual-en-pgfsys-protocol,
-%% pgfmanual-en-pgfsys-animations,
-%}
-%% -----------------------------------------------------------------------------
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "~/pgf/doc/generic/pgf/version-for-luatex/en/pgfmanual"
-%%% coding: iso-latin-1-unix
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-main.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-main.tex
deleted file mode 100644
index b7349247dc..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-main.tex
+++ /dev/null
@@ -1,16 +0,0 @@
-% Copyright 2018 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.
-
-\input{pgfmanual-en-main-preamble.tex}
-\input{pgfmanual-en-main-body.tex}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-math-algorithms.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-math-algorithms.tex
deleted file mode 100644
index 9a4daeeaff..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-math-algorithms.tex
+++ /dev/null
@@ -1,231 +0,0 @@
-% Copyright 2019 by Mark Wibrow
-%
-% 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{Customizing the Mathematical Engine}
-\label{pgfmath-reimplement}
-
-Perhaps you have a desire for some function that \pgfname\ does not provide.
-Perhaps you are not happy with the accuracy or efficiency of some of the
-algorithms that are implemented in \pgfname. In these cases you will want to
-add a function to the parser or replace the current implementations of the
-algorithms with your own code.
-
-The mathematical engine was designed with such customization in mind. It is
-possible to add new functions, or modify the code for existing functions. Note,
-however, that whilst adding new operators is possible, it can be a rather
-tricky business and is only recommended for adventurous users.
-
-To add a new function to the math engine the following command can be used:
-
-\begin{command}{\pgfmathdeclarefunction\opt{|*|}\marg{function name}\marg{number of arguments}\marg{code}}
- This will set up the parser to recognize a function called \meta{name}. The
- name of the function can consist of, uppercase or lowercase letters,
- numbers or the underscore |_|. In line with many programming languages, a
- function name cannot begin with a number or contain any spaces. The
- function may not have been declared earlier, unless the optional star (|*|)
- is provided, which forces an ``overwriting'' of the function by the new
- function. Note that you \emph{should never change the arity of standard
- functions} and you should normally use |\pgfmathredeclarefunction|,
- which does not allow you to do anything wrong here.
-
- The \meta{number of arguments} can be any positive integer, zero, or the
- value |...|, which indicates a variable number of arguments. \pgfname{}
- treats constants, such as |pi| and |e|, as functions with zero arguments.
- Functions with more than nine arguments or with a variable number of
- arguments are a ``bit special'' and are discussed below.
-
- The effect of \meta{code} should be to set the macro |\pgfmathresult| to
- the correct value (namely to the result of the computation without units).
- Furthermore, the function should have no other side effects, that is, it
- should not change any global values. As an example, consider the creation
- of a new function |double|, which takes one argument, and returns the value
- of that argument times two.
- %
-\begin{codeexample}[]
-\makeatletter
-\pgfmathdeclarefunction{double}{1}{
- \begingroup
- \pgf@x=#1pt\relax
- \multiply\pgf@x by2\relax
- \pgfmathreturn\pgf@x
- \endgroup
-}
-\makeatother
-\pgfmathparse{double(44.3)}\pgfmathresult
-\end{codeexample}
-
- The macro |\pgfmathreturn|\meta{tokens} must be
- directly followed by an |\endgroup| and will save the result of the
- computation, by defining |\pgfmathresult| as the expansion of
- \meta{tokens} (without units) outside the group, so \meta{tokens}
- must be something that can be assigned to a dimension register.
-
- Alternatively, the |\pgfmathsmuggle|\meta{macro} can be used. This must
- also be directly followed by an |\endgroup| and will simply ``smuggle'' the
- definition of \meta{macro} outside the \TeX-group.
-
- By performing computations within a \TeX-group, \pgfname{} registers such
- as |\pgf@x|, |\pgf@y| and |\c@pgf@counta|, |\c@pgfcountb|, and so forth,
- can be used at will.
-
- Beyond setting up the parser, this command also defines two macros which
- provide access to the function independently of the parser:
- %
- \begin{itemize}
- \item |\pgfmath|\meta{function name}
-
- This macro will provide a ``public'' interface for the function
- \meta{function name} allowing the function to be called
- independently of the parser. All arguments passed to this macro are
- evaluated using |\pgfmathparse| and then passed on to the following
- macro:
- \item |\pgfmath|\meta{function name}|@|
-
- This macro is the ``private'' implementation of the function's
- algorithm (but note that, for speed, the parser calls this macro
- rather than the ``public'' one). Arguments passed to this macro are
- expected to be numbers without units. It is defined using
- \meta{code}, but need not be self-contained.
- \end{itemize}
-
- For functions that are declared with less than ten arguments, the public
- macro is defined in the same way as normal \TeX{} macros using, for
- example, |\def\pgfmathNoArgs{|\meta{code}|}| for a function with no
- arguments, or |\def\pgfmathThreeArgs#1#2#3{|\meta{code}|}| for a function
- with three arguments. The private macro is defined in the same way, and
- each argument can therefore be accessed in \meta{code} using |#1|, |#2| and
- so on.
-
- For functions with more than nine arguments, or functions with a variable
- number of arguments, these macros are only defined as taking \emph{one}
- argument. The public macro expects its arguments to be comma separated, for
- example, |\pgfmathVariableArgs{1.1,3.5,-1.5,2.6}|. Each argument is parsed
- and passed on to the private macro as follows:
- |\pgfmathVariableArgs@{{1.1}{3.5}{-1.5}{2.6}}|. This means that some
- ``extra work'' will be required to access each argument (although it is a
- fairly simple task).
-
- Note that there are two exceptions to this arrangement: the public versions
- of the |min| and |max| functions still take two arguments for compatibility
- with older versions, but each of these arguments can take several comma
- separated values.
-\end{command}
-
-To redefine a function use the following command:
-
-\begin{command}{\pgfmathredeclarefunction\marg{function name}\marg{code}}
- This command redefines the |\pgfmath|\meta{function name}|@| macro with the
- new \meta{code}. See the description of the
- |\pgfmathdeclarefunction| for details. You cannot change the number of
- arguments for an existing function.
- %
-\begin{codeexample}[]
-\makeatletter
-\pgfmathdeclarefunction{foo}{1}{
- \begingroup
- \pgf@x=#1pt\relax
- \multiply\pgf@x by2\relax
- \pgfmathreturn\pgf@x
- \endgroup
-}
-\pgfmathparse{foo(42)}\pgfmathresult
-\pgfmathredeclarefunction{foo}{
- \begingroup
- \pgf@x=#1pt\relax
- \multiply\pgf@x by3\relax
- \pgfmathreturn\pgf@x
- \endgroup
-}
-\pgfmathparse{foo(42)}\pgfmathresult
-\makeatother
-\end{codeexample}
- %
-\end{command}
-
- \pgfname{} uses the last known definition of a function within the
- prevailing scope, so it is possible for a function to be redefined locally.
- You should also remember that any |.sty| or |.tex| file containing any
- re-implementations should be loaded after |pgfmath|.
-
- In addition to the above commands, the following key is provided to quickly
- create simple ad hoc functions which can greatly improve the readability of
- code, and is particularly useful in \tikzname{}:
-
-\begin{key}{/pgf/declare function=\meta{function definitions}}
- This key allows simple functions to be created locally. Its use is perhaps
- best illustrated by an example:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- \draw [blue, thick, x=0.0085cm, y=1cm,
- declare function={
- sines(\t,\a,\b)=1 + 0.5*(sin(\t)+sin(\t*\a)+sin(\t*\b));
- }]
- plot [domain=0:360, samples=144, smooth] (\x,{sines(\x,3,5)});
-\end{tikzpicture}
-\end{codeexample}
-
- Each definition in \meta{function definitions} takes the form
- \meta{name}|(|\meta{arguments}|)=|\meta{definition}|;| (note the semicolon
- at the end, this is very important). If multiple functions are being
- defined, the semicolon is used to separate them (\emph{not} a comma). The
- function \meta{name} can be any name that is not already a function name in
- the current scope. The list of \meta{arguments} are commands such as |\x|,
- or |\y| (it is not possible to declare functions that take variable numbers
- of arguments using this key). If the function takes no arguments, then the
- parentheses need not be used. The \meta{definition} should be an expression
- that can be parsed by the mathematical engine and should use the commands
- specified in \meta{arguments}.
-
- When specifying multiple functions, functions that appear later on in
- \meta{function definitions} can refer to earlier functions:
- %
-\begin{codeexample}[pre={\pgfmathsetseed{1}}]
-\begin{tikzpicture}[
- declare function={
- excitation(\t,\w) = sin(\t*\w);
- noise = rnd - 0.5;
- source(\t) = excitation(\t,20) + noise;
- filter(\t) = 1 - abs(sin(mod(\t, 90)));
- speech(\t) = 1 + source(\t)*filter(\t);
- }
-]
- \draw [help lines] (0,0) grid (3,2);
- \draw [blue, thick, x=0.0085cm, y=1cm] (0,1) --
- plot [domain=0:360, samples=144, smooth] (\x,{speech(\x)});
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/declare function/execute at begin function=\meta{tokens}}
- These \meta{tokens} are inserted just before |\pgfmathdeclarefunction|
- scans the body of the function definition. This is a rather low-level
- option, so you should read the implementation to figure out where the
- \meta{tokens} are inserted.
-\end{key}
-
-\begin{key}{/pgf/declare function/execute at end function=\meta{tokens}}
- These \meta{tokens} are inserted just after |\pgfmathdeclarefunction| has
- finished scanning the body of the function definition. This is a rather
- low-level option, so you should read the implementation to figure out where
- the \meta{tokens} are inserted.
-\end{key}
-
-\begin{key}{/pgf/declare function/ignore spaces=\meta{boolean}}
- Uses the two previously described keys |/pgf/declare function/execute at begin function| and
- |/pgf/declare function/execute at end function| to install catcodes such
- that spaces inside the body of the function definition of
- |\pgfmathdeclarefunction| are ignored. The usual \TeX\ tokenization rules
- apply, so if the body of the function had already been tokenized by other
- means this will become ineffective. If you want to use a space you can use
- |~| in the function body which has its catcode set to 10 (space).
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-math-commands.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-math-commands.tex
deleted file mode 100644
index 393c0842d0..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-math-commands.tex
+++ /dev/null
@@ -1,246 +0,0 @@
-% Copyright 2018 by Mark Wibrow
-%
-% 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{Additional Mathematical Commands}
-\label{pgfmath-commands}
-
-Instead of parsing and evaluating complex expressions, you can also use the
-mathematical engine to evaluate a single mathematical operation. The macros
-used for many of these computations are listed above in
-Section~\ref{pgfmath-functions}. \pgfname{} also provides some additional
-commands which are shown below:
-
-
-\subsection{Basic arithmetic functions}
-\label{pgfmath-commands-basic}
-
-In addition to the commands described in Section~\ref{pgfmath-functions-basic},
-the following command is provided:
-
-\begin{command}{\pgfmathreciprocal\marg{x}}
- Defines |\pgfmathresult| as $1\div\meta{x}$. This provides greatest
- accuracy when \mvar{x} is small.
-\end{command}
-
-
-\subsection{Comparison and logical functions}
-
-In addition to the commands described in
-Section~\ref{pgfmath-functions-comparison}, the following command was provided
-by Christian Feuers\"anger:
-
-\begin{command}{\pgfmathapproxequalto\marg{x}\marg{y}}
- Defines |\pgfmathresult| 1.0 if $ \rvert \meta{x} - \meta{y} \lvert <
- 0.0001$, but 0.0 otherwise. As a side-effect, the global boolean
- |\ifpgfmathcomparison| will be set accordingly.
-\end{command}
-
-
-\subsection{Pseudo-Random Numbers}
-\label{pgfmath-random}
-
-In addition to the commands described in
-Section~\ref{pgfmath-functions-random}, the following commands are provided:
-
-\begin{command}{\pgfmathgeneratepseudorandomnumber}
- Defines |\pgfmathresult| as a pseudo-random integer between 1 and
- $2^{31}-1$. This uses a linear congruency generator, based on ideas of
- Erich Janka.
-\end{command}
-
-\begin{command}{\pgfmathrandominteger\marg{macro}\marg{minimum}\marg{maximum}}
- This defines \meta{macro} as a pseudo-randomly generated integer from the
- range \meta{minimum} to \meta{maximum} (inclusive).
- %
-\begin{codeexample}[]
-\begin{pgfpicture}
- \foreach \x in {1,...,50}{
- \pgfmathrandominteger{\a}{1}{50}
- \pgfmathrandominteger{\b}{1}{50}
- \pgfpathcircle{\pgfpoint{+\a pt}{+\b pt}}{+2pt}
- \color{blue!40!white}
- \pgfsetstrokecolor{blue!80!black}
- \pgfusepath{stroke, fill}
- }
-\end{pgfpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathdeclarerandomlist\marg{list name}{\ttfamily\{}\marg{item-1}\marg{item-2}...{\ttfamily\}}}
- This creates a list of items with the name \meta{list name}.
-\end{command}
-
-\begin{command}{\pgfmathrandomitem\marg{macro}\marg{list name}}
- Select an item from a random list \meta{list name}. The
- selected item is placed in \meta{macro}.
-\end{command}
-
-\begin{codeexample}[]
-\begin{pgfpicture}
- \pgfmathdeclarerandomlist{color}{{red}{blue}{green}{yellow}{white}}
- \foreach \a in {1,...,50}{
- \pgfmathrandominteger{\x}{1}{85}
- \pgfmathrandominteger{\y}{1}{85}
- \pgfmathrandominteger{\r}{5}{10}
- \pgfmathrandomitem{\c}{color}
- \pgfpathcircle{\pgfpoint{+\x pt}{+\y pt}}{+\r pt}
- \color{\c!40!white}
- \pgfsetstrokecolor{\c!80!black}
- \pgfusepath{stroke, fill}
- }
-\end{pgfpicture}
-\end{codeexample}
-
-\begin{command}{\pgfmathsetseed\marg{integer}}
- Explicitly sets the seed for the pseudo-random number generator. By default
- it is set to the value of |\time|$\times$|\year|.
-\end{command}
-
-
-\subsection{Base Conversion}
-\label{pgfmath-bases}
-
-\pgfname{} provides limited support for conversion between
-\emph{representations} of numbers. Currently the numbers must be positive
-integers in the range $0$ to $2^{31}-1$, and the bases in the range $2$ to
-$36$. All digits representing numbers greater than 9 (in base ten), are
-alphabetic, but may be upper or lower case.
-
-In addition to the commands described in Section~\ref{pgfmath-functions-base},
-the following commands are provided:
-
-\begin{command}{\pgfmathbasetodec\marg{macro}\marg{number}\marg{base}}
- Defines \meta{macro} as the result of converting \meta{number} from base
- \meta{base} to base 10. Alphabetic digits can be upper or lower case.
-
-\medskip{\def\medskip{}
-
-\begin{codeexample}[]
-\pgfmathbasetodec\mynumber{107f}{16} \mynumber
-\end{codeexample}
-
- \noindent Note that, as usual in \TeX, the braces around an argument can be
- omitted if the argument is just a single token (a macro name is a single
- token).
- %
-\begin{codeexample}[]
-\pgfmathbasetodec\mynumber{33FC}{20} \mynumber
-\end{codeexample}
-
-}\medskip
- %
-\end{command}
-
-\begin{command}{\pgfmathdectobase\marg{macro}\marg{number}\marg{base}}
- Defines \meta{macro} as the result of converting \meta{number} from base 10
- to base \meta{base}. Any resulting alphabetic digits are in \emph{lower
- case}.
- %
-\begin{codeexample}[]
-\pgfmathdectobase\mynumber{65535}{16} \mynumber
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathdectoBase\marg{macro}\marg{number}\marg{base}}
- Defines \meta{macro} as the result of converting \meta{number} from base 10
- to base \meta{base}. Any resulting alphabetic digits are in \emph{upper
- case}.
- %
-\begin{codeexample}[]
-\pgfmathdectoBase\mynumber{65535}{16} \mynumber
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathbasetobase\marg{macro}\marg{number}\marg{base-1}\marg{base-2}}
- Defines \meta{macro} as the result of converting \meta{number} from base
- \meta{base-1} to base \meta{base-2}. Alphabetic digits in \meta{number} can
- be upper or lower case, but any resulting alphabetic digits are in
- \emph{lower case}.
- %
-\begin{codeexample}[]
-\pgfmathbasetobase\mynumber{11011011}{2}{16} \mynumber
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathbasetoBase\marg{macro}\marg{number}\marg{base-1}\marg{base-2}}
- Defines \meta{macro} as the result of converting \meta{number} from base
- \meta{base-1} to base \meta{base-2}. Alphabetic digits in \meta{number} can
- be upper or lower case, but any resulting alphabetic digits are in
- \emph{upper case}.
- %
-\begin{codeexample}[]
-\pgfmathbasetoBase\mynumber{121212}{3}{12} \mynumber
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathsetbasenumberlength\marg{integer}}
- Sets the number of digits in the result of a base conversion to
- \meta{integer}. If the result of a conversion has less digits than this
- number, it is prefixed with zeros.
- %
-\begin{codeexample}[]
-\pgfmathsetbasenumberlength{8}
-\pgfmathdectobase\mynumber{15}{2} \mynumber
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathtodigitlist\marg{macro}\marg{number}}
- This command converts \meta{number} into a comma-separated list of digits
- and stores the result in \meta{macro}. The \marg{number} is \emph{not}
- parsed before processing.
- %
-\begin{codeexample}[]
-\pgfmathsetbasenumberlength{8}
-\begin{tikzpicture}[x=0.25cm, y=0.25cm]
- \foreach \n [count=\y] in {0, 60, 102, 102, 126, 102, 102, 102, 0}{
- \pgfmathdectobase{\binary}{\n}{2}
- \pgfmathtodigitlist{\digitlist}{\binary}
- \foreach \digit [count=\x, evaluate={\c=\digit*50+15;}] in \digitlist
- \fill [fill=black!\c] (\x, -\y) rectangle ++(1,1);
- }
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Angle Computations}
-
-Unlike the rest of the math engine, which is a ``standalone'' package, the
-following commands only work in conjunction with the core of \pgfname.
-
-\begin{command}{\pgfmathanglebetweenpoints\marg{p}\marg{q}}
- Returns the angle of a line from \meta{p} to \meta{q} relative to a line
- going straight right from \meta{p}.
- %
-\begin{codeexample}[]
-\pgfmathanglebetweenpoints{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}}
-\pgfmathresult
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathanglebetweenlines\marg{$p_1$}\marg{$q_1$}\marg{$p_2$}\marg{$q_2$}}
- Returns the clockwise angle between a line going through $p_1$ and $q_1$
- and a line going through $p_2$ and $q_2$.
- %
-\begin{codeexample}[]
-\pgfmathanglebetweenlines{\pgfpoint{1cm}{3cm}}{\pgfpoint{2cm}{4cm}}
- {\pgfpoint{0cm}{1cm}}{\pgfpoint{1cm}{0cm}}
-\pgfmathresult
-\end{codeexample}
- %
-\end{command}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-math-design.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-math-design.tex
deleted file mode 100644
index 72e6ca084a..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-math-design.tex
+++ /dev/null
@@ -1,95 +0,0 @@
-% Copyright 2018 by Mark Wibrow and 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{Design Principles}
-
-\pgfname{} needs to perform many computations while typesetting a picture. For
-this, \pgfname\ relies on a mathematical engine, which can also be used
-independently of \pgfname, but which is distributed as part of the \pgfname\
-package nevertheless. Basically, the engine provides a parsing mechanism
-similar to the \calcname{} package so that expressions like |2*3cm+5cm| can be
-parsed; but the \pgfname\ engine is more powerful and can be extended and
-enhanced.
-
-\pgfname{} provides enhanced functionality, which permits the parsing of
-mathematical operations involving integers and non-integers with or without
-units. Furthermore, various functions, including trigonometric functions and
-random number generators can also be parsed (see
-Section~\ref{pgfmath-parsing}). The \calcname{} macros |\setlength| and friends
-have \pgfname{} versions which can parse these operations and functions (see
-Section~\ref{pgfmath-registers}). Additionally, each operation and function has
-an independent \pgfname{} command associated with it (see
-Section~\ref{pgfmath-commands}), and can be accessed outside the parser.
-
-The mathematical engine of \pgfname\ is implicitly used whenever you specify a
-number or dimension in a higher-level macro. For instance, you can write
-|\pgfpoint{2cm+4cm/2}{3cm*sin(30)}| or suchlike. However, the mathematical
-engine can also be used independently of the \pgfname\ core, that is, you can
-also just load it to get access to a mathematical parser.
-
-
-\subsection{Loading the Mathematical Engine}
-
-The mathematical engine of \pgfname\ is loaded automatically by \pgfname, but
-if you wish to use the mathematical engine but you do not need \pgfname\
-itself, you can load the following package:
-
-\begin{package}{pgfmath}
- This command will load the mathematical engine of \pgfname, but not
- \pgfname{} itself. It defines commands like |\pgfmathparse|.
-\end{package}
-
-
-\subsection{Layers of the Mathematical Engine}
-
-Like \pgfname\ itself, the mathematical engine is also structured into
-different layers:
-%
-\begin{enumerate}
- \item The top layer, which you will typically use directly, provides the
- command |\pgfmathparse|. This command parses a mathematical expression
- and evaluates it.
-
- Additionally, the top layer also defines some additional functions
- similar to the macros of the |calc| package for setting dimensions and
- counters. These macros are just wrappers around the |\pgfmathparse|
- macro.
-
- \item The calculation layer provides macros for performing one specific
- computation like computing a reciprocal or a multiplication. The parser
- uses these macros for the actual computation.
- \item The implementation layer provides the actual implementations of the
- computations. These can be changed (and possibly be made more
- efficient) without affecting the higher layers.
-\end{enumerate}
-
-
-\subsection{Efficiency and Accuracy of the Mathematical Engine}
-
-Currently, the mathematical algorithms are all implemented in \TeX. This poses
-some intriguing programming challenges as \TeX{} is a language for typesetting,
-rather than for general mathematics, and as with any programming language,
-there is a trade-off between accuracy and efficiency. If you find the level of
-accuracy insufficient for your purposes, you will have to replace the
-algorithms in the implementation layer.
-
-All the fancy mathematical ``bells-and-whistles'' that the parser provides,
-come with an additional processing cost, and in some instances, such as simply
-setting a length to |1cm|, with no other operations involved, the additional
-processing time is undesirable. To overcome this, the following feature is
-implemented: when no mathematical operations are required, an expression can be
-preceded by |+|. This will bypass the parsing process and the assignment will
-be orders of magnitude faster. This feature \emph{only} works with the macros
-for setting registers described in Section~\ref{pgfmath-registers}.
-%
-\begin{codeexample}[code only]
-\pgfmathsetlength\mydimen{1cm} % parsed : slower.
-\pgfmathsetlength\mydimen{+1cm} % not parsed : much faster.
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-math-numberprinting.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-math-numberprinting.tex
deleted file mode 100644
index 72b60ef6d9..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-math-numberprinting.tex
+++ /dev/null
@@ -1,875 +0,0 @@
-
-\section{Number Printing}
-\label{pgfmath-numberprinting}
-
-{\emph{An extension by Christian Feuersänger}}
-
-\medskip
-\noindent
-\pgfname\ supports number printing in different styles and rounds to arbitrary
-precision.
-
-\begin{command}{\pgfmathprintnumber\marg{x}}
- Generates pretty-printed output for the (real) number \meta{x}. The input
- number \meta{x} is parsed using |\pgfmathfloatparsenumber| which allows
- arbitrary precision.
-
- Numbers are typeset in math mode using the current set of number printing
- options, see below. Optional arguments can also be provided using
- |\pgfmathprintnumber[|\meta{options}|]|\meta{x}.
-\end{command}
-
-\begin{command}{\pgfmathprintnumberto\marg{x}\marg{macro}}
- Returns the resulting number into \meta{macro} instead of typesetting it
- directly.
-\end{command}
-
-\begin{key}{/pgf/number format/fixed}
- Configures |\pgfmathprintnumber| to round the number to a fixed number of
- digits after the period, discarding any trailing zeros.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,fixed,precision=2}
-\pgfmathprintnumber{4.568}\hspace{1em}
-\pgfmathprintnumber{5e-04}\hspace{1em}
-\pgfmathprintnumber{0.1}\hspace{1em}
-\pgfmathprintnumber{24415.98123}\hspace{1em}
-\pgfmathprintnumber{123456.12345}
-\end{codeexample}
-
- See section~\ref{sec:number:styles} for how to change the appearance.
-\end{key}
-
-\begin{key}{/pgf/number format/fixed zerofill=\marg{boolean} (default true)}
- Enables or disables zero filling for any number drawn in fixed point
- format.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,fixed,fixed zerofill,precision=2}
-\pgfmathprintnumber{4.568}\hspace{1em}
-\pgfmathprintnumber{5e-04}\hspace{1em}
-\pgfmathprintnumber{0.1}\hspace{1em}
-\pgfmathprintnumber{24415.98123}\hspace{1em}
-\pgfmathprintnumber{123456.12345}
-\end{codeexample}
- %
- This key affects numbers drawn with |fixed| or |std| styles (the latter
- only if no scientific format is chosen).
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,std,fixed zerofill,precision=2}
-\pgfmathprintnumber{4.568}\hspace{1em}
-\pgfmathprintnumber{5e-05}\hspace{1em}
-\pgfmathprintnumber{1}\hspace{1em}
-\pgfmathprintnumber{123456.12345}
-\end{codeexample}
-
- See section~\ref{sec:number:styles} for how to change the appearance.
-\end{key}
-
-\begin{key}{/pgf/number format/sci}
- Configures |\pgfmathprintnumber| to display numbers in scientific format,
- that means sign, mantissa and exponent (basis~$10$). The mantissa is
- rounded to the desired |precision| (or |sci precision|, see below).
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,sci,precision=2}
-\pgfmathprintnumber{4.568}\hspace{1em}
-\pgfmathprintnumber{5e-04}\hspace{1em}
-\pgfmathprintnumber{0.1}\hspace{1em}
-\pgfmathprintnumber{24415.98123}\hspace{1em}
-\pgfmathprintnumber{123456.12345}
-\end{codeexample}
-
- See section~\ref{sec:number:styles} for how to change the exponential
- display style.
-\end{key}
-
-\begin{key}{/pgf/number format/sci zerofill=\marg{boolean} (default true)}
- Enables or disables zero filling for any number drawn in scientific format.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,sci,sci zerofill,precision=2}
-\pgfmathprintnumber{4.568}\hspace{1em}
-\pgfmathprintnumber{5e-04}\hspace{1em}
-\pgfmathprintnumber{0.1}\hspace{1em}
-\pgfmathprintnumber{24415.98123}\hspace{1em}
-\pgfmathprintnumber{123456.12345}
-\end{codeexample}
- %
- As with |fixed zerofill|, this option does only affect numbers drawn in
- |sci| format (or |std| if the scientific format is chosen).
-
- See section~\ref{sec:number:styles} for how to change the exponential
- display style.
-\end{key}
-
-\begin{stylekey}{/pgf/number format/zerofill=\marg{boolean} (default true)}
- Sets both |fixed zerofill| and |sci zerofill| at once.
-\end{stylekey}
-
-\begin{keylist}{/pgf/number format/std,%
- /pgf/number format/std=\meta{lower e},
- /pgf/number format/std=\meta{lower e}:\meta{upper e}%
-}
- Configures |\pgfmathprintnumber| to a standard algorithm. It chooses either
- |fixed| or |sci|, depending on the order of magnitude. Let $n=s \cdot m
- \cdot 10^e$ be the input number and $p$ the current precision. If $-p/2 \le
- e \le 4$, the number is displayed using |fixed| format. Otherwise, it is
- displayed using |sci| format.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,std,precision=2}
-\pgfmathprintnumber{4.568}\hspace{1em}
-\pgfmathprintnumber{5e-04}\hspace{1em}
-\pgfmathprintnumber{0.1}\hspace{1em}
-\pgfmathprintnumber{24415.98123}\hspace{1em}
-\pgfmathprintnumber{123456.12345}
-\end{codeexample}
- %
- The parameters can be customized using the optional integer argument(s): if
- $\text{\meta{lower e}} \le e \le \text{\meta{upper e}}$, the number is
- displayed in |fixed| format, otherwise in |sci| format. Note that
- \meta{lower e} should be negative for useful results. The precision used
- for the scientific format can be adjusted with |sci precision| if
- necessary.
-\end{keylist}
-
-\begin{keylist}{/pgf/number format/relative*=\meta{exponent base 10}}
- Configures |\pgfmathprintnumber| to format numbers relative to an order of
- magnitude, $10^r$, where $r$ is an integer number.
-
- This key addresses different use-cases.
-
- \paragraph{First use-case:}
-
- provide a unified format for a \emph{sequence} of numbers. Consider the
- following test:
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/relative*={1}}
-\pgfmathprintnumber{6.42e-16}\hspace{1em}
-\pgfmathprintnumber{1.2}\hspace{1em}
-\pgfmathprintnumber{6}\hspace{1em}
-\pgfmathprintnumber{20.6}\hspace{1em}
-\pgfmathprintnumber{87}
-\end{codeexample}
- %
- \noindent With any other style, the |6.42e-16| would have been formatted as
- an isolated number. Here, it is rounded to |0| because when viewed relative
- to $10^1$ (the exponent $1$ is the argument for |relative|), it has no
- significant digits.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/relative*={2}}
-\pgfmathprintnumber{123.345}\hspace{1em}
-\pgfmathprintnumber{0.0012}\hspace{1em}
-\pgfmathprintnumber{0.0014}\hspace{1em}
-\end{codeexample}
- %
- \noindent The example above applies the initial |precision=2| to |123.345|
- -- relative to $100$. Two significant digits of |123.345| relative to $100$
- are |123|. Note that the ``$2$ significant digits of |123.345|'' translates
- to ``round |1.2345| to $2$ digits'', which would yield |1.2300|. Similarly,
- the other two numbers are |0| compared to $100$ using the given
- |precision|.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/relative*={-3}}
-\pgfmathprintnumber{123.345}\hspace{1em}
-\pgfmathprintnumber{0.0012}\hspace{1em}
-\pgfmathprintnumber{0.0014}\hspace{1em}
-\end{codeexample}
-
- \paragraph{Second use-case:}
-
- improve rounding in the presence of \emph{inaccurate} numbers. Let us
- suppose that some limited-precision arithmetics resulted in the result
- |123456999| (like the |fpu| of \pgfname). You know that its precision is
- about five or six significant digits. And you want to provide a fixed point
- output. In this case, the trailing digits |....999| are a numerical
- artifact due to the limited precision. Use |relative*=3,precision=0| to
- eliminate the artifacts:
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,relative*={3},precision=0}
-\pgfmathprintnumber{123456999}\hspace{1em}
-\pgfmathprintnumber{123456999.12}
-\end{codeexample}
- %
- \noindent Here, |precision=0| means that we inspect |123456.999| and round
- that number to $0$ digits. Finally, we move the period back to its initial
- position. Adding |relative style=fixed| results in fixed point output
- format:
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,relative*={3},precision=0,relative style=fixed}
-\pgfmathprintnumber{123456999}\hspace{1em}
-\pgfmathprintnumber{123456999.12}
-\end{codeexample}
- %
- \noindent Note that there is another alternative for this use-case which is
- discussed later: the |fixed relative| style.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,fixed relative,precision=6}
-\pgfmathprintnumber{123456999}\hspace{1em}
-\pgfmathprintnumber{123456999.12}
-\end{codeexample}
-
- You might wonder why there is an asterisk in the key's name. The short
- answer is: there is also a \declareandlabel{/pgf/number format/relative}
- number printer which does unexpected things. The key |relative*| repairs
- this. Existing code will still use the old behavior.
-
- Technically, the key works as follows: as already explained above,
- |relative*=3| key applied to |123456999.12| moves the period by three
- positions and analyzes |123456.99912|. Mathematically speaking, we are
- given a number $x = \pm m \cdot 10^e$ and we attempt to apply
- |relative*=|$r$. The method then rounds $x / 10^r$ to |precision| digits.
- Afterwards, it multiplies the result by $10^r$ and typesets it.
-\end{keylist}
-
-\begin{stylekey}{/pgf/number format/every relative}
- A style which configures how the |relative| method finally displays its
- results.
-
- The initial configuration is
- %
-\begin{codeexample}[code only]
-\pgfkeys{/pgf/number format/every relative/.style=std}
-\end{codeexample}
-
- Note that rounding is turned off when the resulting style is being
- evaluated (since |relative| already rounded the number).
-
- Although supported, I discourage from using |fixed zerofill| or
- |sci zerofill| in this context -- it may lead to a suggestion of higher
- precision than is actually used (because |fixed zerofill| might simply add
- |.00| although there was a different information before |relative| rounded
- the result).
-\end{stylekey}
-
-\begin{key}{/pgf/number format/relative style=\marg{options}}
- The same as |every relative/.append style=|\marg{options}.
-\end{key}
-
-\begin{keylist}{/pgf/number format/fixed relative}
- Configures |\pgfmathprintnumber| to format numbers in a similar way to the
- |fixed| style, but the |precision| is interpreted relatively to the
- number's exponent.
-
- The motivation is to get the same rounding effect as for |sci|, but to
- display the number in the |fixed| style:
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,fixed relative,precision=3}
-\pgfmathprintnumber{1000.0123}\hspace{1em}
-\pgfmathprintnumber{100.0567}\hspace{1em}
-\pgfmathprintnumber{0.000010003452}\hspace{1em}
-\pgfmathprintnumber{0.010073452}\hspace{1em}
-\pgfmathprintnumber{1.23567}\hspace{1em}
-\pgfmathprintnumber{1003.75}\hspace{1em}
-\pgfmathprintnumber{1006.75}\hspace{1em}
-\end{codeexample}
-
- The effect of |fixed relative| is that the number is rounded to
- \emph{exactly} the first \meta{precision} non-zero digits, no matter how
- many leading zeros the number might have.
-
- Use |fixed relative| if you want |fixed| and if you know that only the
- first $n$ digits are correct. Use |sci| if you need a scientific display
- style and only the first $n$ digits are correct.
-
- Note that |fixed relative| ignores the |fixed zerofill| flag.
-
- See also the |relative*| key. Note that the |relative=|\marg{exponent} key
- explicitly moves the period to some designated position before it attempts
- to round the number. Afterwards, it ``rounds from the right'', i.e.\ it
- rounds to that explicitly chosen digit position. In contrast to that,
- |fixed relative| ``rounds from the left'': it takes the \emph{first}
- non-zero digit, temporarily places the period after this digit, and rounds
- that number. The rounding style |fixed| leaves the period where it is, and
- rounds everything behind that digit. The |sci| style is similar to
- |fixed relative|.
-\end{keylist}
-
-\begin{key}{/pgf/number format/int detect}
- Configures |\pgfmathprintnumber| to detect integers automatically. If the
- input number is an integer, no period is displayed at all. If not, the
- scientific format is chosen.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,int detect,precision=2}
-\pgfmathprintnumber{15}\hspace{1em}
-\pgfmathprintnumber{20}\hspace{1em}
-\pgfmathprintnumber{20.4}\hspace{1em}
-\pgfmathprintnumber{0.01}\hspace{1em}
-\pgfmathprintnumber{0}
-\end{codeexample}
- %
-\end{key}
-
-\begin{command}{\pgfmathifisint\marg{number constant}\marg{true code}\marg{false code}}
- A command which does the same check as |int detect|, but it invokes
- \meta{true code} if the \meta{number constant} actually is an integer and
- the \meta{false code} if not.
-
- As a side-effect, |\pgfretval| will contain the parsed number, either in
- integer format or as parsed floating point number.
-
- The argument \meta{number constant} will be parsed with
- |\pgfmathfloatparsenumber|.
- %
-\begin{codeexample}[]
-15 \pgfmathifisint{15}{is an int: \pgfretval.}{is no int}\hspace{1em}
-15.5 \pgfmathifisint{15.5}{is an int: \pgfretval.}{is no int}
-\end{codeexample}
- %
-\end{command}
-
-\begin{key}{/pgf/number format/int trunc}
- Truncates every number to integers (discards any digit after the period).
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,int trunc}
-\pgfmathprintnumber{4.568}\hspace{1em}
-\pgfmathprintnumber{5e-04}\hspace{1em}
-\pgfmathprintnumber{0.1}\hspace{1em}
-\pgfmathprintnumber{24415.98123}\hspace{1em}
-\pgfmathprintnumber{123456.12345}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/number format/frac}
- Displays numbers as fractionals.
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{fpu}}]
-\pgfkeys{/pgf/number format/frac}
-\pgfmathprintnumber{0.333333333333333}\hspace{1em}
-\pgfmathprintnumber{0.5}\hspace{1em}
-\pgfmathprintnumber{2.133333333333325e-01}\hspace{1em}
-\pgfmathprintnumber{0.12}\hspace{1em}
-\pgfmathprintnumber{2.666666666666646e-02}\hspace{1em}
-\pgfmathprintnumber{-1.333333333333334e-02}\hspace{1em}
-\pgfmathprintnumber{7.200000000000000e-01}\hspace{1em}
-\pgfmathprintnumber{6.666666666666667e-02}\hspace{1em}
-\pgfmathprintnumber{1.333333333333333e-01}\hspace{1em}
-\pgfmathprintnumber{-1.333333333333333e-02}\hspace{1em}
-\pgfmathprintnumber{3.3333333}\hspace{1em}
-\pgfmathprintnumber{1.2345}\hspace{1em}
-\pgfmathprintnumber{1}\hspace{1em}
-\pgfmathprintnumber{-6}
-\end{codeexample}
-
- \begin{key}{/pgf/number format/frac TeX=\marg{\textbackslash macro} (initially \texttt{\textbackslash frac})}
- Allows to use a different implementation for |\frac| inside of the
- |frac| display type.
- \end{key}
-
- \begin{key}{/pgf/number format/frac denom=\meta{int} (initially empty)}
- Allows to provide a custom denominator for |frac|.
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{fpu}}]
-\pgfkeys{/pgf/number format/.cd,frac, frac denom=10}
-\pgfmathprintnumber{0.1}\hspace{1em}
-\pgfmathprintnumber{0.5}\hspace{1em}
-\pgfmathprintnumber{1.2}\hspace{1em}
-\pgfmathprintnumber{-0.6}\hspace{1em}
-\pgfmathprintnumber{-1.4}\hspace{1em}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/number format/frac whole=\mchoice{true,false} (initially true)}
- Configures whether complete integer parts shall be placed in front of
- the fractional part. In this case, the fractional part will be less
- then $1$. Use |frac whole=false| to avoid whole number parts.
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{fpu}}]
-\pgfkeys{/pgf/number format/.cd,frac, frac whole=false}
-\pgfmathprintnumber{20.1}\hspace{1em}
-\pgfmathprintnumber{5.5}\hspace{1em}
-\pgfmathprintnumber{1.2}\hspace{1em}
-\pgfmathprintnumber{-5.6}\hspace{1em}
-\pgfmathprintnumber{-1.4}\hspace{1em}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/number format/frac shift=\marg{integer} (initially 4)}
- In case you experience problems because of stability problems, try
- experimenting with a different |frac shift|. Higher shift values $k$
- yield higher sensitivity to inaccurate data or inaccurate arithmetics.
-
- Technically, the following happens. If $r < 1$ is the fractional part
- of the mantissa, then a scale $i = 1/r \cdot 10^k$ is computed where
- $k$ is the shift; fractional parts of $i$ are neglected. The value
- $1/r$ is computed internally, its error is amplified.
-
- If you still experience stability problems, use |\usepackage{fp}| in
- your preamble. The |frac| style will then automatically employ the
- higher absolute precision of |fp| for the computation of $1/r$.
- \end{key}
-\end{key}
-
-\begin{key}{/pgf/number format/precision=\marg{number}}
- Sets the desired rounding precision for any display operation. For
- scientific format, this affects the mantissa.
-\end{key}
-
-\begin{key}{/pgf/number format/sci precision=\meta{number or empty} (initially empty)}
- Sets the desired rounding precision only for |sci| styles.
-
- Use |sci precision={}| to restore the initial configuration (which uses the
- argument provided to |precision| for all number styles).
-\end{key}
-
-\begin{key}{/pgf/number format/read comma as period=\mchoice{true,false} (initially false)}
- This is one of the few keys which allows to customize the number parser. If
- this switch is turned on, a comma is read just as a period.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/read comma as period}
-\pgfmathprintnumber{1234,56}
-\end{codeexample}
- %
- This is typically undesired as it can cause side-effects with math parsing
- instructions. However, it is supported to format input numbers or input
- tables. Consider |use comma| to typeset the result with a comma as well.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- read comma as period,
- use comma}
-\pgfmathprintnumber{1234,56}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Changing display styles}%
-\label{sec:number:styles}
-
-You can change the way how numbers are displayed. For example, if you use the
-`\texttt{fixed}' style, the input number is rounded to the desired precision
-and the current fixed point display style is used to typeset the number. The
-same is applied to any other format: first, rounding routines are used to get
-the correct digits, afterwards a display style generates proper \TeX-code.
-
-\begin{key}{/pgf/number format/set decimal separator=\marg{text}}
- Assigns \marg{text} as decimal separator for any fixed point numbers
- (including the mantissa in sci format).
-
- Use |\pgfkeysgetvalue{/pgf/number format/set decimal separator}\value| to
- get the current separator into |\value|.
-\end{key}
-
-\begin{stylekey}{/pgf/number format/dec sep=\marg{text}}
- Just another name for |set decimal separator|.
-\end{stylekey}
-
-\begin{key}{/pgf/number format/set thousands separator=\marg{text}}
- Assigns \marg{text} as thousands separator for any fixed point numbers
- (including the mantissa in sci format).
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- fixed,
- fixed zerofill,
- precision=2,
- set thousands separator={}}
-\pgfmathprintnumber{1234.56}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- fixed,
- fixed zerofill,
- precision=2,
- set thousands separator={}}
-\pgfmathprintnumber{1234567890}
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- fixed,
- fixed zerofill,
- precision=2,
- set thousands separator={.}}
-\pgfmathprintnumber{1234567890}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- fixed,
- fixed zerofill,
- precision=2,
- set thousands separator={,}}
-\pgfmathprintnumber{1234567890}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- fixed,
- fixed zerofill,
- precision=2,
- set thousands separator={{{,}}}}
-\pgfmathprintnumber{1234567890}
-\end{codeexample}
- %
- The last example employs commas and disables the default comma-spacing.
-
- Use |\pgfkeysgetvalue{/pgf/number format/set thousands separator}\value| to
- get the current separator into |\value|.
-\end{key}
-
-\begin{stylekey}{/pgf/number format/1000 sep=\marg{text}}
- Just another name for |set thousands separator|.
-\end{stylekey}
-
-\begin{key}{/pgf/number format/1000 sep in fractionals=\marg{boolean} (initially false)}
- Configures whether the fractional part should also be grouped into groups
- of three digits.
-
- The value |true| will active the |1000 sep| for both, integer and
- fractional parts. The value |false| will active |1000 sep| only for the
- integer part.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- fixed,
- precision=999,
- set thousands separator={\,},
- 1000 sep in fractionals,
- }
-\pgfmathprintnumber{1234.1234567}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- fixed,fixed zerofill,
- precision=9,
- set thousands separator={\,},
- 1000 sep in fractionals,
- }
-\pgfmathprintnumber{1234.1234567}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/number format/min exponent for 1000 sep=\marg{number} (initially 0)}
- Defines the smallest exponent in scientific notation which is required to
- draw thousand separators. The exponent is the number of digits minus one,
- so $\meta{number}=4$ will use thousand separators starting with $1e4 =
- 10000$.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- int detect,
- 1000 sep={\,},
- min exponent for 1000 sep=0}
-\pgfmathprintnumber{5000}; \pgfmathprintnumber{1000000}
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- int detect,
- 1000 sep={\,},
- min exponent for 1000 sep=4}
-\pgfmathprintnumber{1000}; \pgfmathprintnumber{5000}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- int detect,
- 1000 sep={\,},
- min exponent for 1000 sep=4}
-\pgfmathprintnumber{10000}; \pgfmathprintnumber{1000000}
-\end{codeexample}
- %
- \noindent A value of |0| disables this feature (negative values are
- ignored).
-\end{key}
-
-\begin{key}{/pgf/number format/use period}
- A predefined style which installs periods ``\texttt{.}'' as decimal
- separators and commas ``\texttt{,}'' as thousands separators. This style is
- the default.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use period}
-\pgfmathprintnumber{12.3456}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use period}
-\pgfmathprintnumber{1234.56}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/number format/use comma}
- A predefined style which installs commas ``\texttt{,}'' as decimal
- separators and periods ``\texttt{.}'' as thousands separators.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use comma}
-\pgfmathprintnumber{12.3456}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,fixed,precision=2,use comma}
-\pgfmathprintnumber{1234.56}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/number format/skip 0.=\marg{boolean} (initially false)}
- Configures whether numbers like $0.1$ shall be typeset as $.1$ or not.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- fixed,
- fixed zerofill,precision=2,
- skip 0.}
-\pgfmathprintnumber{0.56}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,
- fixed,
- fixed zerofill,precision=2,
- skip 0.=false}
-\pgfmathprintnumber{0.56}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/number format/showpos=\marg{boolean} (initially false)}
- Enables or disables the display of plus signs for non-negative numbers.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/showpos}
-\pgfmathprintnumber{12.345}
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/showpos=false}
-\pgfmathprintnumber{12.345}
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,showpos,sci}
-\pgfmathprintnumber{12.345}
-\end{codeexample}
- %
-\end{key}
-
-\begin{stylekey}{/pgf/number format/print sign=\marg{boolean}}
- A style which is simply an alias for |showpos=|\marg{boolean}.
-\end{stylekey}
-
-\begin{key}{/pgf/number format/sci 10e}
- Uses $m \cdot 10^e$ for any number displayed in scientific format.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,sci,sci 10e}
-\pgfmathprintnumber{12.345}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/number format/sci 10\textasciicircum e}
- The same as `|sci 10e|'.
-\end{key}
-
-\begin{key}{/pgf/number format/sci e}
- Uses the `$1e{+}0$' format which is generated by common scientific tools
- for any number displayed in scientific format.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,sci,sci e}
-\pgfmathprintnumber{12.345}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/number format/sci E}
- The same with an uppercase `\texttt{E}'.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,sci,sci E}
-\pgfmathprintnumber{12.345}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/number format/sci subscript}
- Typesets the exponent as subscript for any number displayed in scientific
- format. This style requires very little space.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,sci,sci subscript}
-\pgfmathprintnumber{12.345}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/number format/sci superscript}
- Typesets the exponent as superscript for any number displayed in scientific
- format. This style requires very little space.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/number format/.cd,sci,sci superscript}
-\pgfmathprintnumber{12.345}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/number format/sci generic=\marg{keys}}
- Allows to define an own number style for the scientific format. Here,
- \meta{keys} can be one of the following choices (omit the long key prefix):
-
- \begin{key}{/pgf/number format/sci generic/mantissa sep=\marg{text} (initially empty)}
- Provides the separator between a mantissa and the exponent. It might be
- |\cdot|, for example,
- \end{key}
- %
- \begin{key}{/pgf/number format/sci generic/exponent=\marg{text} (initially empty)}
- Provides text to format the exponent. The actual exponent is available
- as argument |#1| (see below).
- \end{key}
- %
-\begin{codeexample}[]
-\pgfkeys{
- /pgf/number format/.cd,
- sci,
- sci generic={mantissa sep=\times,exponent={10^{#1}}}}
-\pgfmathprintnumber{12.345};
-\pgfmathprintnumber{0.00012345}
-\end{codeexample}
- %
- The \meta{keys} can depend on three parameters, namely on |#1| which is the
- exponent, |#2| containing the flags entity of the floating point number and
- |#3| is the (unprocessed and unformatted) mantissa.
-
- Note that |sci generic| is \emph{not} suitable to modify the appearance of
- fixed point numbers, nor can it be used to format the mantissa (which is
- typeset like fixed point numbers). Use |dec sep|, |1000 sep| and
- |print sign| to customize the mantissa.
-\end{key}
-
-\begin{key}{/pgf/number format/retain unit mantissa=\mchoice{true,false} (initially true)}
- Allows to omit a unit mantissa.
- %
-\begin{codeexample}[]
-\pgfkeys{
- /pgf/number format/.cd,
- sci, retain unit mantissa=false}
-\pgfmathprintnumber{10.5};
-\pgfmathprintnumber{10};
-\pgfmathprintnumber{1010};
-\pgfmathprintnumber[precision=1]{-1010};
-\end{codeexample}
- %
- The feature is applied after rounding to the desired precision: if the
- remaining mantissa is equal to~$1$, it will be omitted. It applies to all
- styles involving the scientific format (including |std|).
-\end{key}
-
-\begin{key}{/pgf/number format/\protect\atmarktext dec sep mark=\marg{text}}
- Will be placed right before the place where a decimal separator belongs to.
- However, \marg{text} will be inserted even if there is no decimal
- separator. It is intended as place-holder for auxiliary routines to find
- alignment positions.
-
- This key should never be used to change the decimal separator!
- Use |dec sep| instead.
-\end{key}
-
-\begin{key}{/pgf/number format/\protect\atmarktext sci exponent mark=\marg{text}}
- Will be placed right before exponents in scientific notation. It is
- intended as place-holder for auxiliary routines to find alignment
- positions.
-
- This key should never be used to change the exponent!
-\end{key}
-
-\begin{key}{/pgf/number format/assume math mode=\marg{boolean} (default true)}
- Set this to |true| if you don't want any checks for math mode. The initial
- setting checks whether math mode is active using |\pgfutilensuremath| for
- each final number.
-
- Use |assume math mode=true| if you know that math mode is active. In that
- case, the final number is typeset as-is, no further checking is performed.
-\end{key}
-
-\begin{stylekey}{/pgf/number format/verbatim}
- A style which configures the number printer to produce verbatim text
- output, i.e., it doesn't contain \TeX\ macros.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fpu}}]
-\pgfkeys{
- /pgf/fpu,
- /pgf/number format/.cd,
- sci,
- verbatim}
-\pgfmathprintnumber{12.345};
-\pgfmathprintnumber{0.00012345};
-\pgfmathparse{exp(15)}
-\pgfmathprintnumber{\pgfmathresult}
-\end{codeexample}
- %
- The style resets |1000 sep|, |dec sep|, |print sign|, |skip 0.| and sets
- |assume math mode|. Furthermore, it installs a |sci generic| format for
- verbatim output of scientific numbers.
-
- However, it will still respect |precision|, |fixed zerofill|,
- |sci zerofill| and the overall styles |fixed|, |sci|, |int detect| (and
- their variants). It might be useful if you intend to write output files.
-\end{stylekey}
-
-
-%--------------------------------------------------
-% \subsubsection{Defining own display styles}
-% You can define own display styles, although this may require some insight into \TeX-programming. Here are two examples:
-% \begin{enumerate}
-% \item A new fixed point display style: The following code defines a new style named `\texttt{my own fixed point style}' which uses $1{\cdot}00$ instead of $1.00$.
-% \begin{lstlisting}
-% \def\myfixedpointstyleimpl#1.#2\relax{%
-% #1{\cdot}#2%
-% }%
-% \def\myfixedpointstyle#1{%
-% \pgfutilensuremath{%
-% \ifpgfmathfloatroundhasperiod
-% \expandafter\myfixedpointstyleimpl#1\relax
-% \else
-% #1%
-% \fi
-% }%
-% }
-% \pgfkeys{/my own fixed point style/.code={%
-% \let\pgfmathprintnumber@fixed@style=\myfixedpointstyle}
-% }%
-% \end{lstlisting}
-% You only need to overwrite the macro \lstinline!\pgfmathprintnumber@fixed@style!. This macro takes one argument (the result of any numerical computations). The \TeX-boolean \lstinline!\ifpgfmathfloatroundhasperiod! is true if and only if the input number contains a period.
-%
-% \item An example for a new scientific display style:
-% \begin{lstlisting}
-% % #1:
-% % 0 == '0' (the number is +- 0.0),
-% % 1 == '+',
-% % 2 == '-',
-% % 3 == 'not a number'
-% % 4 == '+ infinity'
-% % 5 == '- infinity'
-% % #2: the mantissa
-% % #3: the exponent
-% \def\myscistyle#1#2e#3\relax{%
-% ...
-% }
-% \pgfkeys{/my own sci style/.code={%
-% \let\pgfmathfloatrounddisplaystyle=\myscistyle},
-% }%
-% \end{lstlisting}
-% \end{enumerate}
-%--------------------------------------------------
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-math-parsing.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-math-parsing.tex
deleted file mode 100644
index c0d32d4d9c..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-math-parsing.tex
+++ /dev/null
@@ -1,1414 +0,0 @@
-% Copyright 2019 by Mark Wibrow
-%
-% 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{Mathematical Expressions}
-\label{pgfmath-syntax}
-
-The easiest way of using \pgfname's mathematical engine is to provide a
-mathematical expression given in familiar infix notation, for example,
-|1cm+4*2cm/5.5| or |2*3+3*sin(30)|. This expression can be parsed by the
-mathematical engine and the result can be placed in a dimension register, a
-counter, or a macro.
-
-It should be noted that all calculations must not exceed $\pm16383.99999$ at
-\emph{any} point, because the underlying computations rely on \TeX{}
-dimensions. This means that many of the underlying computations are necessarily
-approximate and, in addition, not very fast. \TeX{} is, after all, a
-typesetting language and not ideally suited to relatively advanced mathematical
-operations. However, it is possible to change the computations as described in
-Section~\ref{pgfmath-reimplement}.
-
-In the present section, the high-level macros for parsing an expression are
-explained first, then the syntax for expression is explained.
-
-
-\subsection{Parsing Expressions}
-\label{pgfmath-registers}
-\label{pgfmath-parsing}
-
-\subsubsection{Commands}
-
-The \todosp{why 2 labels?}basic command for invoking the parser of \pgfname's
-mathematical engine is the following:
-
-\begin{command}{\pgfmathparse\marg{expression}}
- This macro parses \meta{expression} and returns the result without units in
- the macro |\pgfmathresult|.
-
- \example |\pgfmathparse{2pt+3.5pt}| will set |\pgfmathresult| to the text
- |5.5|.
-
- In the following, the special properties of this command are explained. The
- exact syntax of mathematical expressions is explained in Sections
- \ref{pgfmath-operators} and~\ref{pgfmath-functions}.
- %
- \begin{itemize}
- \item The result stored in the macro |\pgfmathresult| is a decimal
- \emph{without units}. This is true regardless of whether the
- \meta{expression} contains any unit specification. All numbers with
- units are converted to points first. See
- Section~\ref{pgfmath-units} for details on units.
- \item The parser will recognize \TeX{} registers and box dimensions, so
- |\mydimen|, |0.5\mydimen|, |\wd\mybox|, |0.5\dp\mybox|,
- |\mycount\mydimen| and so on can be parsed.
- \item The $\varepsilon$-TeX\ extensions |\dimexpr|, |\numexpr|,
- |\glueexpr|, and |\muexpr| are recognized and evaluated. The values
- they result in will be used in the further evaluation, as if you
- had put |\the| before them.
- \item Parenthesis can be used to change the order of the evaluation.
- \item Various functions are recognized, so it is possible to parse
- |sin(.5*pi r)*60|, which means ``the sine of $0.5$ times $\pi$
- radians, multiplied by 60''. The argument of functions can be any
- expression.
- \item Scientific notation in the form |1.234e+4| is recognized (but the
- restriction on the range of values still applies). The exponent
- symbol can be upper or lower case (i.e., |E| or |e|).
- \item An integer with a zero-prefix (excluding, of course zero itself),
- is interpreted as an octal number and is automatically converted to
- base 10.
- \item An integer with prefix |0x| or |0X| is interpreted as a
- hexadecimal number and is automatically converted to base 10.
- Alphabetic digits can be in uppercase or lowercase.
- \item An integer with prefix |0b| or |0B| is interpreted as a binary
- number and is automatically converted to base 10.
- \item An expression (or part of an expression) surrounded with double
- quotes (i.e., the character |"|) will not be evaluated. Obviously
- this should be used with great care.
- \end{itemize}
-\end{command}
-
-\begin{command}{\pgfmathqparse\marg{expression}}
- This macro is similar to |\pgfmathparse|: it parses \meta{expression} and
- returns the result in the macro |\pgfmathresult|. It differs in two
- respects. Firstly, |\pgfmathqparse| does not parse functions, scientific
- notation, the prefixes for binary octal, or hexadecimal numbers, nor does
- it accept the special use of |"|, |?| or |:| characters. Secondly, numbers
- in \meta{expression} \emph{must} specify a \TeX{} unit (except in such
- instances as |0.5\pgf@x|), which greatly simplifies the problem of parsing
- real numbers. As a result of these restrictions |\pgfmathqparse| is about
- twice as fast as |\pgfmathparse|. Note that the result will still be a
- number without units.
-\end{command}
-
-\begin{command}{\pgfmathpostparse}
- At the end of the parse this command is executed, allowing some custom
- action to be performed on the result of the parse. When this command is
- executed, the macro |\pgfmathresult| will hold the result of the parse (as
- always, without units). The result of the custom action should be used to
- redefine |\pgfmathresult| appropriately. By default, this command is
- equivalent to |\relax|. This differs from previous versions, where, if the
- parsed expression contained no units, the result of the parse was scaled
- according to the value in |\pgfmathresultunitscale| (which by default was
- |1|).
-
- This scaling can be turned on again using:
- |\let\pgfmathpostparse=\pgfmathscaleresult|. Note, however that by scaling
- the result, the base conversion functions will not work, and the |"|
- character should not be used to quote parts of an expression.
-\end{command}
-
-Instead of the |\pgfmathparse| macro you can also use wrapper commands, whose
-usage is very similar to their cousins in the \calcname{} package. The only
-difference is that the expressions can be any expression that is handled by
-|\pgfmathparse|. For all of the following commands, if \meta{expression} starts
-with |+|, no parsing is done and a simple assignment or increment is done using
-normal \TeX\ assignments or increments. This will be orders of magnitude faster
-than calling the parser.
-
-The effect of the following commands is always local to the current \TeX\
-scope.
-
-\begin{command}{\pgfmathsetlength\marg{register}\marg{expression}}
- Basically, this command sets the length of the \TeX{} \meta{register} to
- the value specified by \meta{expression}. However, there is some fine
- print:
-
- First, in case \meta{expression} starts with a |+|, a simple \TeX\
- assignment is done. In particular, \meta{register} can be a glue register
- and \meta{expression} be something like |+1pt plus 1fil| and the
- \meta{register} will be assigned the expected value.
-
- Second, when the \meta{expression} does not start with |+|, it is first
- parsed using |\pgfmathparse|, resulting in a (dimensionless) value
- |\pgfmathresult|. Now, if the parser encountered the unit |mu| somewhere in
- the expression, it assumes that \meta{register} is a |\muskip| register and
- will try to assign to \meta{register} the value |\pgfmathresult| followed
- by |mu|. Otherwise, in case |mu| was not encountered, it is assumed that
- \meta{register} is a dimension register or a glue register and we assign
- |\pgfmathresult| followed by |pt| to it.
-
- The net effect of the above is that you can write things like
- %
-\begin{codeexample}[]
- \muskipdef\mymuskip=0
- \pgfmathsetlength{\mymuskip}{1mu+3*4mu} \the\mymuskip
-\end{codeexample}
- %
-\begin{codeexample}[]
- \dimendef\mydimen=0
- \pgfmathsetlength{\mydimen}{1pt+3*4pt} \the\mydimen
-\end{codeexample}
- %
-\begin{codeexample}[]
- \skipdef\myskip=0
- \pgfmathsetlength{\myskip}{1pt+3*4pt} \the\myskip
-\end{codeexample}
-
- One thing that will \emph{not} work is
- |\pgfmathsetlength{\myskip}{1pt plus 1fil}| since the parser does not
- support fill's. You can, however, use the |+| notation in this case:
- %
-\begin{codeexample}[]
- \skipdef\myskip=0
- \pgfmathsetlength{\myskip}{+1pt plus 1fil} \the\myskip
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfmathaddtolength\marg{register}\marg{expression}}
- Adds the value of \meta{expression} to the \TeX{} \meta{register}. All of
- the special consideration mentioned for |\pgfmathsetlength| also apply here
- in the same way.
-\end{command}
-
-\begin{command}{\pgfmathsetcount\marg{count register}\marg{expression}}
- Sets the value of the \TeX{} \meta{count register}, to the \emph{truncated}
- value specified by \meta{expression}.
-\end{command}
-
-\begin{command}{\pgfmathaddtocount\marg{count register}\marg{expression}}
- Adds the \emph{truncated} value of \meta{expression} to the \TeX{}
- \meta{count register}.
-\end{command}
-
-\begin{command}{\pgfmathsetcounter\marg{counter}\marg{expression}}
- Sets the value of the \LaTeX{} \meta{counter} to the \emph{truncated} value
- specified by \meta{expression}.
-\end{command}
-
-\begin{command}{\pgfmathaddtocounter\marg{counter}\marg{expression}}
- Adds the \emph{truncated} value of \meta{expression} to \meta{counter}.
-\end{command}
-
-\begin{command}{\pgfmathsetmacro\marg{macro}\marg{expression}}
- Defines \meta{macro} as the value of \meta{expression}. The result is a
- decimal without units.
-\end{command}
-
-\begin{command}{\pgfmathsetlengthmacro\marg{macro}\marg{expression}}
- Defines \meta{macro} as the value of \meta{expression} \LaTeX{} \emph{in
- points}.
-\end{command}
-
-\begin{command}{\pgfmathtruncatemacro\marg{macro}\marg{expression}}
- Defines \meta{macro} as the truncated value of \meta{expression}.
-\end{command}
-
-
-\subsubsection{Considerations Concerning Units}
-\label{pgfmath-units}
-
-As was explained earlier, the parser commands like |\pgfmathparse| will always
-return a result without units in it and all dimensions that have a unit like
-|10pt| or |1in| will first be converted to \TeX\ points (|pt|) and, then, the
-unit is dropped.
-
-Sometimes it is useful, nevertheless, to find out whether an expression or not.
-For this, you can use the following commands:
-
-{\let\ifpgfmathunitsdeclared\relax
- \begin{command}{\ifpgfmathunitsdeclared}
- After a call of |\pgfmathparse| this if will be true exactly if
- some unit was encountered in the expression. It is always set
- globally in each call.
-
- Note that \emph{any} ``mentioning'' of a unit inside an
- expression will set this \TeX-if to true. In particular, even an
- expressionlike |2pt/1pt|, which arguably should be considered
- ``scalar'' or ``unit-free'' will still have this \TeX-if set to
- true. However, see the |scalar| function for a way to change
- this.
- \end{command}
-}
-
-\begin{math-function}{scalar(\mvar{value})}
-\mathcommand
- This function is the identity function on its input, but it will reset the
- \TeX-if |\ifpgfmathunitsdeclared|. Thus, it can be used to indicate that
- the given \meta{value} should be considered as a ``scalar'' even when it
- contains units; but note that it will work even when the \meta{value} is a
- string or something else. The only effect of this function is to clear the
- unit declaration.
- %
-\begin{codeexample}[]
-\pgfmathparse{scalar(1pt/2pt)} \pgfmathresult\
-\ifpgfmathunitsdeclared with \else without \fi unit
-\end{codeexample}
-
- Note, however, that this command (currently) really just clears the \TeX-if
- as the input is scanned from left-to-right. Thus, even if there is a use of
- a unit before the |scalar| function is used, the \TeX-if will be cleared:
- %
-\begin{codeexample}[]
-\pgfmathparse{1pt+scalar(1pt)} \pgfmathresult\
-\ifpgfmathunitsdeclared with \else without \fi unit
-\end{codeexample}
-
- The other way round, a use of a unit after the |scalar| function will set
- the units once more.
- %
-\begin{codeexample}[]
-\pgfmathparse{scalar(1pt)+1pt} \pgfmathresult\
-\ifpgfmathunitsdeclared with \else without \fi unit
-\end{codeexample}
-
- For these reasons, you should use the function only on the outermost level
- of an expression.
-
- A typical use of this function is the following:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calc,quotes}}]
-\tikz{
- \coordinate["$A$"] (A) at (2,2);
- \coordinate["$B$" below] (B) at (0,0);
- \coordinate["$C$" below] (C) at (3,0);
- \draw (A) -- (B) -- (C) -- cycle;
- \path
- let \p1 =($(A)-(B)$), \p2 =($(A)-(C)$),
- \n1 = {veclen(\x1,\y1)}, \n2 = {veclen(\x2,\y2)}
- in coordinate ["$D$" below] (D) at ($ (B)!scalar(\n1/(\n1+\n2))!(C) $);
- \draw (A) -- (D);
-}
-\end{codeexample}
- %
-\end{math-function}
-
-A special kind of units are \TeX's ``math units'' (|mu|). It will be treated as
-if |pt| had been used, but you can check whether an expression contained a math
-unit using the following:
-%
-{\let\ifpgfmathmathunitsdeclared\relax
- \begin{command}{\ifpgfmathmathunitsdeclared}
- This \TeX-if is similar to |\ifpgfmathunitsdeclared|, but it
- is only set when the unit |mu| is encountered at least
- once. In this case, |\ifpgfmathunitsdeclared| will \emph{also}
- be set to true. The |scalar| function has no effect on this \TeX-if.
- \end{command}
-}
-
-
-\subsection{Syntax for Mathematical Expressions: Operators}
-
-The syntax for the expressions recognized by |\pgfmathparse| and friends is
-rather straightforward. Let us start with the operators.
-
-\label{pgfmath-operators}
-
-The following operators (presented in the context in which they are used) are
-recognized:
-%
-\begin{math-operator}{+}{infix}{add}
- Adds \mvar{x} to \mvar{y}.
-\end{math-operator}
-
-\begin{math-operator}{-}{infix}{subtract}
- Subtracts \mvar{y} from \mvar{x}.
-\end{math-operator}
-
-\begin{math-operator}{-}{prefix}{neg}
- Reverses the sign of \mvar{x}.
-\end{math-operator}
-
-\begin{math-operator}{*}{infix}{multiply}
- Multiplies \mvar{x} by \mvar{y}.
-\end{math-operator}
-
-\begin{math-operator}{/}{infix}{divide}
- Divides \mvar{x} by \mvar{y}. An error will result if \mvar{y} is 0, or if
- the result of the division is too big for the mathematical engine. Please
- remember when using this command that accurate (and reasonably quick)
- division of real numbers that are not integers is particularly tricky in
- \TeX.
-\end{math-operator}
-
-\begin{math-operator}{\char`\^}{infix}{pow}
- Raises \mvar{x} to the power \mvar{y}.
-\end{math-operator}
-
-\begin{math-operator}{\protect\exclamationmarktext}{postfix}{factorial}
- Calculates the factorial of \mvar{x}.
-\end{math-operator}
-
-\begin{math-operator}{r}{postfix}{deg}
- Converts \mvar{x} to degrees (\mvar{x} is assumed to be in radians). This
- operator has the same precedence as multiplication.
-\end{math-operator}
-
-\begin{math-operators}{?}{:}{conditional}{ifthenelse}
- |?| and |:| are special operators which can be used as a shorthand for |if|
- \mvar{x} |then| \mvar{y} |else| \mvar{z} inside the parser. The expression
- \mvar{x} is taken to be true if it evaluates to any non-zero value.
-\end{math-operators}
-
-\begin{math-operator}{==}{infix}{equal}
- Returns |1| if \mvar{x}$=$\mvar{y}, |0| otherwise.
-\end{math-operator}
-
-\begin{math-operator}{>}{infix}{greater}
- Returns |1| if \mvar{x}$>$\mvar{y}, |0| otherwise.
-\end{math-operator}
-
-\begin{math-operator}{<}{infix}{less}
- Returns |1| if \mvar{x}$<$\mvar{y}, |0| otherwise.
-\end{math-operator}
-
-\begin{math-operator}{\protect\exclamationmarktext=}{infix}{notequal}
- Returns |1| if \mvar{x}$\neq$\mvar{y}, |0| otherwise.
-\end{math-operator}
-
-\begin{math-operator}{>=}{infix}{notless}
- Returns |1| if \mvar{x}$\geq$\mvar{y}, |0| otherwise.
-\end{math-operator}
-
-\begin{math-operator}{<=}{infix}{notgreater}
- Returns |1| if \mvar{x}$\leq$\mvar{y}, |0| otherwise.
-\end{math-operator}
-
-\begin{math-operator}{{\char`\&}{\char`\&}}{infix}{and}
- Returns |1| if both \mvar{x} and \mvar{y} evaluate to some non-zero value.
- Both arguments are evaluated.
-\end{math-operator}
-
-{
- \catcode`\|=12
-\begin{math-operator}[no index]{||}{infix}{or}
- \index{*pgfmanualvbarvbarr@\protect\texttt{\protect\pgfmanualvbarvbar} math operator}%
- \index{Math operators!*pgfmanualvbarvbar@\protect\texttt{\protect\pgfmanualvbarvbar}}%
- Returns {\tt 1} if either \mvar{x} or \mvar{y} evaluate to some non-zero
- value.
-\end{math-operator}
-}
-
-\begin{math-operator}{\protect\exclamationmarktext}{prefix}{not}
- Returns |1| if \mvar{x} evaluates to zero, |0| otherwise.
-\end{math-operator}
-
-\begin{math-operators}{(}{)}{group}{}
- These operators act in the usual way, that is, to control the order in
- which operators are executed, for example, |(1+2)*3|. This includes the
- grouping of arguments for functions, for example, |sin(30*10)| or
- |mod(72,3)| (the comma character is also treated as an operator).
-
- Parentheses for functions with one argument are not always necessary,
- |sin 30| (note the space) is the same as |sin(30)|. However, functions have
- the highest precedence so, |sin 30*10| is the same as |sin(30)*10|.
-\end{math-operators}
-
-\begin{math-operators}{\char`\{}{\char`\}}{array}{}
- These operators are used to process array-like structures (within an
- expression these characters do not act like \TeX{} grouping tokens). The
- \meta{array specification} consists of comma separated elements, for
- example, |{1, 2, 3, 4, 5}|. Each element in the array will be evaluated as
- it is parsed, so expressions can be used. In addition, an element of an
- array can be an array itself, allowing multiple dimension arrays to be
- simulated: |{1, {2,3}, {4,5}, 6}|. When storing an array in a macro, do not
- forget the surrounding braces: |\def\myarray{{1,2,3}}| not
- |\def\myarray{1,2,3}|.
- %
-\begin{codeexample}[]
-\def\myarray{{1,"two",2+1,"IV","cinq","sechs",sin(\i*5)*14}}
-\foreach \i in {0,...,6}{\pgfmathparse{\myarray[\i]}\pgfmathresult, }
-\end{codeexample}
- %
-\end{math-operators}
-
-\chardef\lbrack=`\[
-\chardef\rbrack=`\]
-\begin{math-operators}{\lbrack}{\rbrack}{array access}{array}
- |[| and |]| are two operators used in one particular circumstance: to
- access an array (specified using the |{| and |}| operators) using the index
- \mvar{x}. Indexing starts from zero, so, if the index is greater than, or
- equal to, the number of values in the array, an error will occur, and zero
- will be returned.
- %
-\begin{codeexample}[]
-\def\myarray{{7,-3,4,-9,11}}
-\pgfmathparse{\myarray[3]} \pgfmathresult
-\end{codeexample}
-
- If the array is defined to have multiple dimensions, then the array access
- operators can be immediately repeated.
- %
-\begin{codeexample}[]
-\def\print#1{\pgfmathparse{#1}\pgfmathresult}
-\def\identitymatrix{{{1,0,0},{0,1,0},{0,0,1}}}
-\tikz[x=0.5cm,y=0.5cm]\foreach \i in {0,1,2} \foreach \j in {0,1,2}
- \node at (\j,-\i) [anchor=base] {\print{\identitymatrix[\i][\j]}};
-\end{codeexample}
- %
-\end{math-operators}
-
-\begin{math-operators}{\char`\"}{\char`\"}{group}{}
- These operators are used to quote \mvar{x}. However, as every expression is
- expanded with |\edef| before it is parsed, macros (e.g., font commands like
- |\tt| or |\Huge|) may need to be ``protected'' from this expansion (e.g.,
- |\noexpand\Huge|). Ideally, you should avoid such macros anyway. Obviously,
- these operators should be used with great care as further calculations are
- unlikely to be possible with the result.
- %
-\begin{codeexample}[]
-\def\x{5}
-\foreach \y in {0,10}{
- \pgfmathparse{\x > \y ? "\noexpand\Large Bigger" : "\noexpand\tiny smaller"}
- \x\ is \pgfmathresult\ than \y.
-}
-\end{codeexample}
- %
-\end{math-operators}
-
-
-\subsection{Syntax for Mathematical Expressions: Functions}
-\label{pgfmath-functions}
-
-The following functions are recognized:
-
-\medskip
-\def\mathlink#1{\hyperlink{math:#1}{\tt#1}}
-\begin{tikzpicture}
-\foreach \f [count=\i from 0] in
-{abs,acos,add,and,array,asin,atan,atan2,bin,ceil,cos,
- cosec,cosh,cot,deg,depth,dim,div,divide,e,equal,factorial, false,
- floor,frac,gcd,greater,height,hex,Hex,int,ifthenelse,iseven,isodd,isprime,
- less,ln,log10,log2,max,min,mod,Mod,multiply,
- neg,not,notequal,notgreater,notless,
- oct,or,pi,pow,rad,rand,random,real,rnd,round,
- scalar,sec,sign,sin,sinh,sqrt,subtract,tan,tanh,true, veclen,width}
-\node [anchor=base west] at ({int(\i/12)*2.5cm},{-mod(\i,12)*1.1*\baselineskip}) {\mathlink{\f}};
-\end{tikzpicture}
-\bigskip
-
-Each function has a \pgfname{} command associated with it (which is also shown
-with the function below). In general, the command is simply the name of the
-function prefixed with |\pgfmath|, for example, |\pgfmathadd|, but there are
-some notable exceptions.
-
-
-\subsubsection{Basic arithmetic functions}
-\label{pgfmath-functions-basic}
-
-\begin{math-function}{add(\mvar{x},\mvar{y})}
-\mathcommand
- Adds $x$ and $y$.
- %
-\begin{codeexample}[]
-\pgfmathparse{add(75,6)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{subtract(\mvar{x},\mvar{y})}
-\mathcommand
- Subtract $y$ from $x$.
- %
-\begin{codeexample}[]
-\pgfmathparse{subtract(75,6)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{neg(\mvar{x})}
-\mathcommand
- This returns $-\mvar{x}$.
- %
-\begin{codeexample}[]
-\pgfmathparse{neg(50)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{multiply(\mvar{x},\mvar{y})}
-\mathcommand
- Multiply $x$ by $y$.
- %
-\begin{codeexample}[]
-\pgfmathparse{multiply(75,6)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{divide(\mvar{x},\mvar{y})}
-\mathcommand
- Divide $x$ by $y$.
- %
-\begin{codeexample}[]
-\pgfmathparse{divide(75,6)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{div(\mvar{x},\mvar{y})}
-\mathcommand
- Divide $x$ by $y$ and return the integer part of the result.
- %
-\begin{codeexample}[]
-\pgfmathparse{div(75,9)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{factorial(\mvar{x})}
-\mathcommand
- Return \mvar{x}!.
- %
-\begin{codeexample}[]
-\pgfmathparse{factorial(5)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{sqrt(\mvar{x})}
-\mathcommand
- Calculates $\sqrt{\textrm{\mvar{x}}}$.
- %
-\begin{codeexample}[]
-\pgfmathparse{sqrt(10)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{sqrt(8765.432)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{pow(\mvar{x},\mvar{y})}
-\mathcommand
- Raises \mvar{x} to the power \mvar{y}. For greatest accuracy, \mvar{y}
- should be an integer. If \mvar{y} is not an integer, the actual calculation
- will be an approximation of $e^{y \ln(x)}$.
- %
-\begin{codeexample}[]
-\pgfmathparse{pow(2,7)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{e}
-\mathcommand
- Returns the value 2.718281828.
- %
-{
-\catcode`\^=7
-\begin{codeexample}[]
-\pgfmathparse{(e^2-e^-2)/2} \pgfmathresult
-\end{codeexample}
-}
-\end{math-function}
-
-\begin{math-function}{exp(\mvar{x})}
-\mathcommand
-{ \catcode`\^=7
-
- Maclaurin series for $e^x$.
-}
-\begin{codeexample}[]
-\pgfmathparse{exp(1)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{exp(2.34)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{ln(\mvar{x})}
-\mathcommand
-{ \catcode`\^=7
- An approximation for $\ln(\textrm{\mvar{x}})$. This uses an algorithm of
- Rouben Rostamian, and coefficients suggested by Alain Matthes.
-}
-\begin{codeexample}[]
-\pgfmathparse{ln(10)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{ln(exp(5))} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{log10(\mvar{x})}
-\mathcommand[logten(\mvar{x})]
- An approximation for $\log_{10}(\textrm{\mvar{x}})$.
- %
-\begin{codeexample}[]
-\pgfmathparse{log10(100)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{log2(\mvar{x})}
-\mathcommand[logtwo(\mvar{x})]
- An approximation for $\log_2(\textrm{\mvar{x}})$.
- %
-\begin{codeexample}[]
-\pgfmathparse{log2(128)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{abs(\mvar{x})}
-\mathcommand
- Evaluates the absolute value of $x$.
- %
-\begin{codeexample}[]
-\pgfmathparse{abs(-5)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{-abs(4*-3)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{mod(\mvar{x},\mvar{y})}
-\mathcommand
- This evaluates \mvar{x} modulo \mvar{y}, using truncated division. The sign
- of the result is the same as the sign of
- $\frac{\textrm{\mvar{x}}}{\textrm{\mvar{y}}}$.
- %
-\begin{codeexample}[]
-\pgfmathparse{mod(20,6)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{mod(-100,30)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{Mod(\mvar{x},\mvar{y})}
-\mathcommand
- This evaluates \mvar{x} modulo \mvar{y}, using floored division. The sign
- of the result is never negative.
- %
-\begin{codeexample}[]
-\pgfmathparse{Mod(-100,30)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{sign(\mvar{x})}
-\mathcommand
- Returns the sign of $x$.
- %
-\begin{codeexample}[]
-\pgfmathparse{sign(-5)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{sign(0)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{sign(5)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-
-\subsubsection{Rounding functions}
-\label{pgfmath-functions-rounding}
-
-\begin{math-function}{round(\mvar{x})}
-\mathcommand
- Rounds \mvar{x} to the nearest integer. It uses ``asymmetric half-up''
- rounding. So |1.5| is rounded to |2|, but |-1.5| is rounded to |-2|
- (\emph{not} |-1|).
- %
-\begin{codeexample}[]
-\pgfmathparse{round(32.5/17)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{round(398/12)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{floor(\mvar{x})}
-\mathcommand
- Rounds \mvar{x} down to the nearest integer.
- %
-\begin{codeexample}[]
-\pgfmathparse{floor(32.5/17)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{floor(398/12)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{floor(-398/12)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{ceil(\mvar{x})}
-\mathcommand
- Rounds \mvar{x} up to the nearest integer.
- %
-\begin{codeexample}[]
-\pgfmathparse{ceil(32.5/17)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{ceil(398/12)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{ceil(-398/12)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{int(\mvar{x})}
-\mathcommand
- Returns the integer part of \mvar{x}.
- %
-\begin{codeexample}[]
-\pgfmathparse{int(32.5/17)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{frac(\mvar{x})}
-\mathcommand
- Returns the fractional part of \mvar{x}.
- %
-\begin{codeexample}[]
-\pgfmathparse{frac(32.5/17)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{real(\mvar{x})}
-\mathcommand
- Ensures \mvar{x} contains a decimal point.
- %
-\begin{codeexample}[]
-\pgfmathparse{real(4)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-
-\subsubsection{Integer arithmetics functions}
-\label{pgfmath-functions-integerarithmetics}
-
-\begin{math-function}{gcd(\mvar{x},\mvar{y})}
-\mathcommand
- Computes the greatest common divider of \mvar{x} and \mvar{y}.
- %
-\begin{codeexample}[]
-\pgfmathparse{gcd(42,56)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{isodd(\mvar{x})}
-\mathcommand
- Returns |1| if the integer part of \mvar{x} is odd. Otherwise, returns |0|.
- %
-\begin{codeexample}[]
-\pgfmathparse{isodd(2)} \pgfmathresult,
-\pgfmathparse{isodd(3)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{iseven(\mvar{x})}
-\mathcommand
- Returns |1| if the integer part of \mvar{x} is even. Otherwise, returns |0|.
- %
-\begin{codeexample}[]
-\pgfmathparse{iseven(2)} \pgfmathresult,
-\pgfmathparse{iseven(3)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{isprime(\mvar{x})}
-\mathcommand
- Returns |1| if the integer part of \mvar{x} is prime. Otherwise, returns |0|.
- %
-\begin{codeexample}[]
-\pgfmathparse{isprime(1)} \pgfmathresult,
-\pgfmathparse{isprime(2)} \pgfmathresult,
-\pgfmathparse{isprime(31)} \pgfmathresult,
-\pgfmathparse{isprime(64)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-
-\subsubsection{Trigonometric functions}
-\label{pgfmath-functions-trigonometric}
-
-\begin{math-function}{pi}
-\mathcommand
- Returns the value $\pi=3.141592654$.
- %
-\begin{codeexample}[]
-\pgfmathparse{pi} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{pi r} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{rad(\mvar{x})}
-\mathcommand
- Convert \mvar{x} to radians. \mvar{x} is assumed to be in degrees.
- %
-\begin{codeexample}[]
-\pgfmathparse{rad(90)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{deg(\mvar{x})}
-\mathcommand
- Convert \mvar{x} to degrees. \mvar{x} is assumed to be in radians.
- %
-\begin{codeexample}[]
-\pgfmathparse{deg(3*pi/2)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{sin(\mvar{x})}
-\mathcommand
- %
- Sine of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
- radians.
- %
-\begin{codeexample}[]
-\pgfmathparse{sin(60)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{sin(pi/3 r)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{cos(\mvar{x})}
-\mathcommand
- Cosine of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
- radians.
- %
-\begin{codeexample}[]
-\pgfmathparse{cos(60)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{cos(pi/3 r)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{tan(\mvar{x})}
-\mathcommand
- Tangent of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
- radians.
- %
-\begin{codeexample}[]
-\pgfmathparse{tan(45)} \pgfmathresult
-\end{codeexample}
-
-\begin{codeexample}[]
-\pgfmathparse{tan(2*pi/8 r)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{sec(\mvar{x})}
-\mathcommand
- Secant of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
- radians.
- %
-\begin{codeexample}[]
-\pgfmathparse{sec(45)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{cosec(\mvar{x})}
-\mathcommand
- Cosecant of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
- radians.
- %
-\begin{codeexample}[]
-\pgfmathparse{cosec(30)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{cot(\mvar{x})}
-\mathcommand
- Cotangent of \mvar{x}. By employing the |r| operator, \mvar{x} can be in
- radians.
- %
-\begin{codeexample}[]
-\pgfmathparse{cot(15)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{asin(\mvar{x})}
-\mathcommand
- Arcsine of \mvar{x}. The result is in degrees and in the range $\pm90^\circ$.
- %
-\begin{codeexample}[]
-\pgfmathparse{asin(0.7071)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{acos(\mvar{x})}
-\mathcommand
- Arccosine of \mvar{x} in degrees. The result is in the range $[0^\circ,180^\circ]$.
- %
-\begin{codeexample}[]
-\pgfmathparse{acos(0.5)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{atan(\mvar{x})}
-\mathcommand
- Arctangent of $x$ in degrees.
- %
-\begin{codeexample}[]
-\pgfmathparse{atan(1)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{atan2(\mvar{y},\mvar{x})}
-\mathcommand[atantwo(\mvar{y},\mvar{x})]
- Arctangent of $y\div x$ in degrees. This also takes into account the
- quadrants.
- %
-\begin{codeexample}[]
-\pgfmathparse{atan2(-4,3)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{key}{/pgf/trig format=\mchoice{deg,rad} (initially deg)}
- Allows to define whether trigonometric math functions (i.e.\ all in this
- subsection) operate with degrees or with radians.
- %
-\begin{codeexample}[]
-\pgfmathparse{cos(45)} \pgfmathresult
-\end{codeexample}
-\begin{codeexample}[]
-\pgfkeys{/pgf/trig format=rad}
-\pgfmathparse{cos(pi/2)} \pgfmathresult
-\end{codeexample}
-
- The initial configuration |trig format=deg| is the base of \pgfname: almost
- all of it is based on degrees.
-
- Specifying |trig format=rad| is most useful for data visualization where
- the angles are typically given in radians. However, it is applied to all
- trigonometric functions for which the option applies, including any drawing
- instructions which operate on angles.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[-stealth]
- (0:1) -- (45:1) -- (90:1) -- (135:1) -- (180:1);
-
- \draw[-stealth,trig format=rad,red]
- (pi:1) -- (5/4*pi:1) -- (6/4*pi:1) -- (7/4*pi:1) -- (2*pi:1);
-\end{tikzpicture}
-\end{codeexample}
-
- \paragraph{Warning:}
- At the time of this writing, this feature is ``experimental''. Please
- handle it with care: there may be path instructions or libraries in
- \pgfname\ which rely on |trig format=deg|. The intended usage of
- |trig format=rad| is for local scopes -- and as option for data
- visualization.
-\end{key}
-
-
-\subsubsection{Comparison and logical functions}
-\label{pgfmath-functions-comparison}
-
-\begin{math-function}{equal(\mvar{x},\mvar{y})}
-\mathcommand
- This returns |1| if $\mvar{x}=\mvar{y}$ and |0| otherwise.
- %
-\begin{codeexample}[]
-\pgfmathparse{equal(20,20)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{greater(\mvar{x},\mvar{y})}
-\mathcommand
- This returns |1| if $\mvar{x}>\mvar{y}$ and |0| otherwise.
- %
-\begin{codeexample}[]
-\pgfmathparse{greater(20,25)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{less(\mvar{x},\mvar{y})}
-\mathcommand
- This returns |1| if $\mvar{x}<\mvar{y}$ and |0| otherwise.
- %
-\begin{codeexample}[]
-\pgfmathparse{greater(20,25)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{notequal(\mvar{x},\mvar{y})}
-\mathcommand
- This returns |0| if $\mvar{x}=\mvar{y}$ and |1| otherwise.
- %
-\begin{codeexample}[]
-\pgfmathparse{notequal(20,25)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{notgreater(\mvar{x},\mvar{y})}
-\mathcommand
- This returns |1| if $\mvar{x}\leq\mvar{y}$ and |0| otherwise.
- %
-\begin{codeexample}[]
-\pgfmathparse{notgreater(20,25)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{notless(\mvar{x},\mvar{y})}
-\mathcommand
- This returns |1| if $\mvar{x}\geq\mvar{y}$ and |0| otherwise.
- %
-\begin{codeexample}[]
-\pgfmathparse{notless(20,25)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{and(\mvar{x},\mvar{y})}
-\mathcommand
- This returns |1| if \mvar{x} and \mvar{y} both evaluate to non-zero values.
- Otherwise |0| is returned.
- %
-\begin{codeexample}[]
-\pgfmathparse{and(5>4,6>7)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{or(\mvar{x},\mvar{y})}
-\mathcommand
- This returns |1| if either \mvar{x} or \mvar{y} evaluate to non-zero
- values. Otherwise |0| is returned.
- %
-\begin{codeexample}[]
-\pgfmathparse{or(5>4,6>7)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{not(\mvar{x})}
-\mathcommand
- This returns |1| if $\mvar{x}=0$, otherwise |0|.
- %
-\begin{codeexample}[]
-\pgfmathparse{not(true)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{ifthenelse(\mvar{x},\mvar{y},\mvar{z})}
-\mathcommand
- This returns \mvar{y} if \mvar{x} evaluates to some non-zero value,
- otherwise \mvar{z} is returned.
- %
-\begin{codeexample}[]
-\pgfmathparse{ifthenelse(5==4,"yes","no")} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{true}
-\mathcommand
- This evaluates to |1|.
- %
-\begin{codeexample}[]
-\pgfmathparse{true ? "yes" : "no"} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{false}
-\mathcommand
- This evaluates to |0|.
- %
-\begin{codeexample}[]
-\pgfmathparse{false ? "yes" : "no"} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-
-\subsubsection{Pseudo-random functions}
-\label{pgfmath-functions-random}
-
-\begin{math-function}{rnd}
-\mathcommand
- Generates a pseudo-random number between $0$ and $1$ with a uniform
- distribution.
- %
-\begin{codeexample}[pre={\pgfmathsetseed{1}}]
-\foreach \x in {1,...,10}{\pgfmathparse{rnd}\pgfmathresult, }
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{rand}
-\mathcommand
- Generates a pseudo-random number between $-1$ and $1$ with a uniform
- distribution.
- %
-\begin{codeexample}[pre={\pgfmathsetseed{1}}]
-\foreach \x in {1,...,10}{\pgfmathparse{rand}\pgfmathresult, }
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{random(\opt{\mvar{x},\mvar{y}})}
-\mathcommand
- This function takes zero, one or two arguments. If there are zero
- arguments, a uniform random number between $0$ and $1$ is generated. If
- there is one argument \mvar{x}, a random integer between $1$ and \mvar{x}
- is generated. Finally, if there are two arguments, a random integer between
- \mvar{x} and \mvar{y} is generated. If there are no arguments, the
- \pgfname{} command should be called as follows: |\pgfmathrandom{}|.
- %
-\begin{codeexample}[pre={\pgfmathsetseed{1}}]
-\foreach \x in {1,...,10}{\pgfmathparse{random()}\pgfmathresult, }
-\end{codeexample}
-
-\begin{codeexample}[pre={\pgfmathsetseed{1}}]
-\foreach \x in {1,...,10}{\pgfmathparse{random(100)}\pgfmathresult, }
-\end{codeexample}
-
-\begin{codeexample}[pre={\pgfmathsetseed{1}}]
-\foreach \x in {1,...,10}{\pgfmathparse{random(232,762)}\pgfmathresult, }
-\end{codeexample}
- %
-\end{math-function}
-
-
-\subsubsection{Base conversion functions}
-\label{pgfmath-functions-base}
-
-\begin{math-function}{hex(\mvar{x})}
-\mathcommand
- Convert \mvar{x}{} (assumed to be an integer in base 10) to a hexadecimal
- representation, using lower case alphabetic digits. No further calculation
- will be possible with the result.
- %
-\begin{codeexample}[]
-\pgfmathparse{hex(65535)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{Hex(\mvar{x})}
-\mathcommand
- Convert \mvar{x}{} (assumed to be an integer in base 10) to a hexadecimal
- representation, using upper case alphabetic digits. No further calculation
- will be possible with the result.
- %
-\begin{codeexample}[]
-\pgfmathparse{Hex(65535)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{oct(\mvar{x})}
-\mathcommand
- Convert \mvar{x}{} (assumed to be an integer in base 10) to an octal
- representation. No further calculation should be attempted with the result,
- as the parser can only process numbers converted to base 10.
- %
-\begin{codeexample}[]
-\pgfmathparse{oct(63)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{bin(\mvar{x})}
-\mathcommand
- Convert \mvar{x}{} (assumed to be an integer in base 10) to a binary
- representation. No further calculation should be attempted with the result,
- as the parser can only process numbers converted to base 10.
- %
-\begin{codeexample}[]
-\pgfmathparse{bin(185)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-
-\subsubsection{Miscellaneous functions}
-\label{pgfmath-functions-misc}
-
-\begin{math-function}{min(\mvar{x$_1$},\mvar{x$_2$},\ldots,\mvar{x$_n$})}
-\mathcommand[min({\mvar{x$_1$},\mvar{x$_2$},\ldots},{\ldots,\mvar{x$_{n-1}$},\mvar{x$_n$}})]
- Return the minimum value from \mvar{x$_1$}\ldots\mvar{x$_n$}. For
- historical reasons, the command |\pgfmathmin| takes two arguments, but each
- of these can contain an arbitrary number of comma separated values.
- %
-\begin{codeexample}[]
-\pgfmathparse{min(3,4,-2,250,-8,100)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{max(\mvar{x$_1$},\mvar{x$_2$},\ldots,\mvar{x$_n$})}
-\mathcommand[max({\mvar{x$_1$},\mvar{x$_2$},\ldots},{\ldots,\mvar{x$_{n-1}$},\mvar{x$_n$}})]
- Return the maximum value from \mvar{x$_1$}\ldots\mvar{x$_n$}. Again, for
- historical reasons, the command |\pgfmathmax| takes two arguments, but each
- of these can contain an arbitrary number of comma separated values.
- %
-\begin{codeexample}[]
-\pgfmathparse{max(3,4,-2,250,-8,100)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{veclen(\mvar{x},\mvar{y})}
-\mathcommand
- Calculates $\sqrt{\left(\textrm{\mvar{x}}^2+\textrm{\mvar{y}}^2\right)}$.
- This uses a polynomial approximation, based on ideas of Rouben Rostamian
- %
-\begin{codeexample}[]
-\pgfmathparse{veclen(12,5)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{array(\mvar{x},\mvar{y})}
-\mathcommand
- This accesses the array \mvar{x} at the index \mvar{y}. The array must
- begin and end with braces (e.g., |{1,2,3,4}|) and array indexing starts at
- |0|.
- %
-\begin{codeexample}[]
-\pgfmathparse{array({9,13,17,21},2)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{dim(\mvar{x})}
-\mathcommand
- This returns the dimension of the array \mvar{x}. The array must begin and
- end with braces (e.g., |{1,2,3,4}|).
- %
-\begin{codeexample}[]
-\pgfmathparse{dim({1,2,3,4})} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-The following hyperbolic functions were adapted from code suggested by Martin
-Heller:
-
-\begin{math-function}{sinh(\mvar{x})}
-\mathcommand
- The hyperbolic sine of \mvar{x}
- %
-\begin{codeexample}[]
-\pgfmathparse{sinh(0.5)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{cosh(\mvar{x})}
-\mathcommand
- The hyperbolic cosine of \mvar{x}
- %
-\begin{codeexample}[]
-\pgfmathparse{cosh(0.5)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{tanh(\mvar{x})}
-\mathcommand
- The hyperbolic tangent of \mvar{x}
- %
-
-\begin{codeexample}[]
-\pgfmathparse{tanh(0.5)} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{width("\mvar{x}")}
-\mathcommand
- Return the width of a \TeX{} (horizontal) box containing \mvar{x}. The
- quote characters are necessary to prevent \mvar{x}{} from being parsed. It
- is important to remember that any expression is expanded with |\edef|
- before being parsed, so any macros (e.g., font commands like |\tt| or
- |\Huge|) will need to be ``protected'' (e.g., |\noexpand\Huge| is usually
- sufficient).
- %
-\begin{codeexample}[]
-\pgfmathparse{width("Some Lovely Text")} \pgfmathresult
-\end{codeexample}
-
- Note that results of this method are provided in points.
-\end{math-function}
-
-\begin{math-function}{height("\mvar{x}")}
-\mathcommand
- Return the height of a box containing \mvar{x}.
- %
-\begin{codeexample}[]
-\pgfmathparse{height("Some Lovely Text")} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
-
-\begin{math-function}{depth("\mvar{x}")}
-\mathcommand
- Returns the depth of a box containing \mvar{x}.
- %
-\begin{codeexample}[]
-\pgfmathparse{depth("Some Lovely Text")} \pgfmathresult
-\end{codeexample}
- %
-\end{math-function}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-module-parser.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-module-parser.tex
deleted file mode 100644
index 143bc16851..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-module-parser.tex
+++ /dev/null
@@ -1,311 +0,0 @@
-% Copyright 2019 by Till Tantau
-% Copyright 2019 by Jonathan P. Spratte
-%
-% 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{Parser Module}%
-\label{section-module-parser}%
-
-\begin{pgfmodule}{parser}%
- This module defines some commands for creating a simple letter-by-letter
- parser.
-\end{pgfmodule}
-
-\begin{package}{pgfparser}
- Because the parser module is almost independent of the rest of \pgfname, it
- can also be used as a standalone package with minimal dependencies.
-\end{package}
-
-This module provides commands for defining a parser that scans some given text
-letter-by-letter. For each letter, some code is executed and, possibly a
-state-switch occurs. The code for each letter might take mandatory or optional
-arguments. The parsing process ends when a final state has been reached, and
-optionally some code is executed afterwards.
-
-\begin{command}{\pgfparserparse\marg{parser name}\meta{text}}%
- This command is used to parse the \meta{text} using the (previously defined)
- parser named \meta{parser name}.
-
- The \meta{text} is not contained in curly braces, rather it is all the text
- that follows. The end of the text is determined implicitly, namely when the
- final state of the parser has been reached. If you defined a final action for
- the parser using |\pgfparserdeffinal| it is executed now.
-
- The parser works as follows: At any moment, it is in a certain
- \emph{state}, initially this state is called |initial|. Then, the first
- letter of the \meta{text} is examined (using the |\futurelet| command). For
- each possible state and each possible letter, some action code is stored in
- the parser in a table. This code is then executed. This code may, but need
- not, trigger a \emph{state switch}, causing a new state to be set. The
- parser then moves on to the next character of the text and repeats the
- whole procedure, unless it is in the state |final|, which causes the
- parsing process to stop immediately.
-
- In the following example, the parser counts the number of |a|'s in the
- \text{text}, ignoring any |b|'s. The \meta{text} ends with the first~|c|.
- %
-\begin{codeexample}[preamble={\usepgfmodule{parser}}]
-\newcount\mycount
-\pgfparserdef{myparser}{initial}{the letter a}%
-{\advance\mycount by 1\relax}%
-\pgfparserdef{myparser}{initial}{the letter b}%
-{} % do nothing
-\pgfparserdef{myparser}{initial}{the letter c}%
-{\pgfparserswitch{final}}% done!
-
-\pgfparserparse{myparser}aabaabababbbbbabaabcccc
-There are \the\mycount\ a's.
-\end{codeexample}%
- %
-\end{command}%
-
-\begin{command}%
- {%
- \pgfparserdef\marg{parser name}\marg{state}\meta{symbol meaning}%
- \oarg{arguments}\marg{action}%
- }%
- This command should be used repeatedly to define a parser named
- \meta{parser name}. With a call to this command you specify that the
- \meta{parser name} should do the following: When it is in state
- \meta{state} and reads the letter \meta{symbol meaning}, perform the code
- stored in \meta{action}.
-
- The \meta{symbol meaning} must be the text that results from applying the
- \TeX\ command |\meaning| to the given character. For instance, |\meaning a|
- yields |the letter a|, while |\meaning 1| yields |the character 1|. A space
- yields |blank space |. Alternatively you can give the symbol you want without
- surrounding it in braces. So both
- |\pgfparserdef{myparser}{initial}{the letter a}{foo}|
- and
- |\pgfparserdef{myparser}{initial}a{foo}|
- define an \meta{action} for |the letter a|. This short form works for most
- tokens, but not for a space (in which case you can use
- |\pgfparserdef{myparser}{initial}{blank space}{foo}|), and opening braces
- (in which case you can use
- |\pgfparserdef{myparser}{initial}{\meaning\bgroup}{foo}|, and one might prefer
- to use |\pgfparserdef{myparser}{initial}{\meaning\egroup}{foo}| for closing
- braces as well). You can as well define an action for a macro's meaning (note
- that macros with different names can have the same meaning), so things like
- |\pgfparserdef{myparser}{initial}\texttt{foo}| are possible as well.
-
- The \meta{action} might require arguments which you can specify in the
- optional \meta{arguments} string. The argument string can contain up to nine
- argument specifications of the following types:
-
- \begingroup
- \def\argdesc#1#2%
- {%
- \par
- \begingroup
- \setbox0\hbox{\texttt #1}\makebox[1.5em][l]{\usebox0}%
- \ifdim\wd0>1.5em\\\null\hspace{1.5em}\fi
- \parbox[t]{\dimexpr\linewidth-1.5em\relax}{#2}%
- \endgroup
- }%
- \argdesc{m}%
- {a normal mandatory argument}%
- \argdesc{r\meta{delim}}%
- {a mandatory argument which is read up to the \meta{delim}}%
- \argdesc{o}%
- {an optional argument in |[]| defaulting to a special mark}%
- \argdesc{O\marg{default}}%
- {like |o| but defaulting to \meta{default}}%
- \argdesc{d\meta{delim1}\meta{delim2}}%
- {%
- an optional argument in \meta{delim1} and \meta{delim2} defaulting to a
- special mark%
- }%
- \argdesc{D\meta{delim1}\meta{delim2}\marg{default}}%
- {like |d| but defaulting to \meta{default}}%
- \argdesc{t\meta{token}}%
- {%
- tests whether the next letter is \meta{token}, if so gobbles it and
- the argument is set to a special mark.%
- }%
- \endgroup
-
- So if you want to define an \meta{action} that takes two mandatory arguments
- you use |[mm]|, if it should take an optional star, one optional argument in
- brackets that returns a marker if it's not used, one mandatory and finally an
- optional argument in parentheses that defaults to |something| you use
- |[t*omD(){something}]| as the argument string. If the argument should be
- anything up to a semicolon, you use |[r;]|. Spaces before argument
- specifications in the string are ignored. So |[r m]| will be one argument and
- read anything up to an |m|. Also spaces before any argument in the parsed
- letters are ignored, so if |a| was setup to take an optional argument the
- argument would be detected in |a []|. Like with normal \LaTeXe\ optional
- arguments you have to protect nested brackets: |[a[bc]d]| would be read as
- |a[bc| with a trailing |d]|, \emph{not} as |a[bc]d|. You'd have to use
- |[{a[bc]d}]| to get it correct.
-
- Inside the \meta{action} you can perform almost any kind of code. This code
- will not be surrounded by a scope, so its effect persists after the parsing
- is done. However, each time after the \meta{action} is executed, control
- goes back to the parser. You should not launch a parser inside the
- \meta{action} code, unless you put it in a scope.
-
- When you use |all| as the \meta{state}, the \meta{action} is performed
- in all states as a fallback, whenever \meta{symbol meaning} is encountered.
- This means that when you do not specify anything explicitly for a state and a
- letter, but you do specify something for |all| and this letter, then the
- specified \meta{action} will be used.
-
- When the parser encounters a letter for which nothing is specified in the
- current state (neither directly nor indirectly via |all|), an error occurs.
- Additionally you can specify an action that is executed after the error is
- thrown using |\pgfparserdefunknown|. To suppress these errors (but not the
- action specified with |\pgfparserdefunknown|) you can use the
- |/pgfparser/silent| key or the |silent| key of the current \meta{parser name}.
-\end{command}%
-
-\begin{command}%
- {%
- \pgfparserlet
- \marg{parser name 1}\marg{state 1}\meta{symbol meaning 1}%
- \oarg{opt 1}\oarg{opt 2}\meta{symbol meaning 2}%
- }%
- If none of the optional arguments are given in the following explanation
- \meta{parser name 2} and \meta{state 2} are the same as
- \meta{parser name 1} and \meta{state 1}. If only the first is given
- \meta{state 2} equals \meta{opt 1}. If both are given \meta{parser name 2}
- equals \meta{opt 1} and \meta{state 2} equals \meta{opt 2}.
-
- Defines an action for \meta{parser name 1} in \meta{state 1} for the
- \meta{symbol meaning 1} to do the same as the action of \meta{parser name 2}
- in \meta{state 2} for the \meta{symbol meaning 2}. For \meta{symbol meaning 1}
- and \meta{symbol meaning 2} the same parsing rules apply as for \meta{symbol
- meaning} in |\pgfparserdef| so you either give the meaning in braces or just
- the symbol.
-\end{command}%
-
-\begin{command}{\pgfparserdefunknown\marg{parser name}\marg{state}\marg{action}}%
- With this macro you can define an \meta{action} for the \meta{parser name}
- parser in \meta{state} if no action was defined for the letter which was
- encountered.
-\end{command}%
-
-\begin{command}{\pgfparserdeffinal\marg{parser name}\marg{action}}%
- Every parser can call a final \meta{action} after the state was switched to
- |final|. This \meta{action} is executed after everything else, so you can use
- something that grabs more arguments if you want to.
-\end{command}%
-
-\begin{command}{\pgfparserswitch\marg{state}}%
- This command can be called inside the action code of a parser to cause a
- state switch to \meta{state}.
-\end{command}%
-
-\begin{command}{\pgfparserifmark\marg{arg}\marg{true}\marg{false}}%
- Remember that some of the optional argument types set special marks? With
- |\pgfparserifmark| you can test whether \meta{arg} is such a mark. So if
- there was no optional argument for the argument types |o| and |d| the
- \meta{true} branch will be executed, else the \meta{false} branch. For the |t|
- type argument the \meta{true} branch is executed if the token was encountered.
-\end{command}%
-
-\begin{command}{\pgfparserreinsert}%
- You can use this as the final macro in an action of |\pgfparserdef| or
- |\pgfparserdefunknown|. This has the effect that the contents of
- |\pgfparserletter| will be parsed next. Without any redefinition the result
- will be that the last token will be parsed again. You can change the
- definition of |\pgfparserletter| just before |\pgfparserreinsert| as well to
- parse some specific tokens next.
-\end{command}%
-
-\begin{command}{\pgfparserstate}%
- Expands to the current state of the parser.
-\end{command}%
-
-\begin{command}{\pgfparsertoken}%
- This is the macro which is let to the following token with |\futurelet|. You
- can use it inside an action code.
-\end{command}%
-
-\begin{command}{\pgfparserletter}%
- This macro stores the letter to which |\pgfparsertoken| was let. So if
- you'd use |\pgfparserparse{foo}a| this macro would be defined with
- |\def\pgfparserletter{a}|. This definition is done before any action code is
- executed. There are four special cases: If the next token is of category code
- 1, 2, 6, or 10, so with standard category codes the tokens |{|, |}|, |#|, and
- \textvisiblespace\ (a space), it would be treated differently. In those cases
- this macro expands to |\bgroup|, |\egroup|, |##|, and \textvisiblespace\ for
- the categories 1, 2, 6, and 10, respectively.
-\end{command}%
-
-\begin{command}{\pgfparserset\marg{key list}}%
- The |pgfparser| module has a few keys you can access through this macro. It
- is just a shortcut for |\pgfset{/pgfparser/.cd,#1}|. The available keys are
- listed in subsection~\ref{sec:parser:keys}.
-\end{command}%
-
-
-\subsection{Keys of the Parser Module}
-\label{sec:parser:keys}
-
-\begin{key}{/pgfparser/silent=\meta{boolean} (initially false)}%
- If |true| then no error will be thrown when a letter is parsed for which no
- action is specified, silently ignoring it. This holds true for every parser.
-\end{key}%
-
-\begin{key}{/pgfparser/status=\meta{boolean} (initially false)}%
- If |true| every parser prints a status message for every action executed. This
- might help in debugging and understanding what the parser does.
-\end{key}%
-
-Additionally to those keys for every \meta{parser name} for which
-|\pgfparserdef|, |\pgfparserdefunknown| or |\pgfparserlet| was run at least once
-the following will be defined:
-
-\begin{key}{/pgfparser/\meta{parser name}/silent=\meta{boolean} (initially false)}%
- If |true| the parser \meta{parser name} will silently ignore undefined
- letters. This is an individual equivalent of |/pgfparser/silent| for each
- defined parser.
-\end{key}%
-
-
-\subsection{Examples}
-
-The following example counts the different letters appearing in a more or less
-random string of letters. Every letter is counted only once, this is achieved
-by defining a new action for every encountered unknown letter that does
-nothing. We can define such rule without knowing which letter is used, because
-|\pgfparsertoken| has the same meaning as that letter.
-%
-\begin{codeexample}[
- preamble={\usepgfmodule{parser}},
- pre={\newcount\mycount},
-]
-\mycount=0
-% using the shortcut syntax of just placing ; after the state
-\pgfparserdef{different letters}{all};{\pgfparserswitch{final}}%
-\pgfparserdefunknown{different letters}{all}%
- {\pgfparserdef{different letters}{all}\pgfparsertoken{}\advance\mycount1}%
-\pgfparserdeffinal{different letters}%
- {\the\mycount\ different letters found}%
-% don't throw errors for unknown letters
-\pgfparserset{different letters/silent=true}%
-
-\pgfparserparse{different letters}udiaternxqlchudiea;
-\end{codeexample}%
-
-Next we want to try something that uses some of the different argument types
-available.
-%
-\begin{codeexample}[preamble={\usepgfmodule{parser}}]
-% using the long syntax of \pgfparserdef
-\pgfparserdef{arguments}{initial}{the letter a}[d()]
- {\pgfparserifmark{#1}{\textcolor{red}{\textit{use}}}{\textbf{#1}} }%
-% using the shortcut syntax
-\pgfparserdef{arguments}{initial}t[m]{\texttt{#1} }%
-\pgfparserdef{arguments}{initial}c[t*O{blue}m]
- {\pgfparserifmark{#1}{#3}{\textcolor{#2}{#3}}}%
-\pgfparserdef{arguments}{all};{\pgfparserswitch{final}}%
-
-\pgfparserparse{arguments}t{nobody}a(will)ac[green]{P}c*{arse}c{r};
-\end{codeexample}%
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-oo.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-oo.tex
deleted file mode 100644
index 66ddbc6c4a..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-oo.tex
+++ /dev/null
@@ -1,690 +0,0 @@
-% Copyright 2018 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{Object-Oriented Programming}
-\label{section-oop}
-
-This section describes the |oo| module.
-
-\begin{pgfmodule}{oo}
- This module defines a relatively small set of \TeX\ commands for defining
- classes, methods, attributes and objects in the sense of object-oriented
- programming.
-\end{pgfmodule}
-
-In this chapter it is assumed that you are familiar with the basics of a
-typical object-oriented programming language like Java, C++ or Eiffel.
-
-
-\subsection{Overview}
-
-\TeX\ does not support object-oriented programming, presumably because it was
-written at a time when this style of programming was not yet ``en vogue''. When
-one is used to the object-oriented style of thinking, some programming
-constructs in \TeX\ often seem overly complicated. The object-oriented
-programming module of \pgfname\ may help here. It is written completely using
-simple \TeX\ macros and is, thus, perfectly portable. This also means, however,
-that it is not particularly fast (but not too slow either), so you should use
-it only for non-time-critical things.
-
-Basically, the oo-system supports \emph{classes} (in the object-oriented sense,
-this has nothing to do with \LaTeX-classes), \emph{methods},
-\emph{constructors}, \emph{attributes}, \emph{objects}, \emph{object
-identities}, and (thanks to Sa\v so \v Zivanovi\'c) \emph{inheritance} and
-\emph{overloading.}
-
-The first step is to define a class, using the macro |\pgfooclass| (all normal
-macros in \pgfname's object-oriented system start with |\pgfoo|). This macro
-gets the name of a class and in its body a number of \emph{methods} are
-defined. These are defined using the |\method| macro (which is defined only
-inside such a class definition) and they look a bit like method definitions in,
-say, Java. Object attributes are declared using the |\attribute| command, which
-is also defined only inside a class definition.
-
-Once a class has been defined, you can create objects of this class. Objects
-are created using |\pgfoonew|. Such an object has many characteristics of
-objects in a normal object-oriented programming language: Each object has a
-\emph{unique identity}, so when you create another object, this object is
-completely distinct from all other objects. Each object also has a set of
-private attributes, which may change over time. Suppose, for instance, that we
-have a |point| class. Then creating a new object (called an instance) of this
-class would typically have an |x|-attribute and a |y|-attribute. These can be
-changed over time. Creating another instance of the |point| class creates
-another object with its own |x|- and |y|-attributes.
-
-Given an object, you can call a method for this object. Inside the method the
-attributes of the object for which the method is being called can be accessed.
-
-The life of an object always ends with the end of the \TeX\ scope in which it
-was created. However, changes to attribute values are not local to scopes, so
-when you change an attribute anywhere, this change persists till the end of the
-life of the object or until the attribute is changed again.
-
-
-\subsection{A Running Example: The Stamp Class}
-
-As a running example we will develop a |stamp| class and |stamp| objects. The
-idea is that a stamp object is able to ``stamp something'' on a picture. This
-means that a stamp object has an attribute storing the ``stamp text'' and there
-is a method that asks the object to place this text somewhere on a canvas. The
-method can be called repeatedly and there can be several different stamp
-objects, each producing a different text. Stamp objects can either be created
-dynamically when needed or a library might define many such objects in an outer
-scope.
-
-Such stamps are similar to many things present in \pgfname\ such as arrow tips,
-patterns, or shadings and, indeed, these could all have been implemented in
-this object-oriented fashion (which might have been better, but the
-object-oriented subsystem is a fairly new addition to \pgfname).
-
-
-\subsection{Classes}
-
-We start with the definition of the |stamp| class. This is done using the
-|\pgfooclass| macro:
-
-\begin{command}{\pgfooclass\opt{|(|\meta{list of superclasses}|)|}\marg{class name}\marg{body}}
- This command defines a class named \meta{class name}. The name of the class
- can contain spaces and most other characters, but no periods. So, valid
- class names are |MyClass| or |my class| or |Class_C++_emulation??1|. The
- \meta{list of superclasses} is optional just like the parenthesis around
- it.
-
- The \meta{body} is actually just executed, so any normal \TeX-code is
- permissible here. However, while the \meta{body} is being executed, the
- macros |\method| and |\attribute| are set up so that they can be used to
- define methods and attributes for this class (the original meanings are
- restored afterward).
-
- The definition of a class is local to the scope where the class has been
- defined.
- %
-\begin{codeexample}[code only]
-\pgfooclass{stamp}{
- % This is the class stamp
-
- \attribute text;
- \attribute rotation angle=20;
-
- \method stamp(#1) { % The constructor
- ...
- }
-
- \method apply(#1,#2) { % Causes the stamp to be shown at coordinate (#1,#2)
- ...
- }
-}
-
-% We can now create objects of type "stamp"
-\end{codeexample}
-
- Concerning the list of base classes, the Method Resolution Order
- (\textsc{mro}) is computed using the C3 algorithm also used in Python, v2.3
- and higher. The linearization computed by the algorithm respects both
- local precedence ordering and monotonicity. Resolution of both methods and
- attributes depends on the \textsc{mro}: when a method method name is called
- on an object of class $C$, the system invokes method method name from the
- first class in the \textsc{mro} of $C$ which defines method method name;
- when an object is created, each attribute |attr| is initialized to the
- value specified in the first class in the \textsc{mro} of $C$ which
- declares attribute |attr|.
-\end{command}
-
-The \meta{body} of a class usually just consists of calls to the macros
-|\attribute| and |\method|, which will be discussed in more detail in later
-sections.
-
-
-\subsection{Objects}
-
-Once a class has been declared, we can start creating objects for this class.
-For this the |\pgfoonew| command can be used, which has a peculiar syntax:
-
-\begin{command}{\pgfoonew\opt{\meta{object handle or attribute}|=|}|new |\meta{class name}|(|\meta{constructor arguments}|)|}
- Causes a new object to be created. The class of the object will be
- \meta{class name}, which must previously have been declared using
- |\pgfooclass|. Once the object has been created, the constructor method of
- the object will be called with the parameter list set to \meta{constructor
- arguments}.
-
- The resulting object is stored internally and its lifetime will end exactly
- at the end of the current scope.
-
- Here is an example in which three stamp objects are created.
- %
-\begin{codeexample}[code only]
-\pgfoonew \firststamp=new stamp()
-\pgfoonew \secondstamp=new stamp()
-{
- \pgfoonew \thirdstamp=new stamp()
- ...
-}
-% \thirdstamp no longer exists, but \firststamp and \secondstamp do
-% even if you try to store \thirdstamp in a global variable, trying
-% to access it will result in an error.
-\end{codeexample}
-
- The optional \meta{object handle or attribute} can either be an
- \meta{object handle} or an \meta{attribute}. When an \meta{object handle}
- is given, it must be a normal \TeX\ macro name that will ``point'' to the
- object (handles are discussed in more detail in
- Section~\ref{section-identities}). You can use this macro to call methods
- of the object as discussed in the following section. When an
- \meta{attribute} is given, it must be given in curly braces (the curly
- braces are used to detect the presence of an attribute). In this case, a
- handle to the newly created object is stored in this attribute.
- %
-\begin{codeexample}[code only]
-\pgfooclass{foo}
-{
- \attribute stamp obj;
- \attribute another object;
-
- \method foo() {
- \pgfoonew{stamp obj}=new stamp()
- \pgfoonew{another object}=new bar()
- }
- ...
-}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfoogc}
- This command causes the ``garbage collector'' to be invoked. The job of
- this garbage collector is to free the global \TeX-macros that are used by
- ``dead'' objects (objects whose life-time has ended). This macro is called
- automatically after every scope in which an object has been created, so you
- normally do not need to call this macro yourself.
-\end{command}
-
-
-\subsection{Methods}
-
-Methods are defined inside the body of classes using the following command:
-
-\begin{command}{\method \meta{method name}|(|\meta{parameter list}|)|\marg{method body}}
- This macro, which is only defined inside a class definition, defines a new
- method named \meta{method name}. Just like class names, method names can
- contain spaces and other characters, so \meta{method names} like
- |put_stamp_here| or |put stamp here| are both legal.
-
- Three method names are special: First, a method having either the same name
- as the class or having the name |init| is called the \emph{constructor} of
- the class. There are (currently) no destructors; objects simply become
- ``undefined'' at the end of the scope in which they have been created. The
- other two methods are called |get id| and |get handle|, which are always
- automatically defined and which you cannot redefine. They are discussed in
- Section~\ref{section-identities}.
-
- Overloading of methods by differing numbers of parameters is not possible,
- that is, it is illegal to have two methods inside a single class with the
- same name (despite possibly different parameter lists). However, two
- different classes may contain a method with the same name, that is, classes
- form namespaces for methods. Also, a class can (re)implement a method from
- a superclass.
-
- The \meta{method name} must be followed by a \meta{parameter list} in
- parentheses, which must be present even when the \meta{parameter list} is
- empty. The \meta{parameter list} is actually a normal \TeX\ parameter list
- that will be matched against the parameters inside the parentheses upon
- method invocation and, thus, could be something like |#1#2 foo #3 bar.|,
- but a list like |#1,#2,#3| is more customary. By setting the parameter list
- to just |#1| and then calling, say, |\pgfkeys{#1}| at the beginning of a
- method, you can implement Objective-C-like named parameters.
-
- When a method is called, the \meta{body} of the method will be executed.
- The main difference to a normal macro is that while the \meta{body} is
- executed, a special macro called |\pgfoothis| is set up in such a way that
- it references the object for which the method is executed.
-\end{command}
-
-In order to call a method for an object, you first need to create the object
-and you need a handle for this object. In order to invoke a method for this
-object, a special syntax is used that is similar to Java or C++ syntax:
-
-\begin{pgfmanualentry}
- \pgfmanualentryheadline{\meta{object handle}\opt{|.|\meta{super class}}|.|\meta{method name}|(|\meta{parameters}|)|}%
- \pgfmanualbody
- This causes the method \meta{method name} to be called for the object
- referenced by the \meta{object handle}. The method is the one defined in
- the class of the object or, if it is not defined there, the method defined
- in the superclasses of the object's class (if there are several
- superclasses that define the same method, the method resolution order is
- used to determine which one gets called). If the optional \meta{super
- class} is specified, the method implementation of that class will be used
- rather than the implementation in the object's class. The \meta{parameters}
- are matched against the parameters of the method and, then, the method body
- is executed. The execution of the method body is \emph{not} done inside a
- scope, so the effects of a method body persist.
- %
-\begin{codeexample}[code only]
-\pgfooclass{stamp}{
- % This is the class stamp
-
- \method stamp() { % The constructor
- }
-
- \method apply(#1,#2) { % Causes the stamp to be shown at coordinate (#1,#2)
- % Draw the stamp:
- \node [rotate=20,font=\huge] at (#1,#2) {Passed};
- }
-}
-
-\pgfoonew \mystamp=new stamp()
-
-\begin{tikzpicture}
- \mystamp.apply(1,2)
- \mystamp.apply(3,4)
-\end{tikzpicture}
-\end{codeexample}
-
- Inside a method, you can call other methods. If you have a handle for
- another object, you can simply call it in the manner described above. In
- order to call a method of the current object, you can use the special
- object handle |\pgfoothis|.
-
- \begin{command}{\pgfoothis}
- This object handle is well-defined only when a method is being executed.
- There, it is then set to point to the object for which the method is
- being called, which allows you to call another method for the same
- object.
- %
-\begin{codeexample}[code only]
-\pgfooclass{stamp}{
- % This is the class stamp
-
- \method stamp() {}
-
- \method apply(#1,#2) {
- \pgfoothis.shift origin(#1,#2)
-
- % Draw the stamp:
- \node [rotate=20,font=\huge] {Passed};
- }
-
- % Private method:
- \method shift origin(#1,#2) {
- \tikzset{xshift=#1,yshift=#2}
- }
-}
-\end{codeexample}
- \end{command}
-\end{pgfmanualentry}
-
-\begin{command}{\pgfoosuper|(|\meta{class},\meta{object handle}|).|\meta{method name}|(|\meta{arguments}|)|}
- This macro gives you finer control over which method gets invoked in case
- of multiple inheritance. This macro calls \meta{method name} of the object
- specified by \meta{object handle}, but which implementation of the method
- is called is determined as follows: it will be the implementation in the
- first class (in the method resolution order) after \meta{class} that
- defines \meta{method name}.
-\end{command}
-
-
-\subsection{Attributes}
-
-Every object has a set of attributes, which may change over time. Attributes
-are declared using the |\attribute| command, which, like the |\method| command,
-is defined only inside the scope of |\pgfooclass|. Attributes can be modified
-(only) by methods. To take the |stamp| example, an attribute of a |stamp|
-object might be the text that should be stamped when the |apply| method is
-called.
-
-When an attribute is changed, this change is \emph{not} local to the current
-\TeX\ group. Changes will persist till the end of the object's life or until
-the attribute is changed once more.
-
-To declare an attribute you should use the |\attribute| command:
-%
-\begin{command}{\attribute \meta{attribute name}\opt{|=|\meta{initial value}}|;|}
- This command can only be given inside the body of an |\pgfooclass| command.
- It declares the attribute named \meta{attribute name}. This name, like
- method or class names, can be quite arbitrary, but should not contain
- periods. Valid names are |an_attribute?| or |my attribute|.
-
- You can optionally specify an \meta{initial value} for the attribute; if
- none is given, the empty string is used automatically. The initial value is
- the value that the attribute will have just after the object has been
- created and before the constructor is called.
- %
-\begin{codeexample}[code only]
-\pgfooclass{stamp}{
- % This is the class stamp
-
- \attribute text;
- \attribute rotation angle = 20;
-
- \method stamp(#1) {
- \pgfooset{text}{#1} % Set the text
- }
-
- \method apply(#1,#2) {
- \pgfoothis.shift origin(#1,#2)
-
- % Draw the stamp:
- \node [rotate=\pgfoovalueof{rotation angle},font=\huge]
- {\pgfoovalueof{text}};
- }
-
- \method shift origin(#1,#2) { ... }
-
- \method set rotation (#1) {
- \pgfooset{rotation angle}{#1}
- }
-}
-\end{codeexample}
- %
-\end{command}
-
-Attributes can be set and read only inside methods, it is not possible to do so
-using an object handle. Spoken in terms of traditional object-oriented
-programming, attributes are always private. You need to define getter and
-setter methods if you wish to read or modify attributes.
-
-Reading and writing attributes is not done using the ``dot-notation'' that is
-used for method calls. This is mostly due to efficiency reasons. Instead, a set
-of special macros is used, all of which can \emph{only be used inside methods}.
-
-\begin{command}{\pgfooset\marg{attribute}\marg{value}}
- Sets the \meta{attribute} of the current object to \meta{value}.
- %
-\begin{codeexample}[code only]
-\method set rotation (#1) {
- \pgfooset{rotation angle}{#1}
-}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfooeset\marg{attribute}\marg{value}}
- Performs the same action as |\pgfooset| but in an |\edef| full expansion
- context.
-\end{command}
-
-\begin{command}{\pgfooappend\marg{attribute}\marg{value}}
- This method adds the given \meta{value} to the \meta{attribute} at the end.
-\end{command}
-
-\begin{command}{\pgfooprefix\marg{attribute}\marg{value}}
- This method adds the given \meta{value} to the \meta{attribute} at the
- beginning.
-\end{command}
-
-\begin{command}{\pgfoolet\marg{attribute}\marg{macro}}
- Sets the \meta{attribute} of the current value to the current value of
- \meta{macro} using \TeX's |\let| command.
- %
-\begin{codeexample}[code only]
-\method foo () {
- \pgfoolet{my func}\myfunc
- % Changing \myfunc now has no effect on the value of attribute my func
-}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfoovalueof\marg{attribute}}
- Expands (eventually) to the current value of \meta{attribute} of the
- current object.
- %
-\begin{codeexample}[code only]
-\method apply(#1,#2) {
- \pgfoothis.shift origin(#1,#2)
-
- \node [rotate=\pgfoovalueof{rotation angle},font=\huge]
- {\pgfoovalueof{text}};
-}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfooget\marg{attribute}\marg{macro}}
- Reads the current value of \meta{attribute} and stores the result in
- \meta{macro}.
- %
-\begin{codeexample}[code only]
-...
- \method get rotation (#1) {
- \pgfooget{rotation angle}{#1}
- }
-...
-
-\mystamp.get rotation(\therotation)
-``\therotation'' is now ``20'' (or whatever).
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Identities}
-\label{section-identities}
-
-Every object has a unique identity, which is simply an integer. It is possible
-to retrieve the object id using the |get id| method (discussed below), but
-normally you will not need to do so because the id itself cannot be used to
-access an object. Rather, you access objects via their methods and these, in
-turn, can only be called via object handles.
-
-Object handles can be created in four ways:
-%
-\begin{enumerate}
- \item Calling |\pgfoonew|\meta{object handle}|=...| will cause \meta{object
- handle} to be a handle to the newly created object.
- \item Using |\let| to create an alias of an existing object handle: If
- |\mystamp| is a handle, saying |\let\myotherstamp=\mystamp| creates a
- second handle to the same object.
- \item |\pgfooobj|\marg{id} can be used as an object handle to the object
- with the given \meta{id}.
- \item Using the |get handle| method to create a handle to a given object.
-\end{enumerate}
-
-Let us have a look at the last two methods.
-
-\begin{command}{\pgfooobj\marg{id}}
- Provided that \meta{id} is the id of an existing object (an object whose
- life-time has not expired), calling this command yields a handle to this
- object. The handle can then be used to call methods:
- %
-\begin{codeexample}[code only]
-% Create a new object:
-\pgfoonew \mystamp=new stamp()
-
-% Get the object's id and store it in \myid:
-\mystamp.get id(\myid)
-
-% The following two calls have the same effect:
-\mystamp.apply(1,1)
-\pgfooobj{\myid}.apply(1,1)
-\end{codeexample}
- %
-\end{command}
-
-The |get id| method can be used to retrieve the id of an object. This method is
-predefined for every class and you should not try to define a method of this
-name yourself.
-
-\begin{predefinedmethod}{get id(\meta{macro})}
- Calling \meta{obj}|.get id(|\meta{macro}|)| stores the id \meta{obj} in
- \meta{macro}. This is mainly useful when you wish to store an object for a
- longer time and you cannot guarantee that any handle that you happen to
- have for this object will be available later on.
-
- The only way to use the retrieved id later on is to call |\pgfooobj|.
-
- Different object that are alive (that are still within the scope in which
- they were created) will always have different ids, so you can use the id to
- test for equality of objects. However, after an object has been destroyed
- because its scope has ended, the same id may be used again for newly
- created objects.
-
- Here is a typical application where you need to call this method: You wish
- to collect a list of objects for which you wish to call a specific method
- from time to time. For the collection process you wish to offer a macro
- called |\addtoobjectlist|, which takes an object handle as parameter. It is
- quite easy to store this handle somewhere, but a handle is, well, just a
- handle. Typically, shortly after the call to |\addtoobjectlist| the handle
- will no longer be valid or even exist, even though the object still exists.
- In this case, you wish to store the object id somewhere instead of the
- handle. Thus, for the object passed to |\addtoobjectlist| you call the
- |get id| method and store the resulting id, rather than the handle.
-\end{predefinedmethod}
-
-There is a second predefined method, called |get handle|, which is also used to
-create object handles.
-
-\begin{predefinedmethod}{get handle(\marg{macro name})}
- Calling this method for an object will cause \meta{macro name} to become a
- handle to the given object. For any object handle |\obj| -- other than
- |\pgfoothis| -- the following two have the same effect:
- %
- \begin{enumerate}
- \item |\let|\meta{macro name}|=\obj|
- \item |\obj.get handle(|\meta{macro name}|)|
- \end{enumerate}
-
- The first method is simpler and faster. However, for |\pgfoothis| there is
- a difference: The call |\pgfoothis.get handle(|\meta{macro name}|)| will
- cause \meta{macro name} to be an object handle to the current object and
- will persist to be so even after the method is done. By comparison,
- |\let|\meta{macro name}|=\pgfoothis| causes |\obj| to be the same as the
- very special macro |\pgfoothis|, so |\obj| will always refer to the current
- object, which may change over time.
-\end{predefinedmethod}
-
-
-\subsection{The Object Class}
-\label{section-object}
-
-The object-oriented module predefines a basic class |object| that can be used
-as a base class in different context.
-
-\begin{ooclass}{object}
- This class current only implements one method:
-
- \begin{method}{copy(\meta{handle})}
- Creates a new object and initializes the values of its (declared)
- attributes to the values of the original. The method takes one
- argument: a control sequence which receives the handle of the copy.
- \end{method}
-\end{ooclass}
-
-
-\subsection{The Signal Class}
-\label{section-signals}
-
-In addition to the basic mechanism for defining and using classes and object,
-the class |signal| is predefined. It implements a so-called signal--slot
-mechanism.
-
-\begin{ooclass}{signal}
- This class is used to implement a simple signal--slot mechanism. The idea
- is the following: From time to time special things happen about which a
- number of objects need to be informed. Different things can happen and
- different object will be interested in these things. A |signal| object can
- be used to signal that such special things of a certain kind have happened.
- For example, one signal object might be used to signal the event that ``a
- page has been shipped out''. Another signal might be used to signal that
- ``a figure is about to be typeset'', and so on.
-
- Objects can ``tune in'' to signals. They do so by \emph{connecting} one of
- their methods (then called a \emph{slot}) to the signal. Then, whenever the
- signal is \emph{emitted}, the method of the connected object(s) get called.
- Different objects can connect different slots to the same signal as long as
- the argument lists will fit. For example, the object that is used to signal
- the ``end of page has been reached'' might emit signals that have, say, the
- box number in which the finished page can be found as a parameter
- (actually, the finished page is always in box 255). Then one object could
- connect a method |handle page(#1)| to this signal, another might connect
- the method |emergency action(#1)| to this signal, and so on.
-
- Currently, it is not possible to ``unregister'' or ``detach'' a slot from a
- signal, that is, once an object has been connect to a signal, it will
- continue to receive emissions of this signal till the end of the life-time
- of the signal. This is even true when the object no longer exists (but the
- signal does), so care must be taken that signal objects are always created
- after the objects that are listening to them.
-
- \begin{method}{signal()}
- The constructor does nothing.
- \end{method}
-
- \begin{method}{connect(\meta{object handle},\meta{method name})}
- This method gets an \meta{object handle} as parameter and a
- \meta{method name} of this object. It will queue the object-method pair
- in an internal list and each time the signal emits something, this
- object's method is called.
-
- Be careful not to pass |\pgfoothis| as \meta{object handle}. This would
- cause the signal object to connect to itself. Rather, if you wish to
- connect a signal to a method of the current object you first need to
- create an alias using the |get handle| method:
- %
-\begin{codeexample}[code only]
-\pgfooclass{some class}{
- \method some class() {
- \pgfoothis.get handle(\me)
- \somesignal.connect(\me,foo)
- \anothersignal.connect(\me,bar)
- }
- \method foo () {}
- \method bar (#1,#2) {}
-}
-\pgfoonew \objA=new some class()
-\pgfoonew \objB=new some class()
-\end{codeexample}
- \end{method}
-
- \begin{method}{emit(\meta{arguments})}
- This method emits a signal to all connected slots. This means that for
- all objects that have previously been connected via a call of
- |connect|, the method (slot) that was specified during the call of
- |connect| is invoked with given \meta{arguments}.
- %
-\begin{codeexample}[code only]
-\anothersignal.emit(1,2)
-% will call \objA.bar(1,2) and \objB.bar(1,2)
-\end{codeexample}
- \end{method}
-\end{ooclass}
-
-
-\subsection{Implementation Notes}
-
-For the curious, here are some notes on how the oo-system is implemented:
-%
-\begin{itemize}
- \item There is an object id counter that gets incremented each time an
- object is created. However, this counter is local to the current scope,
- which means that it is reset at the end of each scope, corresponding to
- the fact that at the end of a scope all objects created in this scope
- become invalid. Newly created objects will then have the same id as
- ``deleted'' objects.
- \item Attributes are stored globally. For each attribute of each object
- there is a macro whose name is composed of the object's id and the
- attribute name. Changes to object attributes are always global.
- \item A call to the garbage collector causes a loop to be executed that
- tries to find objects whose object number is larger than the current
- maximum alive objects. The global attributes of these objects are then
- freed (set to |\relax|) by calling a special internal method of these
- (dead) objects.
-
- The garbage collector is automatically called after each group in
- which an object was created using |\aftergroup|.
- \item When a method is called, before the method call some code is executed
- that sets a global counter storing the current object id to the object
- id of the object being called. After the method call some code is
- inserted that restores the global counter to its original value. This
- is done without scopes, so some tricky |\expandafter| magic is needed.
- Note that, because of this process, you cannot use commands like
- |\pgfutil@ifnextchar| at the end of a method.
- \item An object handle contains just the code to set up and restore the
- current object number to the number of the object being called.
-\end{itemize}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pages.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pages.tex
deleted file mode 100644
index 5da034e477..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-pages.tex
+++ /dev/null
@@ -1,636 +0,0 @@
-% 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{Page Management}
-
-This section describes the |pgfpages| package. Although this package is not
-concerned with creating pictures, its implementation relies so heavily on
-\pgfname\ that it is documented here. Currently, |pgfpages| only works with
-\LaTeX, but if you are adventurous, feel free to hack the code so that it also
-works with plain \TeX.
-
-The aim of |pgfpages| is to provide a flexible way of putting multiple pages on
-a single page \emph{inside \TeX}. Thus, |pgfpages| is quite different from
-useful tools like |psnup| or |pdfnup| insofar as it creates its output in a
-single pass. Furthermore, it works uniformly with both |latex| and |pdflatex|,
-making it easy to put multiple pages on a single page without any fuss.
-
-A word of warning: \emph{using |pgfpages| will destroy hyperlinks}. Actually,
-the hyperlinks are not destroyed, only they will appear at totally wrong
-positions on the final output. This is due to a fundamental flaw in the \pdf\
-specification: In \pdf\ the bounding rectangle of a hyperlink is given in
-``absolute page coordinates'' and translations or rotations do not affect them.
-Thus, the transformations applied by |pgfpages| to put the pages where you want
-them are (cannot, even) be applied to the coordinates of hyperlinks. It is
-unlikely that this will change in the foreseeable future.
-
-
-\subsection{Basic Usage}
-
-The internals of |pgfpages| are complex since the package can do all sorts of
-interesting tricks. For this reason, so-called \emph{layouts} are predefined
-that set up all option in appropriate ways.
-
-You use a layout as follows:
-%
-\begin{codeexample}[code only]
-\documentclass{article}
-
-\usepackage{pgfpages}
-\pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm]
-
-\begin{document}
-This text is shown on the left.
-\clearpage
-This text is shown on the right.
-\end{document}
-\end{codeexample}
-
-The layout |2 on 1| puts two pages on a single page. The option |a4paper| tells
-|pgfpages| that the \emph{resulting} page (called the \emph{physical} page in
-the following) should be |a4paper| and it should be landscape (which is quite
-logical since putting two portrait pages next to each other gives a landscape
-page). Normally, the \emph{logical} pages, that is, the pages that \TeX\
-``thinks'' that it is typesetting, will have the same sizes, but this need not
-be the case. |pgfpages| will automatically scale down the logical pages such
-that two logical pages fit next to each other inside a DIN A4 page.
-
-The |border shrink| tells |pgfpages| that it should add an additional 5mm to
-the shrinking such that a 5mm-wide border is shown around the resulting logical
-pages.
-
-As a second example, let us put two pages produced by the \textsc{beamer} class
-on a single page:
-%
-\begin{codeexample}[code only]
-\documentclass{beamer}
-
-\usepackage{pgfpages}
-\pgfpagesuselayout{2 on 1}[a4paper,border shrink=5mm]
-
-\begin{document}
-\begin{frame}
- This text is shown at the top.
-\end{frame}
-\begin{frame}
- This text is shown at the bottom.
-\end{frame}
-\end{document}
-\end{codeexample}
-
-Note that we do not use the |landscape| option since \textsc{beamer}'s logical
-pages are already in landscape mode and putting two landscape pages on top of
-each other results in a portrait page. However, if you had used the |4 on 1|
-layout, you would have had to add |landscape| once more, using the |6 on 1| or
-|8 on 1| you must not, using |16 on 1| you need it yet again. And, no, there is
-no |32 on 1| layout.
-
-Another word of caution: \emph{using |pgfpages| will produce wrong page numbers
-in the |.aux| file}. The reason is that \TeX\ instantiates the page numbers
-when writing an |.aux| file only when the physical page is shipped out.
-Fortunately, this problem is easy to fix: First, typeset our file normally
-without using the |\pgfpagesuselayout| command (just put the comment marker |%|
-before it) Then, rerun \TeX\ with the |\pgfpagesuselayout| command included and
-add the command |\nofiles|. This command ensures that the |.aux| file is not
-modified, which is exactly what you want. So, to typeset the above example, you
-should actually first \TeX\ the following file:
-%
-\begin{codeexample}[code only]
-\documentclass{article}
-
-\usepackage{pgfpages}
-%%\pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm]
-%%\nofiles
-
-\begin{document}
-This text is shown on the left.
-\clearpage
-This text is shown on the right.
-\end{document}
-\end{codeexample}
-%
-and then typeset
-%
-\begin{codeexample}[code only]
-\documentclass{article}
-
-\usepackage{pgfpages}
-\pgfpagesuselayout{2 on 1}[a4paper,landscape,border shrink=5mm]
-\nofiles
-
-\begin{document}
-This text is shown on the left.
-\clearpage
-This text is shown on the right.
-\end{document}
-\end{codeexample}
-
-The final basic example is the |resize to| layout (it works a bit like a
-hypothetical |1 on 1| layout). This layout resizes the logical page such that
-is fits the specified physical size. Since this does not change the page
-numbering, you need not worry about the |.aux| files with this layout. For
-example, adding the following lines will ensure that the physical output will
-fit on DIN A4 paper:
-%
-\begin{codeexample}[code only]
-\usepackage{pgfpages}
-\pgfpagesuselayout{resize to}[a4paper]
-\end{codeexample}
-
-This can be very useful when you have to handle lots of papers that are typeset
-for, say, letter paper and you have an A4 printer or the other way round. For
-example, the following article will be fit for printing on letter paper:
-%
-\begin{codeexample}[code only]
-\documentclass[a4paper]{article}
-%% a4 is currently the logical size and also the physical size
-
-\usepackage{pgfpages}
-\pgfpagesuselayout{resize to}[letterpaper]
-%% a4 is still the logical size, but letter is the physical one
-
-\begin{document}
- \title{My Great Article}
-...
-\end{document}
-\end{codeexample}
-
-
-\subsection{The Predefined Layouts}
-
-This section explains the predefined layouts in more detail. You select a
-layout using the following command:
-%
-\begin{command}{\pgfpagesuselayout\marg{layout}\oarg{options}}
- Installs the specified \meta{layout} with the given \meta{options}. The
- predefined layouts and their permissible options are explained below.
-
- If this function is called multiple times, only the last call ``wins''. You
- can thereby overwrite any previous settings. In particular, layouts
- \emph{do not} accumulate.
-
- \example |\pgfpagesuselayout{resize to}[a4paper]|
-\end{command}
-
-\begin{pgflayout}{resize to}
- This layout is used to resize every logical page to a specified physical
- size. To determine the target size, the following options may be given:
- %
- \begin{itemize}
- \item \declare{|physical paper height=|\meta{size}} sets the height of
- the physical page size to \meta{size}.
- \item \declare{|physical paper width=|\meta{size}} sets the width of
- the physical Pappe size to \meta{size}.
- \item \declare{|a0paper|} sets the physical page size to DIN A0 paper.
- \item \declare{|a1paper|} sets the physical page size to DIN A1 paper.
- \item \declare{|a2paper|} sets the physical page size to DIN A2 paper.
- \item \declare{|a3paper|} sets the physical page size to DIN A3 paper.
- \item \declare{|a4paper|} sets the physical page size to DIN A4 paper.
- \item \declare{|a5paper|} sets the physical page size to DIN A5 paper.
- \item \declare{|a6paper|} sets the physical page size to DIN A6 paper.
- \item \declare{|letterpaper|} sets the physical page size to the
- American letter paper size.
- \item \declare{|legalpaper|} sets the physical page size to the
- American legal paper size.
- \item \declare{|executivepaper|} sets the physical page size to the
- American executive paper size.
- \item \declare{|landscape|} swaps the height and the width of the
- physical paper.
- \item \declare{|border shrink=|\meta{size}} additionally reduces the
- size of the logical page on the physical page by \meta{size}.
- \end{itemize}
-\end{pgflayout}
-
-\begin{pgflayout}{2 on 1}
- Puts two logical pages alongside each other on each physical page if the
- logical height is larger than the logical width (logical pages are in
- portrait mode). Otherwise, two logical pages are put on top of each other
- (logical pages are in landscape mode). When using this layout, it is
- advisable to use the |\nofiles| command, but this is not done
- automatically.
-
- The same \meta{options} as for the |resize to| layout can be used, plus the
- following option:
- %
- \begin{itemize}
- \item \declare{|odd numbered pages right|} places the first page on the
- right.
- \end{itemize}
-\end{pgflayout}
-
-\begin{pgflayout}{4 on 1}
- Puts four logical pages on a single physical page. The same \meta{options}
- as for the |resize to| layout can be used.
-\end{pgflayout}
-
-\begin{pgflayout}{6 on 1}
- Puts six logical pages on a single physical page.
-\end{pgflayout}
-
-\begin{pgflayout}{8 on 1}
- Puts eight logical pages on a single physical page. As for |2 on 1| and
- |4 on 1|, the orientation depends on whether the logical pages are in
- landscape mode or in portrait mode.
-\end{pgflayout}
-
-\begin{pgflayout}{16 on 1}
- This is for the \textsc{ceo}.
-\end{pgflayout}
-
-\begin{pgflayout}{rounded corners}
-\label{layout-rounded-corners}
- This layout adds ``rounded corners'' to every page, which, supposedly,
- looks nicer during presentations with projectors (personally, I doubt
- this). This is done by (possibly) resizing the page to the physical page
- size. Then four black rectangles are drawn in each corner. Next, a clipping
- region is set up that contains all of the logical page except for little
- rounded corners. Finally, the logical page is drawn and clipped against the
- clipping region.
-
- Note that every logical page should fill its background for this to work.
-
- In addition to the \meta{options} that can be given to |resize to|, the
- following options may be given.
- %
- \begin{itemize}
- \item \declare{|corner width=|\meta{size}} specifies the size of the
- corner.
- \end{itemize}
- %
-\begin{codeexample}[code only]
-\documentclass{beamer}
-\usepackage{pgfpages}
-\pgfpagesuselayout{rounded corners}[corner width=5pt]
-\begin{document}
-...
-\end{document}
-\end{codeexample}
- %
-\end{pgflayout}
-
-\begin{pgflayout}{two screens with lagging second}
- This layout puts two logical pages alongside each other. The second page
- always shows what the main page showed on the previous physical page. Thus,
- the second page ``lags behind'' the main page. This can be useful when you
- have two projectors attached to your computer and can show different parts
- of a physical page on different projectors.
-
- The following \meta{options} may be given:
- %
- \begin{itemize}
- \item \declare{|second right|} puts the second page right of the main
- page. This will make the physical pages twice as wide as the
- logical pages, but it will retain the height.
- \item \declare{|second left|} puts the second page left, otherwise it
- behaves the same as |second right|.
- \item \declare{|second bottom|} puts the second page below the main
- page. This make the physical pages twice as high as the logical
- ones.
- \item \declare{|second top|} works like |second bottom|.
- \end{itemize}
-\end{pgflayout}
-
-\begin{pgflayout}{two screens with optional second}
- This layout works similarly to |two screens with lagging second|. The
- difference is that the contents of the second screen only changes when one
- of the commands |\pgfshipoutlogicalpage{2}|\marg{box} or
- |\pgfcurrentpagewillbelogicalpage{2}| is called. The first puts the given
- \meta{box} on the second page. The second specifies that the current page
- should be put there, once it is finished.
-
- The same options as for |two screens with lagging second| may be given.
-\end{pgflayout}
-
-You can define your own predefined layouts using the following command:
-
-\begin{command}{\pgfpagesdeclarelayout\marg{layout}\marg{before actions}\marg{after actions}}
- This command predefines a \meta{layout} that can later be installed using
- the |\pgfpagesuselayout| command.
-
- When |\pgfpagesuselayout|\marg{layout}\oarg{options} is called, the
- following happens: First, the \meta{before actions} are executed. They can
- be used, for example, to set up default values for keys. Next,
- |\setkeys{pgfpagesuselayoutoption}|\marg{options} is executed. Finally, the
- \meta{after actions} are executed.
-
- Here is an example:
- %
-\begin{codeexample}[code only]
-\pgfpagesdeclarelayout{resize to}
-{
- \def\pgfpageoptionborder{0pt}
-}
-{
- \pgfpagesphysicalpageoptions
- {%
- logical pages=1,%
- physical height=\pgfpageoptionheight,%
- physical width=\pgfpageoptionwidth%
- }
- \pgfpageslogicalpageoptions{1}
- {%
- resized width=\pgfphysicalwidth,%
- resized height=\pgfphysicalheight,%
- border shrink=\pgfpageoptionborder,%
- center=\pgfpoint{.5\pgfphysicalwidth}{.5\pgfphysicalheight}%
- }%
-}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Defining a Layout}
-
-If none of the predefined layouts meets your problem or if you wish to modify
-them, you can create layouts from scratch. This section explains how this is
-done.
-
-Basically, |pgfpages| hooks into \TeX's |\shipout| function. This function is
-called whenever \TeX\ has completed typesetting a page and wishes to send this
-page to the |.dvi| or |.pdf| file. The |pgfpages| package redefines this
-command. Instead of sending the page to the output file, |pgfpages| stores it
-in an internal box and then acts as if the page had been output. When \TeX\
-tries to output the next page using |\shipout|, this call is once more
-intercepted and the page is stored in another box. These boxes are called
-\emph{logical pages}.
-
-At some point, enough logical pages have been accumulated such that a
-\emph{physical page} can be output. When this happens, |pgfpages| possibly
-scales, rotates, and translates the logical pages (and possibly even does
-further modifications) and then puts them at certain positions of the
-\emph{physical} page. Once this page is fully assembled, the ``real'' or
-``original'' |\shipout| is called to send the physical page to the output file.
-
-In reality, things are slightly more complicated. First, once a physical page
-has been shipped out, the logical pages are usually voided, but this need not
-be the case. Instead, it is possible that certain logical pages just retain
-their contents after the physical page has been shipped out and these pages
-need not be filled once more before a physical shipout can occur. However, the
-contents of these logical pages can still be changed using special commands. It
-is also possible that after a shipout certain logical pages are filled with the
-contents of \emph{other} logical pages.
-
-A \emph{layout} defines for each logical page where it will go on the physical
-page and which further modifications should be done. The following two commands
-are used to define the layout:
-
-\begin{command}{\pgfpagesphysicalpageoptions\marg{options}}
- This command sets the characteristics of the ``physical'' page. For
- example, it is used to specify how many logical pages there are and how
- many logical pages must be accumulated before a physical page is shipped
- out. How each individual logical page is typeset is specified using the
- command |\pgfpageslogicalpageoptions|, described later.
-
- \example A layout for putting two portrait pages on a single landscape
- page:
- %
-\begin{codeexample}[code only]
-\pgfpagesphysicalpageoptions
-{%
- logical pages=2,%
- physical height=\paperwidth,%
- physical width=\paperheight,%
-}
-
-\pgfpageslogicalpageoptions{1}
-{%
- resized width=.5\pgfphysicalwidth,%
- resized height=\pgfphysicalheight,%
- center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}%
-}%
-\pgfpageslogicalpageoptions{2}
-{%
- resized width=.5\pgfphysicalwidth,%
- resized height=\pgfphysicalheight,%
- center=\pgfpoint{.75\pgfphysicalwidth}{.5\pgfphysicalheight}%
-}%
-\end{codeexample}
-
- The following \meta{options} may be set:
- \begin{itemize}
- \item \declare{|logical pages=|\meta{logical pages}} specified how many
- logical pages there are, in total. These are numbered 1 to
- \meta{logical pages}.
- \item \declare{|first logical shipout=|\meta{first}}. See the next
- option. By default, \meta{first} is 1.
- \item \declare{|last logical shipout=|\meta{last}}. Together with the
- previous option, these two options define an interval of pages
- inside the range 1 to \meta{logical pages}. Only this range is used
- to store the pages that are shipped out by \TeX. This means that
- after a physical shipout has just occurred (or at the beginning),
- the first time \TeX\ wishes to perform a shipout, the page to be
- shipped out is stored in logical page \meta{first}. The next time
- \TeX\ performs a shipout, the page is stored in logical page
- $\meta{first} +1$ and so on, until the logical page \meta{last} is
- also filled. Once this happens, a physical shipout occurs and the
- process starts once more.
-
- Note that logical pages that lie outside the interval between
- \meta{first} and \meta{last} are filled only indirectly or when
- special commands are used.
-
- By default, \meta{last} equals \meta{logical pages}.
- \item \declare{|current logical shipout=|\meta{current}} changes an
- internal counter such that \TeX's next logical shipout will be
- stored in logical page \meta{current}.
-
- This option can be used to ``warp'' the logical page filling
- mechanism to a certain page. You can both skip logical pages and
- overwrite already filled logical pages. After the logical page
- \meta{current} has been filled, the internal counter is incremented
- normally as if the logical page \meta{current} had been ``reached''
- normally. If you specify a \meta{current} larger than \meta{last},
- a physical shipout will occur after the logical page \meta{current}
- has been filled.
- \item \declare{|physical height=|\meta{height}} specifies the height of
- the physical pages. This height is typically different from the
- normal |\paperheight|, which is used by \TeX\ for its typesetting
- and page breaking purposes.
- \item \declare{|physical width=|\meta{width}} specifies the physical
- width.
- \end{itemize}
-\end{command}
-
-
-\begin{command}{\pgfpageslogicalpageoptions\marg{logical page number}\marg{options}}
- This command is used to specify where the logical page number \meta{logical
- page number} will be placed on the physical page. In addition, this command
- can be used to install additional ``code'' to be executed when this page is
- put on the physical page.
-
- The number \meta{logical page number} should be between 1 and \meta{logical
- pages}, which has previously been installed using the
- |\pgfpagesphysicalpageoptions| command.
-
- The following \meta{options} may be given:
- %
- \begin{itemize}
- \item \declare{|center=|\meta{pgf point}} specifies the center of the
- logical page inside the physical page as a \pgfname-point. The
- origin of the coordinate system of the physical page is at the
- \emph{lower} left corner.
- %
-\begin{codeexample}[code only]
-\pgfpageslogicalpageoptions{1}
-{% center logical page on middle of left side
- center=\pgfpoint{.25\pgfphysicalwidth}{.5\pgfphysicalheight}%
- resized width=.5\pgfphysicalwidth,%
- resized height=\pgfphysicalheight,%
-}
-\end{codeexample}
- %
- \item \declare{|resized width=|\meta{size}} specifies the width that
- the logical page should have \emph{at most} on the physical page.
- To achieve this width, the pages is scaled down appropriately
- \emph{or more}. The ``or more'' part can happen if the
- |resize height| option is also used. In this case, the scaling is
- chosen such that both the specified height and width are met. The
- aspect ratio of a logical page is not modified.
- \item \declare{|resized height=|\meta{height}} specifies the maximum
- height of the logical page.
- \item \declare{|original width=|\meta{width}} specifies the width the
- \TeX\ ``thinks'' that the logical page has. This width is
- |\paperwidth| at the point of invocation, by default. Note that
- setting this width to something different from |\paperwidth| does
- \emph{not} change the |\pagewidth| during \TeX's typesetting. You
- have to do that yourself.
-
- You need this option only for special logical pages that have a
- height or width different from the normal one and for which you
- will (later on) set these sizes yourself.
- \item \declare{|original height=|\meta{height}} works like
- |original width|.
- \item \declare{|scale=|\meta{factor}} scales the page by at least the
- given \meta{factor}. A \meta{factor} of |0.5| will half the size of
- the page, a factor or |2| will double the size. ``At least'' means
- that if options like |resize height| are given and if the scaling
- required to meet that option is less than \meta{factor}, that other
- scaling is used instead.
- \item \declare{|xscale=|\meta{factor}} scales the logical page along
- the $x$-axis by the given \meta{factor}. This scaling is done
- independently of any other scaling. Mostly, this option is useful
- for a factor of |-1|, which flips the page along the $y$-axis. The
- aspect ratio is not kept.
- \item \declare{|yscale=|\meta{factor}} works like |xscale|, only for
- the $y$-axis.
- \item \declare{|rotation=|\meta{degree}} rotates the page by
- \meta{degree} around its center. Use a degree of |90| or |-90| to
- go from portrait to landscape and back. The rotation need not be a
- multiple of |90|.
- \item \declare{|copy from=|\meta{logical page number}}. Normally, after
- a physical shipout has occurred, all logical pages are voided in a
- loop. However, if this option is given, the current logical page is
- filled with the contents of the old logical page number
- \meta{logical page number}.
-
- \example Have logical page 2 retain its contents:
- %
-\begin{codeexample}[code only]
-\pgfpageslogicalpageoptions{2}{copy from=2}
-\end{codeexample}
-
- \example Let logical page 2 show what logical page 1 showed on the
- just-shipped-out physical page:
- %
-\begin{codeexample}[code only]
-\pgfpageslogicalpageoptions{2}{copy from=1}
-\end{codeexample}
- %
- \item \declare{|border shrink|=\meta{size}} specifies an additional
- reduction of the size to which the page is page is scaled.
- \item \declare{|border code|=\meta{code}}. When this option is given,
- the \meta{code} is executed before the page box is inserted with a
- path preinstalled that is a rectangle around the current logical
- page. Thus, setting \meta{code} to |\pgfstroke| draws a rectangle
- around the logical page. Setting \meta{code} to
- |\pgfsetlinewidth{3pt}\pgfstroke| results in a thick (ugly) frame.
- Adding dashes and filling can result in arbitrarily funky and
- distracting borders.
-
- You can also call |\pgfdiscardpath| and add your own path
- construction code (for example to paint a rectangle with rounded
- corners). The coordinate system is set up in such a way that a
- rectangle starting at the origin and having the height and width of
- \TeX-box 0 will result in a rectangle filling exactly the logical
- page currently being put on the physical page. The logical page is
- inserted \emph{after} these commands have been executed.
-
- \example Add a rectangle around the page:
- %
-\begin{codeexample}[code only]
-\pgfpageslogicalpageoptions{1}{border code=\pgfstroke}
-\end{codeexample}
- %
- \item \declare{|corner width|=\meta{size}} adds black ``rounded
- corners'' to the page. See the description of the predefined layout
- |rounded corners| on page~\pageref{layout-rounded-corners}.
- \end{itemize}
-\end{command}
-
-
-\subsection{Creating Logical Pages}
-
-Logical pages are created whenever \TeX\ thinks that a page is full and
-performs a |\shipout| command. This will cause |pgfpages| to store the box that
-was supposed to be shipped out internally until enough logical pages have been
-collected such that a physical shipout can occur.
-
-Normally, whenever a logical shipout occurs, that current page is stored in
-logical page number \meta{current logical page}. This counter is then
-incremented, until it is larger than \meta{last logical shipout}. You can,
-however, directly change the value of \meta{current logical page} by calling
-|\pgfpagesphysicalpageoptions|.
-
-Another way to set the contents of a logical page is to use the following
-command:
-
-\begin{command}{\pgfpagesshipoutlogicalpage\marg{number}\meta{box}}
- This command sets to logical page \meta{number} to \meta{box}. The
- \meta{box} should be the code of a \TeX\ box command. This command does not
- influence the counter \meta{current logical page} and does not cause a
- physical shipout.
- %
-\begin{codeexample}[code only]
-\pgfpagesshipoutlogicalpage{0}\vbox{Hi!}
-\end{codeexample}
-
- This command can be used to set the contents of logical pages that are
- normally not filled.
-\end{command}
-
-The final way of setting a logical page is using the following command:
-
-\begin{command}{\pgfpagescurrentpagewillbelogicalpage\marg{number}}
- When the current \TeX\ page has been typeset, it will be become the given
- logical page \meta{number}. This command ``interrupts'' the normal order of
- logical pages, that is, it behaves like the previous command and does not
- update the \meta{current logical page} counter.
- %
-\begin{codeexample}[code only]
-\pgfpagesuselayout{two screens with optional second}
-...
-Text for main page.
-\clearpage
-
-\pgfpagescurrentpagewillbelogicalpage{2}
-Text that goes to second page
-\clearpage
-
-Text for main page.
-\end{codeexample}
- %
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfcalendar.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfcalendar.tex
deleted file mode 100644
index 50fc9ca140..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfcalendar.tex
+++ /dev/null
@@ -1,492 +0,0 @@
-% 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{Date and Calendar Utility Macros}
-\label{section-calendar}
-
-This section describes the package |pgfcalendar|.
-
-\begin{package}{pgfcalendar}
- This package can be used independently of \pgfname. It has two purposes:
- %
- \begin{enumerate}
- \item It provides functions for working with dates. Most noticeably, it
- can convert a date in ISO-standard format (like 1975-12-26) to a
- so-called Julian day number, which is defined in Wikipedia as
- follows: ``The Julian day or Julian day number is the (integer)
- number of days that have elapsed since the initial epoch at noon
- Universal Time (UT) Monday, January 1, 4713 BC in the proleptic
- Julian calendar''. The package also provides a function for
- converting a Julian day number to an ISO-format date.
-
- Julian day numbers make it very easy to work with days. For
- example, the date ten days in the future of 2008-02-20 can be
- computed by converting this date to a Julian day number, adding 10,
- and then converting it back. Also, the day of week of a given date
- can be computed by taking the Julian day number modulo~7.
- \item It provides a macro for typesetting a calendar. This macro is
- highly configurable and flexible (for example, it can produce both
- plain text calendars and also complicated \tikzname-based
- calendars), but most users will not use the macro directly. It is
- the job of a frontend to provide useful configurations for
- typesetting calendars based on this command.
- \end{enumerate}
-\end{package}
-
-
-\subsection{Handling Dates}
-
-\subsubsection{Conversions Between Date Types}
-
-\begin{command}{\pgfcalendardatetojulian\marg{date}\marg{counter}}
- This macro converts a date in a format to be described in a moment to the
- Julian day number in the Gregorian calendar. The \meta{date} should expand
- to a string of the following form:
- %
- \begin{enumerate}
- \label{calendar-date-format}
- \item It should start with a number representing the year. Use |\year|
- for the current year, that is, the year the file is being typeset.
- \item The year must be followed by a hyphen.
- \item Next should come a number representing the month. Use |\month|
- for the current month. You can, but need not, use leading zeros.
- For example, |02| represents February, just like |2|.
- \item The month must also be followed by a hyphen.
- \item Next you must either provide a day of month (again, a number and,
- again, |\day| yields the current day of month) or the keyword
- |last|. This keyword refers to the last day of the month, which is
- automatically computed (and which is a bit tricky to compute,
- especially for February).
- \item Optionally, you can next provide a plus sign followed by positive
- or negative number. This number of days will be added to the
- computed date.
- \end{enumerate}
-
- Here are some examples:
- %
- \begin{itemize}
- \item |2006-01-01| refers to the first day of 2006.
- \item |2006-02-last| refers to February 28, 2006.
- \item |\year-\month-\day| refers to today.
- \item |2006-01-01+2| refers to January 3, 2006.
- \item |\year-\month-\day+1| refers to tomorrow.
- \item |\year-\month-\day+-1| refers to yesterday.
- \end{itemize}
-
- The conversion method is taken from the English Wikipedia entry on Julian
- days.
-
- \newcount\mycount
- \example |\pgfcalendardatetojulian{2007-01-14}{\mycount}| sets
- |\mycount| to
- \pgfcalendardatetojulian{2007-01-14}{\mycount}\the\mycount.
-\end{command}
-
-\begin{command}{\pgfcalendarjuliantodate\marg{Julian day}\marg{year macro}\marg{month macro}\marg{day macro}}
- This command converts a Julian day number to an ISO-date. The \meta{Julian
- day} must be a number or \TeX\ counter, the \meta{year macro}, \meta{month
- macro} and \meta{day macro} must be \TeX\ macro names. They will be set to
- numbers representing the year, month, and day of the given Julian day in
- the Gregorian calendar.
-
- The \meta{year macro} will be assigned the year without leading zeros. Note
- that this macro will produce year 0 (as opposed to other calendars, where
- year 0 does not exist). However, if you really need calendars for before
- the year 1, it is expected that you know what you are doing anyway.
-
- The \meta{month macro} gets assigned a two-digit number representing the
- month (with a leading zero, if necessary). Thus, the macro is set to |01|
- for January.
-
- The \meta{day macro} gets assigned a two-digit number representing the day
- of the month (again, possibly with a leading zero).
-
- To convert a Julian day number to an ISO-date you use code like the
- following:
- %
-\begin{verbatim}
-\pgfcalendarjuliantodate{2454115}{\myyear}{\mymonth}{\myday}
-\edef\isodate{\myyear-\mymonth-\myday}
-\end{verbatim}
- %
- The above code sets |\isodate| to
- \pgfcalendarjuliantodate{2454115}{\myyear}{\mymonth}{\myday}%
- \edef\isodate{\myyear-\mymonth-\myday}\texttt{\isodate}.
-\end{command}
-
-\begin{command}{\pgfcalendarjuliantoweekday\marg{Julian day}\marg{week day counter}}
- This command converts a Julian day to a week day by computing the day
- modulo 7. The \meta{week day counter} must be a \TeX\ counter. It will be
- set to 0 for a Monday, to 1 for a Tuesday, and so on.
-
- \example |\pgfcalendarjuliantoweekday{2454115}{\mycount}| sets
- |\mycount| to
- \pgfcalendarjuliantoweekday{2454115}{\mycount}\the\mycount\ (it was a Sunday).
-\end{command}
-
-\begin{command}{\pgfcalendareastersunday\marg{year}\marg{counter}}
- This command computes the date of Easter Sunday as a Julian date and stores
- it in \meta{counter}.
-
- \example |\pgfcalendareastersunday{2019}{\mycount}| sets
- |\mycount| to
- \pgfcalendareastersunday{2019}{\mycount}\the\mycount, which corresponds to
- \pgfcalendarjuliantodate{\mycount}{\myyear}{\mymonth}{\myday}%
- \edef\isodate{\myyear-\mymonth-\myday}\texttt{\isodate}.
-\end{command}
-
-\subsubsection{Checking Dates}
-
-\begin{command}{\pgfcalendarifdate\marg{date}\marg{tests}\marg{code}\marg{else code}}
-\label{pgfcalendarifdate}
- This command is used to execute code based on properties of \meta{date}.
- The \meta{date} must be a date in ISO-format. For this date, the
- \meta{tests} are checked (to be detailed later) and if one of the tests
- succeeds, the \meta{code} is executed. If none of the tests succeeds, the
- \meta{else code} is executed.
-
- \example |\pgfcalendarifdate{2007-02-07}{Wednesday}{Is a Wednesday}{Is not a Wednesday}|
- yields \texttt{\pgfcalendarifdate{2007-02-07}{Wednesday}{Is a Wednesday}{Is
- not a Wednesday}}.
-
- The \meta{tests} is a comma-separated list of key--value pairs. The
- following are defined by default:
- %
- \begin{itemize}
- \itemcalendaroption{all} This test is passed by all dates.
- \itemcalendaroption{Monday} This test is passed by all dates that are
- Mondays.
- \itemcalendaroption{Tuesday} as above.
- \itemcalendaroption{Wednesday} as above.
- \itemcalendaroption{Thursday} as above.
- \itemcalendaroption{Friday} as above.
- \itemcalendaroption{Saturday} as above.
- \itemcalendaroption{Sunday} as above.
- \itemcalendaroption{workday} Passed by Mondays, Tuesdays, Wednesdays,
- Thursdays, and Fridays. \itemcalendaroption{weekend} Passed by
- Saturdays and Sundays.
- \itemcalendaroption{equals}|=|\meta{reference} The \meta{reference}
- can be in one of two forms: Either, it is a full ISO format date
- like |2007-01-01| or the year may be missing as in |12-31|. In the
- first case, the test is passed if \meta{date} is the same as
- \meta{reference}. In the second case, the test is passed if the
- month and day part of \meta{date} is the same as \meta{reference}.
-
- For example, the test |equals=2007-01-10| will only be passed by
- this particular date. The test |equals=05-01| will be passed by
- every first of May on any year.
- \itemcalendaroption{at least}|=|\meta{reference} This test works
- similarly to the |equals| test, only it is checked whether
- \meta{date} is equal to \meta{reference} or to any later date.
- Again, the \meta{reference} can be a full date like |2007-01-01| or
- a short version like |07-01|. For example, |at least=07-01| is true
- for every day in the second half of any year.
- \itemcalendaroption{at most}|=|\meta{reference} as above.
- \itemcalendaroption{between}|=|\meta{start reference}| and |\meta{end
- reference} This test checks whether the current date lies between
- the two given reference dates. Both full and short version may be
- given.
-
- For example |between=2007-01-01 and 2007-02-28| is true for the
- days in January and February of 2007.
-
- For another example, |between=05-01 and 05-07| is true for the days
- of the first week of May of any year.
- \itemcalendaroption{day of month}|=|\meta{number} Passed by the day of
- month of the \meta{date} that is \meta{number}. For example, the
- test |day of month=1| is passed by every first of every month.
- \itemcalendaroption{end of month}\opt{|=|\meta{number}} Passed by the
- day of month of the \meta{date} that is \meta{number} from the end
- of the month. For example, the test |end of month=1| is passed by
- the last day of every month, the test |end of month=2| is passed by
- the second last day of every month. If \meta{number} is omitted, it
- is assumed to be |1|.
- \itemcalendaroption{Easter}\opt{|=|\meta{number}} This test checks
- whether the given date is Easter Sunday. The optional number can
- be used for offsets from Easter Sunday, e.g.\ |Easter=-3| for
- Maundy Thursday, |Easter=-2| for Good Friday, |Easter=1| for Easter
- Monday. Since the dates of other Christian holidays are determined
- by the date of Easter, these can be accessed as well, e.g.\
- |Easter=39| for Feast of the Ascension, |Easter=49| for Pentecost,
- and |Easter=50| for Whit Monday.
- \end{itemize}
-
- In addition to the above checks, you can also define new checks. To do so,
- you must add a new key to the path |/pgf/calendar/| using the |\pgfkeys|
- command. The job of the code of this new key is to possibly set the \TeX-if
- |\ifpgfcalendarmatches| to true (if it is already true, no action should be
- taken) to indicate that the \meta{date} passes the test setup by this new
- key.
-
- In order to perform the test, the key code needs to know the date that
- should be checked. The date is available through a macro, but a whole bunch
- of additional information about this date is also available through the
- following macros:
- %
- \begin{itemize}
- \item |\pgfcalendarifdatejulian| is the Julian day number of the
- \meta{date} to be checked.
- \item |\pgfcalendarifdateweekday| is the weekday of the \meta{date} to
- be checked.
- \item |\pgfcalendarifdateyear| is the year of the \meta{date} to be
- checked.
- \item |\pgfcalendarifdatemonth| is the month of the \meta{date} to be
- checked.
- \item |\pgfcalendarifdateday| is the day of month of the \meta{date} to
- be checked.
- \end{itemize}
-
- For example, let us define a new key that checks whether the \meta{date} is
- a Workers day (May 1st). This can be done as follows:
- %
-\begin{verbatim}
-\pgfkeys{/pgf/calendar/workers day/.code=%
-{
- \ifnum\pgfcalendarifdatemonth=5\relax
- \ifnum\pgfcalendarifdateday=1\relax
- \pgfcalendarmatchestrue
- \fi
- \fi
-}}
-\end{verbatim}
- %
-\end{command}
-
-
-\subsubsection{Typesetting Dates}
-
-\begin{command}{\pgfcalendarweekdayname\marg{week day number}}
- This command expands to a textual representation of the day of week, given
- by the \meta{week day number}. Thus, |\pgfcalendarweekdayname{0}| expands
- to |Monday| if the current language is English and to |Montag| if the
- current language is German, and so on. See
- Section~\ref{section-calendar-locale} for more details on translations.
-
- \example |\pgfcalendarweekdayname{2}| yields
- \texttt{\pgfcalendarweekdayname{2}}.
-\end{command}
-
-\begin{command}{\pgfcalendarweekdayshortname\marg{week day number}}
- This command works similarly to the previous command, only an abbreviated
- version of the week day is produced.
-
- \example |\pgfcalendarweekdayshortname{2}| yields
- \texttt{\pgfcalendarweekdayshortname{2}}.
-\end{command}
-
-\begin{command}{\pgfcalendarmonthname\marg{month number}}
- This command expands to a textual representation of the month, which is
- given by the \meta{month number}.
-
- \example |\pgfcalendarmonthname{12}| yields
- \texttt{\pgfcalendarmonthname{12}}.
-\end{command}
-
-\begin{command}{\pgfcalendarmonthshortname\marg{month number}}
- As above, only an abbreviated version is produced.
-
- \example |\pgfcalendarmonthshortname{12}| yields
- \texttt{\pgfcalendarmonthshortname{12}}.
-\end{command}
-
-
-\subsubsection{Localization}
-\label{section-calendar-locale}
-
-All textual representations of week days or months (like ``Monday'' or
-``February'') are wrapped with |\translate| commands from the |translator|
-package (it this package is not loaded, no translation takes place).
-Furthermore, the |pgfcalendar| package will try to load the
-|translator-months-dictionary|, if the |translator| package is loaded.
-
-If you want to use the |translator| package, it has to be loaded before the
-|pgfcalendar| package or, when you are using the |calendar| \tikzname\ library,
-before |tikz|. Otherwise it will not be properly detected.
-
-The net effect of all this is that all dates will be translated to the current
-language setup in the |translator| package. See the documentation of this
-package for more details.
-
-
-\subsection{Typesetting Calendars}
-
-\begin{command}{\pgfcalendar\marg{prefix}\marg{start date}\marg{end date}\marg{rendering code}}
- This command can be used to typeset a calendar. It is a very general
- command, the actual work has to be done by giving clever implementations of
- \meta{rendering code}. Note that this macro need \emph{not} be called
- inside a |{pgfpicture}| environment (even though it typically will be) and
- you can use it to typeset calendars in normal \TeX\ or using packages other
- than \pgfname.
-
-
- \medskip
- \textbf{Basic typesetting process.}
- A calendar is typeset as follows: The \meta{start date} and \meta{end date}
- specify a range of dates. For each date in this range the \meta{rendering
- code} is executed with certain macros setup to yield information about the
- \emph{current date} (the current date in the enumeration of dates of the
- range). Typically, the \meta{rendering code} places nodes inside a picture,
- but it can do other things as well. Note that it is also the job of the
- \meta{rendering code} to position the calendar correctly.
-
- The different calls of the \meta{rending code} are not surrounded by \TeX\
- groups (though you can do so yourself, of course). This means that settings
- can accumulate between different calls, which is often desirable and
- useful.
-
-
- \medskip
- \textbf{Information about the current date.}
- Inside the \meta{rendering code}, different macros can be access:
- %
- \begin{itemize}
- \item |\pgfcalendarprefix| The \meta{prefix} parameter. This prefix is
- recommended for nodes inside the calendar, but you have to use it
- yourself explicitly.
- \item |\pgfcalendarbeginiso| The \meta{start date} of range being
- typeset in ISO format (like 2006-01-10).
- \item |\pgfcalendarbeginjulian| Julian day number of \meta{start date}.
- \item |\pgfcalendarendiso| The \meta{end date} of range being typeset
- in ISO format.
- \item |\pgfcalendarendjulian| Julian day number of \meta{end date}.
- \item |\pgfcalendarcurrentjulian| This \TeX\ count holds the Julian day
- number of the day currently being rendered.
- \item |\pgfcalendarcurrentweekday| The weekday (a number with zero
- representing Monday) of the current date.
- \item |\pgfcalendarcurrentyear| The year of the current date.
- \item |\pgfcalendarcurrentmonth| The month of the current date (always
- two digits with a leading zero, if necessary).
- \item |\pgfcalendarcurrentday| The day of month of the current date
- (always two digits).
- \end{itemize}
-
-
- \medskip
- {\bfseries The |\ifdate| command.}
- Inside the |\pgfcalendar| the macro |\ifdate| is available locally:
- %
- \begin{command}{\ifdate\marg{tests}\marg{code}\marg{else code}}
- \label{ifdate}%
- This command has the same effect as calling |\pgfcalendarifdate|
- for the current date.
- \end{command}
-
-
- \medskip
- \textbf{Examples.}
- In a first example, let us create a very simple calendar: It just lists the
- dates in a certain range.
- %
-\begin{codeexample}[vbox,ignorespaces,preamble={\usepackage{pgfcalendar}}]
-\pgfcalendar{cal}{2007-01-20}{2007-02-10}{\pgfcalendarcurrentday\ }
-\end{codeexample}
- %
- Let us now make this a little more interesting: Let us add a line break
- after each Sunday.
- %
-\begin{codeexample}[vbox,ignorespaces,preamble={\usepackage{pgfcalendar}}]
-\pgfcalendar{cal}{2007-01-20}{2007-02-10}
-{
- \pgfcalendarcurrentday\
- \ifdate{Sunday}{\par}{}
-}
-\end{codeexample}
- %
- We now want to have all Mondays to be aligned on a column. For this,
- different approaches work. Here is one based positioning each day
- horizontally using a skip.
- %
-\begin{codeexample}[vbox,ignorespaces,preamble={\usepackage{pgfcalendar}}]
-\pgfcalendar{cal}{2007-01-20}{2007-02-10}
-{%
- \leavevmode%
- \hbox to0pt{\hskip\pgfcalendarcurrentweekday cm\pgfcalendarcurrentday\hss}%
- \ifdate{Sunday}{\par}{}%
-}
-\end{codeexample}
- %
- Let us now typeset two complete months.
- %
-\begin{codeexample}[vbox,ignorespaces,preamble={\usepackage{pgfcalendar}}]
-\pgfcalendar{cal}{2007-01-01}{2007-02-28}{%
- \ifdate{day of month=1}{
- \par\bigskip\hbox to7.5cm{\itshape\hss\pgfcalendarshorthand mt\hss}\par
- }{}%
- \leavevmode%
- {%
- \ifdate{weekend}{\color{black!50}}{\color{black}}%
- \hbox to0pt{%
- \hskip\pgfcalendarcurrentweekday cm%
- \hbox to1cm{\hss\pgfcalendarshorthand d-}\hss%
- }%
- }%
- \ifdate{Sunday}{\par}{}%
-}
-\end{codeexample}
- %
- For our final example, we use a |{tikzpicture}|.
- %
-\begin{codeexample}[vbox,ignorespaces,preamble={\usepackage{pgfcalendar}}]
-\begin{tikzpicture}
- \pgfcalendar{cal}{2007-01-20}{2007-02-10}{%
- \ifdate{workday}
- {\tikzset{filling/.style={fill=blue!20}}}
- {\tikzset{filling/.style={fill=red!20}}}
- \node (\pgfcalendarsuggestedname) at (\pgfcalendarcurrentweekday,0)
- [anchor=base,circle,filling] {\pgfcalendarcurrentday};
- \ifdate{Sunday}{\pgftransformyshift{-3em}}{}%
- }
- \draw (cal-2007-01-21) -- (cal-2007-02-03);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfcalendarshorthand\marg{kind}\marg{representation}}
-\label{pgfcalendarshorthand}
- This command can be used inside a |\pgfcalendar|, where it will expand to a
- representation of the current day, month, year or day of week, depending on
- whether \meta{kind} is |d|, |m|, |y| or |w|. The \meta{representation} can
- be one of the following: |-|, |=|, |0|, |.|, and |t|. They have the
- following meanings:
- %
- \begin{itemize}
- \item The minus sign selects the shortest numerical representation
- possible (no leading zeros).
- \item The equal sign also selects the shortest numerical
- representation, but a space is added to single digit days and
- months (thereby ensuring that they have the same length as other
- days).
- \item The zero digit selects a two-digit numerical representation for
- days and months. For years it is allowed, but has no effect.
- \item The letter |t| selects a textual representation.
- \item The dot selects an abbreviated textual representation.
- \end{itemize}
- %
- Normally, you should say |\let\%=\pgfcalendarshorthand| locally, so that
- you can write |\%wt| instead of the much more cumbersome
- |\pgfcalendarshorthand{w}{t}|.
- %
-\begin{codeexample}[leave comments,preamble={\usepackage{pgfcalendar}}]
-\let\%=\pgfcalendarshorthand
-\pgfcalendar{cal}{2007-01-20}{2007-01-20}
-{ ISO form: \%y0-\%m0-\%d0, long form: \%wt, \%mt \%d-, \%y0}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfcalendarsuggestedname}
- This macro expands to a suggested name for nodes representing days in a
- calendar. If the \meta{prefix} is empty, it expands to the empty string,
- otherwise it expands to the \meta{prefix} of the calendar, followed by a
- hyphen, followed by the ISO format version of the date. Thus, when the date
- |2007-01-01| is typeset in a calendar for the prefix |mycal|, the macro
- expands to |mycal-2007-01-01|.
-\end{command}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgffor.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgffor.tex
deleted file mode 100644
index 94a41fbfe2..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgffor.tex
+++ /dev/null
@@ -1,418 +0,0 @@
-% 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{Repeating Things: The Foreach Statement}
-\label{section-foreach}
-
-This section describes the package |pgffor|, which is loaded automatically by
-\tikzname, but not by \pgfname:
-
-\begin{package}{pgffor}
- This package can be used independently of \pgfname, but works particularly
- well together with \pgfname\ and \tikzname. It defines two new commands:
- |\foreach| and |\breakforeach|.
-\end{package}
-
-\begin{command}{\foreach| |\meta{variables}| |\opt{{\ttfamily[}\meta{options}{\ttfamily]}}| in |\meta{list} \meta{commands}}
- The syntax of this command is a bit complicated, so let us go through it
- step-by-step.
-
- In the easiest case, \meta{variables} is a single \TeX-command like |\x| or
- |\point|. (If you want to have some fun, you can also use active
- characters. If you do not know what active characters are, you are
- blessed.)
-
- Still in the easiest case, \meta{options} will be omitted. The keys for
- customizing this command will be discussed below.
-
- Again, in the easiest case, \meta{list} is either a comma-separated list of
- values surrounded by curly braces or it is the name of a macro that contain
- such a list of values. Anything can be used as a value, but numbers are
- most likely.
-
- Finally, in the easiest case, \meta{commands} is some \TeX-text in curly
- braces.
-
- With all these assumptions, the |\foreach| statement will execute the
- \meta{commands} repeatedly, once for every element of the \meta{list}. Each
- time the \meta{commands} are executed, the \meta{variable} will be set to
- the current value of the list item.
- %
-\begin{codeexample}[]
-\foreach \x in {1,2,3,0} {[\x]}
-\end{codeexample}
-
-\begin{codeexample}[]
-\def\mylist{1,2,3,0}
-\foreach \x in \mylist {[\x]}
-\end{codeexample}
-
- Note that in each execution of \meta{commands} the \meta{commands} are put
- in a \TeX\ group. This means that \emph{local changes to counters inside
- \meta{commands} do not persist till the next iteration}. For instance, if
- you add 1 to a counter inside \meta{commands} locally, then in the next
- iteration the counter will have the same value it had at the beginning of
- the first iteration. You have to add |\global| if you wish changes to
- persist from iteration to iteration.
-
-
- \medskip
- \textbf{Syntax for the commands.}
- Let us move on to a more complicated setting. The first complication occurs
- when the \meta{commands} are not some text in curly braces. If the
- |\foreach| statement does not encounter an opening brace, it will instead
- scan everything up to the next semicolon and use this as \meta{commands}.
- This is most useful in situations like the following:
- %
-\begin{codeexample}[]
-\tikz
- \foreach \x in {0,1,2,3}
- \draw (\x,0) circle (0.2cm);
-\end{codeexample}
-
- However, the ``reading till the next semicolon'' is not the whole truth.
- There is another rule: If a |\foreach| statement is directly followed by
- another |\foreach| statement, this second foreach statement is collected as
- \meta{commands}. This allows you to write the following:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \foreach \x in {0,1,2,3}
- \foreach \y in {0,1,2,3}
- {
- \draw (\x,\y) circle (0.2cm);
- \fill (\x,\y) circle (0.1cm);
- }
-\end{tikzpicture}
-\end{codeexample}
-
- \medskip
- \textbf{The dots notation.}
- The second complication concerns the \meta{list}. If this \meta{list}
- contains the list item ``|...|'', this list item is replaced by the
- ``missing values''. More precisely, the following happens:
-
- Normally, when a list item |...| is encountered, there should already have
- been \emph{two} list items before it, which where numbers. Examples of
- \emph{numbers} are |1|, |-10|, or |-0.24|. Let us call these numbers $x$
- and $y$ and let $d := y-x$ be their difference. Next, there should also be
- one number following the three dots, let us call this number~$z$.
-
- In this situation, the part of the list reading ``$x$|,|$y$|,...,|$z$'' is
- replaced by ``$x$, $x+d$, $x+2d$, $x+3d$, \dots, $x+md$'', where the last
- dots are semantic dots, not syntactic dots. The value $m$ is the largest
- number such that $x + md \le z$ if $d$ is positive or such that $x+md \ge
- z$ if $d$ is negative.
-
- Perhaps it is best to explain this by some examples: The following
- \meta{list} have the same effects:
-
- |\foreach \x in {1,2,...,6} {\x, }| yields \foreach \x in {1,2,...,6} {\x, }
-
- |\foreach \x in {1,2,3,...,6} {\x, }| yields \foreach \x in {1,2,3,...,6} {\x, }
-
- |\foreach \x in {1,3,...,11} {\x, }| yields \foreach \x in {1,3,...,11} {\x, }
-
- |\foreach \x in {1,3,...,10} {\x, }| yields \foreach \x in {1,3,...,10} {\x, }
-
- |\foreach \x in {0,0.1,...,0.5} {\x, }| yields \foreach \x in {0,0.1,...,0.5} {\x, }
-
- |\foreach \x in {a,b,9,8,...,1,2,2.125,...,2.5} {\x, }| yields \foreach \x in {a,b,9,8,...,1,2,2.125,...,2.5} {\x, }
-
- As can be seen, for fractional steps that are not multiples of $2^{-n}$ for
- some small $n$, rounding errors can occur pretty easily. Thus, in the
- second last case, |0.5| should probably be replaced by |0.501| for
- robustness.
-
- There is another special case for the |...| statement: If the |...| is used
- right after the first item in the list, that is, if there is an $x$, but no
- $y$, the difference $d$ obviously cannot be computed and is set to $1$ if
- the number $z$ following the dots is larger than $x$ and is set to $-1$ if
- $z$ is smaller:
-
- |\foreach \x in {1,...,6} {\x, }| yields \foreach \x in {1,...,6} {\x, }
-
- |\foreach \x in {9,...,3.5} {\x, }| yields \foreach \x in {9,...,3.5} {\x, }
-
- There is a yet another special case for the |...| statement, in that it can
- indicate an alphabetic character sequence:
-
- |\foreach \x in {a,...,m} {\x, }| yields \foreach \x in {a,...,m} {\x, }
-
- |\foreach \x in {Z,X,...,M} {\x, }| yields \foreach \x in {Z,X,...,M} {\x, }
-
- A final special case for the |...| statement is contextual replacement. If
- the |...| is used in some context, for example, |sin(...)|, this context
- will be interpreted correctly, provided that the list items prior to the
- |...| statement have \emph{exactly} the same pattern, except that, instead
- of dots, they have a number or a character:
-
- |\foreach \x in {2^1,2^...,2^7} {$\x$, }| yields \foreach \x in {2^1,2^...,2^7} {$\x$, }
-
- |\foreach \x in {0\pi,0.5\pi,...\pi,3\pi} {$\x$, }| yields \foreach \x in {0\pi,0.5\pi,...\pi,3\pi} {$\x$, }
-
- |\foreach \x in {A_1,..._1,H_1} {$\x$, }| yields \foreach \x in {A_1,..._1,H_1} {$\x$, }
-
-
- \textbf{Special handling of pairs.}
- Different list items are separated by commas. However, this causes a
- problem when the list items contain commas themselves as pairs like |(0,1)|
- do. In this case, you should put the items containing commas in braces as
- in |{(0,1)}|. However, since pairs are such a natural and useful case, they
- get a special treatment by the |\foreach| statement. When a list item
- starts with a |(| everything up to the next |)| is made part of the item.
- Thus, we can write things like the following:
- %
-\begin{codeexample}[]
-\tikz
- \foreach \position in {(0,0), (1,1), (2,0), (3,1)}
- \draw \position rectangle +(.25,.5);
-\end{codeexample}
-
-
- \medskip
- \textbf{Using the foreach-statement inside paths.}
- \tikzname\ allows you to use |foreach| and |\foreach| (both have the same
- effect) inside a path construction. In such a case, the \meta{commands}
- must be path construction commands. Here are two examples:
- %
-\begin{codeexample}[]
-\tikz
- \draw (0,0)
- foreach \x in {1,...,3}
- { -- (\x,1) -- (\x,0) }
- ;
-\end{codeexample}
-
-\begin{codeexample}[]
-\tikz \draw foreach \p in {1,...,3} {(\p,1)--(\p,3) (1,\p)--(3,\p)};
-\end{codeexample}
-
- Note that the |node| and |pic| path commands also support the |foreach|
- statement in special ways.
-
-
- \medskip
- \textbf{Multiple variables.}
- You will often wish to iterate over two variables at the same time. Since
- you can nest |\foreach| loops, this is normally straight-forward. However,
- you sometimes wish variables to iterate ``simultaneously''. For example, we
- might be given a list of edges that connect two coordinates and might wish
- to iterate over these edges. While doing so, we would like the source and
- target of the edges to be set to two different variables.
-
- To achieve this, you can use the following syntax: The \meta{variables} may
- not only be a single \TeX-variable. Instead, it can also be a list of
- variables separated by slashes (|/|). In this case the list items can also
- be lists of values separated by slashes.
-
- Assuming that the \meta{variables} and the list items are lists of values,
- each time the \meta{commands} are executed, each of the variables in
- \meta{variables} is set to one part of the list making up the current list
- item. Here is an example to clarify this:
-
- \example |\foreach \x / \y in {1/2,a/b} {``\x\ and \y''}| yields
- \foreach \x / \y in {1/2,a/b} {``\x\ and \y''}.
-
- If some entry in the \meta{list} does not have ``enough'' slashes, the last
- entry will be repeated. Here is an example:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \foreach \x/\xtext in {0,...,3,2.72 / e}
- \draw (\x,0) node{$\xtext$};
-\end{tikzpicture}
-\end{codeexample}
-
- Here are more useful examples:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- % Define some coordinates:
- \path[nodes={circle,fill=yellow!80!black,draw}]
- (0,0) node(a) {a}
- (2,0.55) node(b) {b}
- (1,1.5) node(c) {c}
- (2,1.75) node(d) {d};
-
- % Draw some connections:
- \foreach \source/\target in {a/b, b/c, c/a, c/d}
- \draw (\source) .. controls +(.75cm,0pt) and +(-.75cm,0pt)..(\target);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- % Let's draw circles at interesting points:
- \foreach \x / \y / \r in {0 / 0 / 2mm, 1 / 1 / 3mm, 2 / 0 / 1mm}
- \draw (\x,\y) circle (\r);
-
- % Same effect
- \foreach \center/\r in {{(0,0)/2mm}, {(1,1)/3mm}, {(2,0)/1mm}}
- \draw[yshift=2.5cm] \center circle (\r);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[line cap=round,line width=3pt]
- \filldraw [fill=yellow!80!black] (0,0) circle (2cm);
-
- \foreach \angle / \label in
- {0/3, 30/2, 60/1, 90/12, 120/11, 150/10, 180/9,
- 210/8, 240/7, 270/6, 300/5, 330/4}
- {
- \draw[line width=1pt] (\angle:1.8cm) -- (\angle:2cm);
- \draw (\angle:1.4cm) node{\textsf{\label}};
- }
-
- \foreach \angle in {0,90,180,270}
- \draw[line width=2pt] (\angle:1.6cm) -- (\angle:2cm);
-
- \draw (0,0) -- (120:0.8cm); % hour
- \draw (0,0) -- (90:1cm); % minute
-\end{tikzpicture}%
-\end{codeexample}
-
-\begin{codeexample}[]
-\tikz[shading=ball]
- \foreach \x / \cola in {0/red,1/green,2/blue,3/yellow}
- \foreach \y / \colb in {0/red,1/green,2/blue,3/yellow}
- \shade[ball color=\cola!50!\colb] (\x,\y) circle (0.4cm);
-\end{codeexample}
-
-
- \medskip
- \textbf{Options to customize the foreach-statement.}
-
- The keys described below can be used in the \meta{options} argument to the
- |\foreach| command. They all have the path |/pgf/foreach/|, however, the
- path is set automatically when \meta{options} are parsed, so it does not
- have to be explicitly stated.
-
- \begin{key}{/pgf/foreach/var=\meta{variable}}
- This key provides an alternative way to specify variables:
- |\foreach [var=\x,var=\y]| is the same as |\foreach \x/\y|. If used,
- this key should be used before the other keys.
- \end{key}
-
- \begin{key}{/pgf/foreach/evaluate=\meta{variable}| |\opt{|as |\meta{macro}| using |\meta{formula}}}
- By default, list items are not evaluated: |1+2|, yields |1+2|, not |3|.
- This key allows a variable to be evaluated using the mathematical
- engine. The variable must have been specified either using the |var|
- key or in the \meta{variables} argument of the |foreach| command. By
- default, the result of the evaluation will be stored in
- \meta{variable}. However, the optional |as |\meta{macro} statement can
- be used to store the result in \meta{macro}.
- %
-\begin{codeexample}[]
-\foreach \x [evaluate=\x] in {2^0,2^...,2^8}{$\x$, }
-\end{codeexample}
-
-\begin{codeexample}[]
-\foreach \x [evaluate=\x as \xeval] in {2^0,2^...,2^8}{$\x=\xeval$, }
-\end{codeexample}
-
- The optional |using |\meta{formula} statement means an evaluation does
- not have to be explicitly stated for each item in \meta{list}. The
- \meta{formula} should contain at least one reference to
- \meta{variable}.
- %
-\begin{codeexample}[]
-\tikz\foreach \x [evaluate=\x as \shade using \x*10] in {0,1,...,10}
- \node [fill=red!\shade!yellow, minimum size=0.65cm] at (\x,0) {\x};
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/foreach/remember=\meta{variable}| as |\meta{macro}| |\opt{|(initially |\meta{value}|)|}}
- This key allows the item value stored in \meta{variable} to be
- remembered during the next iteration, stored in \meta{macro}. If a
- variable is evaluated, the result of this evaluation is remembered. By
- default the value of \meta{variable} is zero for the first iteration,
- however, the optional |(initially |\meta{value}|)| statement, allows
- the \meta{macro} to be initially defined as \meta{value}.
- %
-\begin{codeexample}[]
-\foreach \x [remember=\x as \lastx (initially A)] in {B,...,H}{$\overrightarrow{\lastx\x}$, }
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/foreach/count=\meta{macro}| |\opt{|from |\meta{value}}}
- This key allows \meta{macro} to hold the position in the list of the
- current item. The optional |from |\meta{value} statement allows the
- counting to begin from \meta{value}.
- %
-\begin{codeexample}[]
-\tikz[x=0.75cm,y=0.75cm]
- \foreach \x [count=\xi] in {a,...,e}
- \foreach \y [count=\yi] in {\x,...,e}
- \node [draw, top color=white, bottom color=blue!50, minimum size=0.666cm]
- at (\xi,-\yi) {$\mathstrut\x\y$};
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/foreach/parse=\marg{boolean} (default false)}
- If this key is set to true the upper bound in the loop will be
- fed into |\pgfmathparse|. This allows to use complex expressions as
- the upper bound. However, the expression must be safe for evaluation
- in |\pgfmathparse|. It is known that internal \TeX\ registers can
- cause trouble.
- %
-\begin{codeexample}[]
-\foreach \x [parse=true] in {1,...,1.0e+1 - 1}{ \x }
-\end{codeexample}
- %
- \end{key}
-
- \begin{key}{/pgf/foreach/expand list=\marg{boolean} (default false)}
- If this key is set to true the contents of the list are fully expanded
- with |\edef| before further processing. This allows using complex
- macros which generate a list upon expansion without having to use an
- intermediate macro.
- %
-\begin{codeexample}[]
-\def\Iota#1#2{%
- \ifnum\numexpr#1\relax<\numexpr#2\relax
- \the\numexpr#1\relax,%
- \expandafter\Iota\expandafter{\the\numexpr(#1)+1\relax}{#2}%
- \else
- \the\numexpr#2\relax
- \fi}
-\foreach [expand list=true] \x in {\Iota{1}{5}} {
- \x
-}
-\end{codeexample}
- %
- \end{key}
-\end{command}
-
-\begin{command}{\breakforeach}
- If this command is given inside a |\foreach| command, no further executions
- of the \meta{commands} will occur. However, the current execution of the
- \meta{commands} is continued normally, so it is probably best to use this
- command only at the end of a |\foreach| command.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \foreach \x in {1,...,4}
- \foreach \y in {1,...,4}
- {
- \fill[red!50] (\x,\y) ellipse (3pt and 6pt);
-
- \ifnum \x<\y
- \breakforeach
- \fi
- }
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeys.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeys.tex
deleted file mode 100644
index 95994059da..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeys.tex
+++ /dev/null
@@ -1,1743 +0,0 @@
-% 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{Key Management}
-\label{section-keys}
-
-This section describes the package |pgfkeys|. It is loaded automatically by
-both \pgfname\ and \tikzname.
-
-\begin{package}{pgfkeys}
- This package can be used independently of \pgfname. Note that no
- other package of \pgfname\ needs to be loaded (so neither the
- emulation layer nor the system layer is needed). The Con\TeX t
- abbreviation is |pgfkey| \todosp{pgfkey --> pgfkeys?} if |pgfmod| is not loaded.
-\end{package}
-
-
-\subsection{Introduction}
-
-\subsubsection{Comparison to Other Packages}
-
-The |pgfkeys| package defines a key--value management system that is in some
-sense similar to the more light-weight |keyval| system and the improved
-|xkeyval| system. However, |pgfkeys| uses a slightly different philosophy than
-these systems and it will coexist peacefully with both of them.
-
-The main differences between |pgfkeys| and |xkeyval| are the following:
-%
-\begin{itemize}
- \item |pgfkeys| organizes keys in a tree, while |keyval| and |xkeyval|
- use families. In |pgfkeys| the families correspond to the root
- entries of the key tree.
- \item |pgfkeys| has no save-stack impact (you will have to read the \TeX
- Book very carefully to appreciate this).
- \item |pgfkeys| is slightly slower than |keyval|, but not much.
- \item |pgfkeys| supports styles. This means that keys can just stand for
- other keys (which can stand for other keys in turn or which can also
- just execute some code). \tikzname\ uses this mechanism heavily.
- \item |pgfkeys| supports multi-argument key code. This can, however, be
- emulated in |keyval|.
- \item |pgfkeys| supports handlers. These are call-backs that are called
- when a key is not known. They are very flexible, in fact even
- defining keys in different ways is handled by, well, handlers.
-\end{itemize}
-
-
-\subsubsection{Quick Guide to Using the Key Mechanism}
-
-The following quick guide to \pgfname's key mechanism only treats the most
-commonly used features. For an in-depth discussion of what is going on, please
-consult the remainder of this section.
-
-Keys are organized in a large tree that is reminiscent of the Unix file tree. A
-typical key might be, say, |/tikz/coordinate system/x| or just |/x|. Again as
-in Unix, when you specify keys you can provide the complete path of the key,
-but you usually just provide the name of the key (corresponding to the file
-name without any path) and the path is added automatically.
-
-Typically (but not necessarily) some code is associated with a key. To execute
-this code, you use the |\pgfkeys| command. This command takes a list of
-so-called key--value pairs. Each pair is of the form \meta{key}|=|\meta{value}.
-For each pair the |\pgfkeys| command will execute the code stored for the
-\meta{key} with its parameter set to \meta{value}.
-
-Here is a typical example of how the |\pgfkeys| command is used:
-%
-\begin{codeexample}[code only]
-\pgfkeys{/my key=hallo,/your keys/main key=something\strange,
- key name without path=something else}
-\end{codeexample}
-
-Now, to set the code that is stored in a key you do not need to learn a new
-command. Rather, the |\pgfkeys| command can also be used to set the code of a
-key. This is done using so-called \emph{handlers}. They look like keys whose
-names look like ``hidden files in Unix'' since they start with a dot. The
-handler for setting the code of a key is appropriately called |/.code| and it
-is used as follows:
-%
-\begin{codeexample}[]
-\pgfkeys{/my key/.code=The value is '#1'.}
-\pgfkeys{/my key=hi!}
-\end{codeexample}
-%
-As you can see, in the first line we defined the code for the key |/my key|. In
-the second line we executed this code with the parameter set to |hi!|.
-
-There are numerous handlers for defining a key. For instance, we can also
-define a key whose value actually consists of more than one parameter.
-%
-\begin{codeexample}[]
-\pgfkeys{/my key/.code 2 args=The values are '#1' and '#2'.}
-\pgfkeys{/my key={a1}{a2}}
-\end{codeexample}
-
-We often want to have keys where the code is called with some default value if
-the user does not provide a value. Not surprisingly, this is also done using a
-handler, this time called |/.default|.
-%
-\begin{codeexample}[]
-\pgfkeys{/my key/.code=(#1)}
-\pgfkeys{/my key/.default=hello}
-\pgfkeys{/my key=hallo,/my key}
-\end{codeexample}
-
-The other way round, it is also possible to specify that a value \emph{must} be
-specified, using a handler called |/.value required|. Finally, you can also
-require that no value \emph{may} be specified using |/.value forbidden|.
-
-All keys for a package like, say, \tikzname\ start with the path |/tikz|. We
-obviously do not like to write this path down every time we use a key (so we do
-not have to write things like |\draw[/tikz/line width=1cm]|). What we need is
-to somehow ``change the default path to a specific location''. This is done
-using the handler |/.cd| (for ``change directory''). Once this handler has been
-used on a key, all subsequent keys {\itshape in the current call of |\pgfkeys|
-only} are automatically prefixed with this path, if necessary.
-
-Here is an example:
-%
-\begin{codeexample}[code only]
-\pgfkeys{/tikz/.cd,line width=1cm,line cap=round}
-\end{codeexample}
-%
-This makes it easy to define commands like |\tikzset|, which could be defined
-as follows (the actual definition is a bit faster, but the effect is the same):
-%
-\begin{codeexample}[code only]
-\def\tikzset#1{\pgfkeys{/tikz/.cd,#1}}
-\end{codeexample}
-
-When a key is handled, instead of executing some code, the key can also cause
-further keys to be executed. Such keys will be called \emph{styles}. A style
-is, in essence, just a key list that should be executed whenever the style is
-executed. Here is an example:
-%
-\begin{codeexample}[]
-\pgfkeys{/a/.code=(a:#1)}
-\pgfkeys{/b/.code=(b:#1)}
-\pgfkeys{/my style/.style={/a=foo,/b=bar,/a=#1}}
-\pgfkeys{/my style=wow}
-\end{codeexample}
-%
-As the above example shows, styles can also be parameterized, just like the
-normal code keys.
-
-As a typical use of styles, suppose we wish to set up the key |/tikz| so that
-it will change the default path to |/tikz|. This can be achieved as follows:
-%
-\begin{codeexample}[code only]
-\pgfkeys{/tikz/.style=/tikz/.cd}
-\pgfkeys{tikz,line width=1cm,draw=red}
-\end{codeexample}
-
-Note that when |\pgfkeys| is executed, the default path is set to~|/|. This
-means that the first |tikz| will be completed to |/tikz|. Then |/tikz| is a
-style and, thus, replaced by |/tikz/.cd|, which changes the default path to
-|/tikz|. Thus, the |line width| is correctly prefixed with |/tikz|.
-
-
-\subsection{The Key Tree}
-
-The |pgfkeys| package organizes keys in a so-called \emph{key tree}. This tree
-will be familiar to anyone who has used a Unix operating system: A key is
-addressed by a path, which consists of different parts separated by slashes. A
-typical key might be |/tikz/line width| or just |/tikz| or something more
-complicated like |/tikz/cs/x/.store in|.
-
-Let us fix some further terminology: Given a key like |/a/b/c|, we call the
-part leading up the last slash (|/a/b|) the \emph{path} of the key. We call
-everything after the last slash (|c|) the \emph{name} of the key (in a file
-system this would be the file name).
-
-We do not always wish to specify keys completely. Instead, we usually specify
-only part of a key (typically only the name) and the \emph{default path} is
-then added to the key at the front. So, when the default path is |/tikz| and
-you refer to the (partial) key |line width|, the actual key that is used is
-|/tikz/line width|. There is a simple rule for deciding whether a key is a
-partial key or a full key: If it starts with a slash, then it is a full key and
-it is not modified; if it does not start with a slash, then the default path is
-automatically prefixed.
-
-\emph{Remark:} The above rule is actually a definition, hence the corresponding
-sufficiency conditions hold. That is, if it is a full key, then it starts with
-a slash; if it is a partial key, then it does not start with a slash. Moreover,
-a path always starts with a slash.
-
-Note that the default path is not the same as a search path. In particular, the
-default path is just a single path. When a partial key is given, only this
-single default path is prefixed; |pgfkeys| does not try to look up the key in
-different parts of a search path. It is, however, possible to emulate search
-paths, but a much more complicated mechanism must be used.
-
-When you set keys (to be explained in a moment), you can freely mix partial and
-full keys and you can change the default path. This makes it possible to
-temporarily use keys from another part of the key tree (this turns out to be a
-very useful feature).
-
-Each key (may) store some \emph{tokens} and there exist commands, described
-below, for setting, getting, and changing the tokens stored in a key. However,
-you will only very seldom use these commands directly. Rather, the standard way
-of using keys is the |\pgfkeys| command or some command that uses it internally
-like, say, |\tikzset|. So, you may wish to skip the following commands and
-continue with the next subsection.
-
-\begin{command}{\pgfkeyssetvalue\marg{full key}\marg{token text}}
- Stores the \meta{token text} in the \meta{full key}. The \meta{full key}
- may not be a partial key, so no default-path-adding is done. The
- \meta{token text} can be arbitrary tokens and may even contain things like
- |#| or unbalanced \TeX-ifs.
- %
-\begin{codeexample}[]
-\pgfkeyssetvalue{/my family/my key}{Hello, world!}
-\pgfkeysvalueof{/my family/my key}
-\end{codeexample}
-
- The setting of a key is always local to the current \TeX\ group.
-\end{command}
-
-\begin{command}{\pgfkeyssetevalue\marg{full key}\marg{token text}}
- The |\edef| version of |\pgfkeyssetvalue|.
-\end{command}
-
-\begin{command}{\pgfkeyslet\marg{full key}\marg{macro}}
- Performs a |\let| statement so the \meta{full key} points to the contents
- of \meta{macro}.
- %
-\begin{codeexample}[]
-\def\helloworld{Hello, world!}
-\pgfkeyslet{/my family/my key}{\helloworld}
-\pgfkeysvalueof{/my family/my key}
-\end{codeexample}
- %
- You should never let a key be equal to |\relax|. Such a key may or may not
- be indistinguishable from an undefined key.
-\end{command}
-
-\begin{command}{\pgfkeysgetvalue\marg{full key}\marg{macro}}
- Retrieves the tokens stored in the \meta{full key} and lets \meta{macro} be
- equal to these tokens. If the key has not been set, the \meta{macro} will
- be equal to |\relax|.
- %
-\begin{codeexample}[]
-\pgfkeyssetvalue{/my family/my key}{Hello, world!}
-\pgfkeysgetvalue{/my family/my key}{\helloworld}
-\helloworld
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfkeysvalueof\marg{full key}}
- Inserts the value stored in \meta{full key} at the current position into
- the text.
- %
-\begin{codeexample}[]
-\pgfkeyssetvalue{/my family/my key}{Hello, world!}
-\pgfkeysvalueof{/my family/my key}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfkeysifdefined\marg{full key}\marg{if}\marg{else}}
- Checks whether this key was previously set using either |\pgfkeyssetvalue|
- or |\pgfkeyslet|. If so, the code in \meta{if} is executed, otherwise the
- code in \meta{else}.
-
- This command will use e\TeX's |\ifcsname| command, if available, for
- efficiency. This means, however, that it may behave differently for \TeX\
- and for e\TeX\ when you set keys to |\relax|. For this reason you should
- not do so.
- %
-\begin{codeexample}[]
-\pgfkeyssetvalue{/my family/my key}{Hello, world!}
-\pgfkeysifdefined{/my family/my key}{yes}{no}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Setting Keys}
-
-Settings keys is done using a powerful command called |\pgfkeys|. This command
-takes a list of so-called \emph{key--value pairs}. These are pairs of the form
-\meta{key}|=|\meta{value}. The principal idea is the following: For each pair
-in the list, some \emph{action} is taken. This action can be one of the
-following:
-%
-\begin{enumerate}
- \item A command is executed whose argument(s) are \meta{value}. This
- command is stored in a special subkey of \meta{key}.
- \item The \meta{value} is stored in the \meta{key} itself.
- \item If the key's name (the part after the last slash) is a known
- \emph{handler}, then this handler will take care of the key.
- \item If the key is totally unknown, one of several possible \emph{unknown
- key handlers} is called.
-\end{enumerate}
-
-Additionally, if the \meta{value} is missing, a default value may or may not be
-substituted. Before we plunge into all the details, let us have a quick look at
-the command itself.
-
-\begin{command}{\pgfkeys\marg{key list}}
- The \meta{key list} should be a list of key--value pairs, separated by
- commas. A key--value pair can have the following two forms:
- \meta{key}|=|\meta{value} or just \meta{key}. Any spaces around the
- \meta{key} or around the \meta{value} are removed. It is permissible to
- surround both the \meta{key} or the \meta{value} in curly braces, which are
- also removed. Especially putting the \meta{value} in curly braces needs to
- be done quite often, namely whenever the \meta{value} contains an
- equal-sign or a comma.
-
- The key--value pairs in the list are handled in the order they appear. How
- this handling is done, exactly, is described in the rest of this section.
-
- If a \meta{key} is a partial key, the current value of the default path is
- prefixed to the \meta{key} and this ``upgraded'' key is then used. The
- default path is just the root path |/| when the first key is handled, but
- it may change later on. At the end of the command, the default path is
- reset to the value it had before this command was executed.
-
- Calls of this command may be nested. Thus, it is permissible to call
- |\pgfkeys| inside the code that is executed for a key. Since the default
- path is restored after a call of |\pgfkeys|, the default path will not
- change when you call |\pgfkeys| while executing code for a key (which is
- exactly what you want).
-\end{command}
-
-\begin{command}{\pgfqkeys\marg{default path}\marg{key list}}
- This command has the same effect as |\pgfkeys{|\meta{default
- path}|/.cd,|\meta{key list}|}|, it is only marginally quicker. This command
- should not be used in user code, but rather in commands like |\tikzset| or
- |\pgfset| that get called very often.
-\end{command}
-
-\begin{command}{\pgfkeysalso\marg{key list}}
- This command has exactly the same effect as |\pgfkeys|, only the default
- path is not modified before or after the keys are being set. This command
- is mainly intended to be called by the code that is being processed for a
- key.
-\end{command}
-
-\begin{command}{\pgfqkeysalso\marg{default path}\marg{key list}}
- This command has the same effect as |\pgfkeysalso{|\meta{default
- path}|/.cd,|\meta{key list}|}|, it is only quicker. Changing the default
- path inside a |\pgfkeyalso| is dangerous, so use with care. A rather safe
- place to call this command is at the beginning of a \TeX\ group.
-\end{command}
-
-
-\subsubsection{First Char Syntax Detection}
-\label{sec:pgf:first:char:syntax}
-
-Usually, keys are of the form \meta{key}|=|\meta{value} and how such keys are
-handled is discussed in the rest of this section. However, it is also possible
-to setup a different syntax for certain parts of the input to |\pgfkeys|. Since
-this is a rather advanced option, most readers may wish to skip the following
-discussion upon first reading; it is discussed here because this special syntax
-detection is the very first thing that is done when a key is processed, before
-any of the following operations are performed.
-
-The |\pgfkeys| command and its variants decompose their input into a list of
-\meta{string}s that are separated by commas. By default, each such
-\meta{string} must either have the form \meta{key}|=|\meta{value} or of the
-form \meta{key} with the value-part missing. However, you might wish to
-interpret some of these strings differently. For instance, when a \meta{string}
-has the form |"|\meta{text}|"|, you might wish the \meta{string} to be
-interpreted as if one had written |label text={|\meta{text}|}|. Then, people
-could write
-%
-\begin{codeexample}[code only]
-\myset{red, "main valve", thick}
-\end{codeexample}
-%
-instead of the more cumbersome
-%
-\begin{codeexample}[code only]
-\myset{red, label text=main valve, thick}
-\end{codeexample}
-%
-An example where such a syntax reinterpretation is done is the |quotes|
-library, which allows you to write things like
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz \graph { a ->["1" red] b ->["0"] c };
-\end{codeexample}
-%
-\noindent instead of the somewhat longer
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph { a ->[edge node={node[red,auto]{1}}] b ->[edge label=0] c };
-\end{codeexample}
-
-In order to detect whether a \meta{string} has a special syntax, you can
-request that the \emph{first character} of \meta{string} is analysed by the key
-parser. If this first character matches a character that has been flagged as a
-special character, the \meta{string} is not interpreted as a usual key--value
-pair. Instead, \meta{string} is passed as a parameter to a special macro that
-should take care of the \meta{string}. After this macro has finished, the
-parsing continues with the \meta{next string} in the list.
-
-In order to setup a special syntax handling for \meta{strings} that begin with
-a certain character, two things need to be done:
-%
-\begin{enumerate}
- \item First, the whole |first char syntax| detection must be ``switched on'',
- since, by default, it is turned off for efficiency reasons (the
- overhead is rather small, however). This is done by setting the
- following key:
- %
- \begin{key}{/handlers/first char syntax=\opt{\meta{true or false}} (default true, initially false)}
- \end{key}
- \item Second, in order to handle strings starting with a certain
- \meta{character} in a special way, you need to store a macro in the
- following key:
- %
- \begin{key}{/handlers/first char syntax/\meta{meaning of character}}
- The \meta{meaning of character} should be the text that \TeX's
- command |\meaning| returns for a macro that has been |\let| to the
- \meta{character}. For instance, when strings starting with |"|
- should be treated in a special way, the \meta{meaning of character}
- would be the string |the character "| since this is what \TeX\
- writes when you say
- %
-\begin{codeexample}[]
-\let\mycharacter="
-\meaning\mycharacter
-\end{codeexample}
- %
- Now, the key |/handlers/first char syntax/|\meta{meaning of
- character} should be setup (using |\pgfkeyssetvalue| or using the
- |.initial| handler) to store a \meta{macro name}.
-
- If this is the case and if \meta{string} starts with the
- \meta{character} (blanks at the beginning of \meta{string} are
- deleted prior to this test), then \meta{macro name} is called with
- \meta{string} as its argument.
- \end{key}
-\end{enumerate}
-
-Let us now have a look at an example. We install two handlers, one for strings
-starting with |"| and one for strings starting with |<|.
-%
-\begin{codeexample}[]
-\pgfkeys{
- /handlers/first char syntax=true,
- /handlers/first char syntax/the character "/.initial=\myquotemacro,
- /handlers/first char syntax/the character </.initial=\mypointedmacro,
-}
-
-\def\myquotemacro#1{Quoted: #1. }
-\def\mypointedmacro#1{Pointed: #1. }
-
-\ttfamily \pgfkeys{"foo", <bar>}
-\end{codeexample}
-
-Naturally, in the above examples, the two handling macros did not do something
-particularly exciting. In the next example, we setup a more elaborate macro
-that mimics a small part the behavior of the |quotes| library, only for single
-quotes:
-%
-\begin{codeexample}[]
-\pgfkeys{
- /handlers/first char syntax=true,
- /handlers/first char syntax/the character '/.initial=\mysinglequotemacro
-}
-
-\def\mysinglequotemacro#1{\pgfkeysalso{label={#1}}}
-
-\tikz \node [circle, 'foo', draw] {bar};
-\end{codeexample}
-
-Note that in the above example, the macro |\mysinglequotemacro| gets passed the
-complete string, including the single quotes. It is the job of the macro to get
-rid of them, if this is necessary.
-
-The first char syntax detection allows you to perform rather powerful
-transformations on the syntax of keys -- provided you can ``pin down'' the
-syntax on the first character. In the following example, you can write
-expressions in parentheses in front of a key--value pair and the pair will only
-be executed when the expression evaluates to true:
-%
-\begin{codeexample}[]
-\pgfkeys{
- /handlers/first char syntax=true,
- /handlers/first char syntax/the character (/.initial=\myparamacro
-}
-
-\def\myparamacro#1{\myparaparser#1\someendtext}
-\def\myparaparser(#1)#2\someendtext{
- \pgfmathparse{#1}
- \ifx\pgfmathresult\onetext
- \pgfkeysalso{#2}
- \fi
-}
-\def\onetext{1}
-
-\foreach \i in {1,...,4}
- \tikz \node [draw, thick, rectangle, (pi>\i) circle, (pi>\i*2) draw=red] {x};
-\end{codeexample}
-
-
-\subsubsection{Default Arguments}
-
-The arguments of the |\pgfkeys| command can either be of the form
-\meta{key}|=|\meta{value} or of the form \meta{key} with the value-part
-missing. In the second case, the |\pgfkeys| will try to provide a \emph{default
-value} for the \meta{value}. If such a default value is defined, it will be
-used as if you had written \meta{key}|=|\meta{default value}.
-
-In the following, the details of how default values are determined is
-described; however, you should normally use the handlers |/.default| and
-|/.value required| as described in Section~\ref{section-default-handlers} and
-you may wish to skip the following details.
-
-When |\pgfkeys| encounters a \meta{key} without an equal-sign, the following
-happens:
-%
-\begin{enumerate}
- \item The input is replaced by \meta{key}|=\pgfkeysnovalue|. In particular,
- the commands |\pgfkeys{my key}| and
- % FIXME: there is a bug in the pretty printer ... fix it and get rid of '||' here:
- |\pgfkeys{my key=||\pgfkeysnovalue}| have exactly the same effect and
- you can ``simulate'' a missing value by providing the value
- |\pgfkeysnovalue|, which is sometimes useful.
- \item If the \meta{value} is |\pgfkeysnovalue|, then it is checked whether
- the subkey \meta{key}|/.@def| exists. For instance, if you write
- |\pgfkeys{/my key}|, then it is checked whether the key |/my key/.@def|
- exists.
- \item If the key \meta{key}|/.@def| exists, then the tokens stored in this
- key are used as \meta{value}.
- \item If the key does not exist, then |\pgfkeysnovalue| is used as the
- \meta{value}.
- \item At the end, if the \meta{value} is now equal to
- |\pgfkeysvaluerequired|, then the code (or something fairly equivalent)
- |\pgfkeys{/errors/value required=|\meta{key}|{}}| is executed. Thus, by
- changing this key you can change the error message that is printed or
- you can handle the missing value in some other way.
-\end{enumerate}
-
-
-\subsubsection{Keys That Execute Commands}
-\label{section-key-code}
-
-After the transformation process described in the previous subsection, we
-arrive at a key of the form \meta{key}=\meta{value}, where \meta{key} is a full
-key. Different things can now happen, but always the macro |\pgfkeyscurrentkey|
-will have been set up to expand to the text of the \meta{key} that is currently
-being processed.
-
-The first things that is tested is whether the key \meta{key}|/.@cmd| exists.
-If this is the case, then it is assumed that this key stores the code of a
-macro and this macro is executed. The argument of this macro is \meta{value}
-directly followed by |\pgfeov|, which stands for ``end of value''. The
-\meta{value} is not surrounded by braces. After this code has been executed,
-|\pgfkeys| continues with the next key in the \meta{key list}.
-
-It may seem quite peculiar that the macro stored in the key \meta{key}|/.@cmd|
-is not simply executed with the argument |{|\meta{value}|}|. However, the
-approach taken in the |pgfkeys| packages allows for more flexibility. For
-instance, assume that you have a key that expects a \meta{value} of the form
-``\meta{text}|+|\meta{more text}'' and wishes to store \meta{text} and
-\meta{more text} in two different macros. This can be achieved as follows:
-%
-\begin{codeexample}[]
-\def\mystore#1+#2\pgfeov{\def\a{#1}\def\b{#2}}
-\pgfkeyslet{/my key/.@cmd}{\mystore}
-\pgfkeys{/my key=hello+world}
-
-|\a| is \a, |\b| is \b.
-\end{codeexample}
-
-Naturally, defining the code to be stored in a key in the above manner is too
-awkward. The following commands simplify things a bit, but the usual manner of
-setting up code for a key is to use one of the handlers described in
-Section~\ref{section-code-handlers}.
-
-\begin{command}{\pgfkeysdef\marg{key}\marg{code}}
- This command temporarily defines a \TeX-macro with the argument list
- |#1\pgfeov| and then lets \meta{key}|/.@cmd| be equal to this macro. The
- net effect of all this is that you have then set up code for the key
- \meta{key} so that when you write |\pgfkeys{|\meta{key}|=|\meta{value}|}|,
- then the \meta{code} is executed with all occurrences of |#1| in
- \meta{code} being replaced by \meta{value}. (This behavior is quite
- similar to the |\define@key| command of |keyval| and |xkeyval|).
- %
-\begin{codeexample}[]
-\pgfkeysdef{/my key}{#1, #1.}
-\pgfkeys{/my key=hello}
-\end{codeexample}
-\end{command}
-
-\begin{command}{\pgfkeysedef\marg{key}\marg{code}}
- This command works like |\pgfkeysdef|, but it uses |\edef| rather than
- |\def| when defining the key macro. If you do not know the difference
- between the two, then you will not need this command; and if you know the
- difference, then you will know when you need this command.
-\end{command}
-
-\begin{command}{\pgfkeysdefnargs\marg{key}\marg{argument count}\marg{code}}
- This command works like |\pgfkeysdef|, but it allows you to provide an
- arbitrary \meta{argument count} between $0$ and $9$ (inclusive).
- %
-\begin{codeexample}[]
-\pgfkeysdefnargs{/my key}{2}{\def\a{#1}\def\b{#2}}
-\pgfkeys{/my key=
- {hello}
- {world}}
-
-|\a| is `\a', |\b| is `\b'.
-\end{codeexample}
- %
- The resulting key will expect exactly \marg{argument count} arguments.
-\end{command}
-%
-\begin{command}{\pgfkeysedefnargs\marg{key}\marg{argument count}\marg{code}}
- The |\edef| version of |\pgfkeysdefnargs|.
-\end{command}
-
-\begin{command}{\pgfkeysdefargs\marg{key}\marg{argument pattern}\marg{code}}
- This command works like |\pgfkeysdefnargs|, but it allows you to provide an
- arbitrary \meta{argument pattern} rather than just a number of arguments.
- %
-\begin{codeexample}[]
-\pgfkeysdefargs{/my key}{#1+#2}{\def\a{#1}\def\b{#2}}
-\pgfkeys{/my key=hello+world}
-
-|\a| is \a, |\b| is \b.
-\end{codeexample}
- %
- Note that |\pgfkeysdefnargs| is \emph{better} when it comes to simple
- argument \emph{counts}\footnote{When the resulting keys are used, the
- \texttt{defnargs} variant allows spaces between arguments whereas the
- \texttt{defargs} variant does not; it considers the spaces as part of the
- argument.}.
-\end{command}
-
-\begin{command}{\pgfkeysedefargs\marg{key}\marg{argument pattern}\marg{code}}
- The |\edef| version of |\pgfkeysdefargs|.
-\end{command}
-
-
-\subsubsection{Keys That Store Values}
-
-Let us continue with what happens when |\pgfkeys| processes the current key and
-the subkey \meta{key}|/.@cmd| is not defined. Then it is checked whether the
-\meta{key} itself exists (has been previously assigned a value using, for
-instance, |\pgfkeyssetvalue|). In this case, the tokens stored in \meta{key}
-are replaced by \meta{value} and |\pgfkeys| proceeds with the next key in the
-\meta{key list}.
-
-
-\subsubsection{Keys That Are Handled}
-\label{section-key-handlers}
-
-If neither the \meta{key} itself nor the subkey \meta{key}|/.@cmd| are defined,
-then the \meta{key} cannot be processed ``all by itself''. Rather, a
-\meta{handler} is needed for this key. Most of the power of |pgfkeys| comes
-from the proper use of such handlers.
-
-Recall that the \meta{key} is always a full key (if it was not originally, it
-has already been upgraded at this point to a full key). It decomposed into two
-parts:
-
-\begin{enumerate}
- \item The \meta{path} of \meta{key} (everything before the last slash) is
- stored in the macro |\pgfkeyscurrentpath|.
- \item The \meta{name} of \meta{key} (everything after the last slash) is
- stored in the macro |\pgfkeyscurrentname|.
-
- It is recommended (but not necessary) that the name of a handler starts
- with a dot (but not with |.@|), so that they are easy to detect for the
- reader.
-\end{enumerate}
-
-(For efficiency reasons, these two macros are only set up at this point; so
-when code is executed for a key in the ``usual'' manner then these macros are
-not set up.)
-
-The |\pgfkeys| command now checks whether the key
-|/handlers/|\meta{name}|/.@cmd| exists. If so, it should store a command and
-this command is executed exactly in the same manner as described in
-Section~\ref{section-key-code}. Thus, this code gets the \meta{value} that was
-originally intended for \meta{key} as its argument, followed by |\pgfeov|. It
-is the job of the handlers to do something useful with the \meta{value}.
-
-For an example, let us write a handler that will output the value stored in a
-key to the log file. We call this handler |/.print to log|. The idea is that
-when someone tries to use the key |/my key/.print to log|, then this key will
-not be defined and the handler gets executed. The handler will then have access
-to the path-part of the key, which is |/my key|, via the macro
-|\pgfkeyscurrentpath|. It can then lookup which value is stored in this key and
-print it.
-%
-\begin{codeexample}[code only]
-\pgfkeysdef{/handlers/.print to log}
-{%
- \pgfkeysgetvalue{\pgfkeyscurrentpath}{\temp}
- \writetolog{\temp}
-}
-\pgfkeyssetvalue{/my key}{Hi!}
-...
-\pgfkeys{/my key/.print to log}
-\end{codeexample}
-%
-The above code will print |Hi!| in the log, provided the macro |\writetolog| is
-set up appropriately.
-
-For a more interesting handler, let us program a handler that will set up a key
-so that when the key is used, some code is executed. This code is given as
-\meta{value}. All the handler must do is to call |\pgfkeysdef| for the path of
-the key (which misses the handler's name) and assign the parameter value to it.
-%
-\begin{codeexample}[]
-\pgfkeysdef{/handlers/.my code}{\pgfkeysdef{\pgfkeyscurrentpath}{#1}}
-\pgfkeys{/my key/.my code=(#1)}
-\pgfkeys{/my key=hallo}
-\end{codeexample}
-
-There are some parameters for handled keys which prove to be useful in some
-(possibly rare) special cases:
-%
-\begin{key}{/handler config=\mchoice{all,only existing,full or existing} (initially all)}
- Changes the initial configuration how key handlers will be used.
-
- This configuration is for advanced users and rarely necessary.
- %
- \begin{description}
- \item[\texttt{all}] The preconfigured setting |all| works as described
- above and imposes no restriction on the key setting process.
- \item[\texttt{only existing}] The value |only existing| modifies the
- algorithm for handled keys as follows: a handler \meta{key
- name}|/.|\meta{handler} will be executed only if \meta{key name} is
- either a key which stores its value directly or a command key for
- which |/.@cmd| exists. If \meta{key name} does \emph{not} exist
- already, the complete string \meta{key name}|/.|\meta{handler} is
- considered to be an unknown key and the procedure described in the
- next section applies (for the path of \meta{key name}).
- %
-\begin{codeexample}[]
-% Define a test key and error handlers:
-\pgfkeys{/the/key/.code={Initial definition. }}
-\pgfkeys{/handlers/.unknown/.code={Unknown key `\pgfkeyscurrentkey'. }}
-
-% calling the test key yields 'Initial definition. ':
-\pgfkeys{/the/key}
-
-% Change configuration:
-\pgfkeys{/handler config=only existing}
-
-% allowed: key *re*-definition:
-\pgfkeys{/the/key/.code={Re-Definition. }}
-% calling the key yields 'Re-Definition. ':
-\pgfkeys{/the/key}
-
-% not allowed: definition of new keys:
-% this checks for '/the/other key/.unknown'
-% and '/handlers/.unknown'
-% and yields finally
-% 'Unknown key `/the/other key/.code`'
-\pgfkeys{/the/other key/.code={New definition. }}
-\end{codeexample}
- %
- It is necessary to exclude some key handlers from this procedure.
- Altogether, the detailed procedure is as follows:
- %
- \begin{enumerate}
- \item If a handled key like |/a path/a key/.a handler=value| is
- encountered, it is checked whether the handler should be
- invoked. This is the case if
- %
- \begin{itemize}
- \item An exception from |only existing| for this key
- exists (see below),
- \item The key |/a path/a key| exists already -- either
- directly as storage key or with the |.@cmd| suffix.
- \end{itemize}
- %
- \item If the check passes, everything works as before.
- \item If the check fails, the complete key will be considered
- to be unknown. In that case, the handling of unknown keys
- as described in the next section applies. There, the
- current key path will be set to |/a path| and the current
- key's name to |key/.a handler|.
- \end{enumerate}
-
- A consequence of this configuration is to provide more meaningful
- processing of handled keys if a search path for keys is in effect,
- see section~\ref{sec:pgf:unknown:keys} for an example.
- \item[\texttt{full or existing}] Finally, the choice |full or existing|
- is a variant of |only existing|: it works in the same way for keys
- which do not have a full key path. For example, the style
-
- |\pgfkeys{/my path/.cd,key/.style={|$\dotsc$|}}|
-
- can only be redefined: it doesn't have a full path, so the
- |only existing| mechanism applies. But the style
-
- |\pgfkeys{/my path/key/.style={|$\dotsc$|}}|
-
- will still work. This allows users to override the |only existing|
- feature if they know what they're doing (and provide full key
- paths).
- \end{description}
-\end{key}
-
-\begin{key}{/handler config/only existing/add exception=\marg{key handler name}}
- Allows to add exceptions to the |/handler config=only existing| feature.
- Initially exceptions for the key handlers |/.cd|, |/.try|, |/.retry|,
- |/.lastretry| and |/.unknown| are defined. The value \marg{key handler
- name} should be the name of a key handler.
-\end{key}
-
-
-\subsubsection{Keys That Are Unknown}
-\label{sec:pgf:unknown:keys}
-
-For some keys, neither the key, nor its |.@cmd| subkey nor a handler is
-defined. In this case, it is checked whether the key \meta{current
-path}|/.unknown/.@cmd| exists. Thus, when you try to use the key
-|/tikz/strange|, then it is checked whether |/tikz/.unknown/.@cmd| exists. If
-this key exists (which it does), it is executed. This code can then try to make
-sense of the key. For instance, the handler for \tikzname\ will try to
-interpret the key's name as a color or as an arrow specification or as a
-\pgfname\ option.
-
-You can set up unknown key handlers for your own keys by simply setting the
-code of the key \meta{my path prefix}|/.unknown|. This also allows you to set
-up ``search paths''. The idea is that you would like keys to be searched not
-only in a single default path, but in several. Suppose, for instance, that you
-would like keys to be searched for in |/a|, |/b|, and |/b/c|. We set up a key
-|/my search path| for this:
-%
-\begin{codeexample}[code only]
-\pgfkeys{/my search path/.unknown/.code=
- {%
- \let\searchname=\pgfkeyscurrentname%
- \pgfkeysalso{%
- /a/\searchname/.try=#1,
- /b/\searchname/.retry=#1,
- /b/c/\searchname/.retry=#1%
- }%
- }%
-}
-\pgfkeys{/my search path/.cd,foo,bar}
-\end{codeexample}
-%
-In the above code, |foo| and |bar| will be searched for in the three
-directories |/a|, |/b|, and |/b/c|. Before you start implementing search paths
-using this pattern, consider the |/.search also| handler discussed below.
-
-If the key \meta{current path}|/.unknown/.@cmd| does not exist, the handler
-|/handlers/.unknown| is invoked instead, which is always defined and which
-prints an error message by default.
-
-
-\subsubsection{Search Paths And Handled Keys}
-
-There is one special case which occurs in the search path example above. What
-happens if we want to change a style? For example,
-%
-\begin{codeexample}[code only]
-\pgfkeys{/my search path/.cd,custom/.style={variables}}
-\end{codeexample}
-%
-\noindent could mean a style in |/my search path/|, |/a/|, |/b/| or even
-|/b/c/|!
-
-Due to the rules for handled keys, the answer is
-|/my search path/custom/.style={variables}|. It may be useful to modify this
-default behavior. One useful thing would be to search for \emph{existing}
-styles named |custom| and redefine them. For example, if a style |/b/custom|
-exists, the assignment |custom/.style={variables}| should probably redefine
-|/b/custom| instead of |/my search path/custom|. This can be done using
-|handler config|:
-%
-\begin{codeexample}[]
-\pgfkeys{/my search path/.unknown/.code=
- {%
- \let\searchname=\pgfkeyscurrentname%
- \pgfkeysalso{%
- /a/\searchname/.try=#1,
- /b/\searchname/.retry=#1,
- /b/c/\searchname/.retry=#1%
- }%
- }%
-}
-
-% Let's define /b/custom here:
-\pgfkeys{/b/custom/.code={This is `\pgfkeyscurrentkey'. }}
-
-% Reconfigure treatment of key handlers:
-\pgfkeys{/handler config=only existing}
-
-% The search path procedure will find /b/custom
-% -> leads to This is `/b/custom'
-\pgfkeys{/my search path/.cd,custom}
-
-% Due to the reconfiguration, this will find /b/custom instead of
-% defining /my search path/custom:
-\pgfkeys{/my search path/.cd,custom/.append code={Modified. }}
-
-% So using the search path, we again find /b/custom which
-% leads to This is `/b/custom' Modified
-\pgfkeys{/my search path/.cd,custom}
-\end{codeexample}
-
-A slightly different approach to search paths can be realized using the
-|/.search also| key handler, see below.
-
-
-\subsection{Key Handlers}
-
-We now describe which key handlers are defined by default. You can also define
-new ones as described in Section~\ref{section-key-handlers}.
-
-
-\subsubsection{Handlers for Path Management}
-
-\begin{handler}{{.cd}}
- This handler causes the default path to be set to \meta{key}. Note that the
- default path is reset at the beginning of each call to |\pgfkeys| to be
- equal to~|/|.
-
- \example |\pgfkeys{/tikz/.cd,...}|
-\end{handler}
-
-\begin{handler}{{.is family}}
-\label{section-is family-handler}
- This handler sets up things such that when \meta{key} is executed, then the
- current path is set to \meta{key}. A typical use is the following:
- %
-\begin{codeexample}[code only]
-\pgfkeys{/tikz/.is family}
-\pgfkeys{tikz,line width=1cm}
-\end{codeexample}
- %
- The effect of this handler is the same as if you had written
- \meta{key}|/.style=|\meta{key}|/.cd|, only the code produced by the
- |/.is family| handler is quicker.
-\end{handler}
-
-
-\subsubsection{Setting Defaults}
-\label{section-default-handlers}
-
-\begin{handler}{{.default}|=|\meta{value}}
- Sets the default value of \meta{key} to \meta{value}. This means that
- whenever no value is provided in a call to |\pgfkeys|, then this
- \meta{value} will be used instead.
-
- \example |\pgfkeys{/width/.default=1cm}|
-\end{handler}
-
-\begin{handler}{{.value required}}
- This handler causes the error message key |/erros/value required| to be
- issued whenever the \meta{key} is used without a value.
-
- \example |\pgfkeys{/width/.value required}|
-\end{handler}
-
-\begin{handler}{{.value forbidden}}
- This handler causes the error message key |/erros/value forbidden| to be
- issued whenever the \meta{key} is used with a value.
-
- This handler works be adding code to the code of the key. This means that
- you have to define the key first before you can use this handler.
- %
-\begin{codeexample}[code only]
-\pgfkeys{/my key/.code=I do not want an argument!}
-\pgfkeys{/my key/.value forbidden}
-
-\pgfkeys{/my key} % Ok
-\pgfkeys{/my key=foo} % Error
-\end{codeexample}
- %
-\end{handler}
-
-
-\subsubsection{Defining Key Codes}
-\label{section-code-handlers}
-
-A number of handlers exist for defining the code of keys.
-
-\begin{handler}{{.code}|=|\meta{code}}
- This handler executes |\pgfkeysdef| with the parameters \meta{key} and
- \meta{code}. This means that, afterwards, whenever the \meta{key} is used,
- the \meta{code} gets executed. More precisely, when
- \meta{key}|=|\meta{value} is encountered in a key list, \meta{code} is
- executed with any occurrence of |#1| replaced by \meta{value}. As always,
- if no \meta{value} is given, the default value is used, if defined, or the
- special value |\pgfkeysnovalue|.
-
- It is permissible that \meta{code} calls the command |\pgfkeys|. It is also
- permissible the \meta{code} calls the command |\pgfkeysalso|, which is
- useful for styles, see below.
- %
-\begin{codeexample}[code only]
-\pgfkeys{/par indent/.code={\parindent=#1},/par indent/.default=2em}
-\pgfkeys{/par indent=1cm}
-...
-\pgfkeys{/par indent}
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.ecode}|=|\meta{code}}
- This handler works like |/.code|, only the command |\pgfkeysedef| is used.
-\end{handler}
-
-\begin{handler}{{.code 2 args}|=|\meta{code}}
- This handler works like |/.code|, only two arguments rather than one are
- expected when the \meta{code} is executed. This means that when
- \meta{key}|=|\meta{value} is encountered in a key list, the \meta{value}
- should consist of two arguments. For instance, \meta{value} could be
- |{first}{second}|. Then \meta{code} is executed with any occurrence of |#1|
- replaced |first| and any occurrence of |#2| replaced by |second|.
- %
-\begin{codeexample}[code only]
-\pgfkeys{/page size/.code 2 args={\paperheight=#2\paperwidth=#1}}
-\pgfkeys{/page size={30cm}{20cm}}
-\end{codeexample}
- %
- Because of the special way the \meta{value} is parsed, if you set
- \meta{value} to, for instance, |first| (without any braces), then |#1| will
- be set to |f| and |#2| will be set to |irst|.
-\end{handler}
-
-\begin{handler}{{.ecode 2 args}|=|\meta{code}}
- This handler works like |/.code 2 args|, only an |\edef| is used rather
- than a |\def| to define the macro.
-\end{handler}
-
-\begin{handler}{{.code n args}|=|\marg{argument count}\marg{code}}
- This handler also works like |/.code|, but you can now specify a number of
- arguments between $0$ and $9$ (inclusive).
- %
-\begin{codeexample}[]
-\pgfkeys{/a key/.code n args={2}{First=`#1', Second=`#2'}}
-\pgfkeys{/a key={A}{B}}
-\end{codeexample}
- %
- In contrast to |/.code 2 args|, there must be exactly \meta{argument count}
- arguments, not more and not less and these arguments should be properly
- delimited.
-\end{handler}
-
-\begin{handler}{{.ecode n args}|=|\marg{argument count}\marg{code}}
- This handler works like |/.code n args|, only an |\edef| is used rather
- than a |\def| to define the macro.
-\end{handler}
-
-\begin{handler}{{.code args}|=|\marg{argument pattern}\marg{code}}
- This handler is the most flexible way to define a |/.code| key: you can now
- specify an arbitrary \meta{argument pattern}. Such a pattern is a usual
- \TeX\ macro pattern. For instance, suppose \meta{argument pattern} is
- |(#1/#2)| and \meta{key}|=|\meta{value} is encountered in a key list with
- \meta{value} being |(first/second)|. Then \meta{code} is executed with any
- occurrence of |#1| replaced |first| and any occurrence of |#2| replaced by
- |second|. So, the actual \meta{value} is matched against the \meta{argument
- pattern} in the standard \TeX\ way.
- %
-\begin{codeexample}[code only]
-\pgfkeys{/page size/.code args={#1 and #2}{\paperheight=#2\paperwidth=#1}}
-\pgfkeys{/page size=30cm and 20cm}
-\end{codeexample}
-
- Note that |/.code n args| should be preferred in case you need just a
- number of arguments (when the resulting keys are used, |/.code n args|
- gobbles spaces between the arguments whereas |/.code args| considers spaces
- to be part of the argument).
-\end{handler}
-
-\begin{handler}{{.ecode args}|=|\marg{argument pattern}\marg{code}}
- This handler works like |/.code args|, only an |\edef| is used rather than
- a |\def| to define the macro.
-\end{handler}
-
-There are also handlers for modifying existing keys.
-
-\begin{handler}{{.add code}|=|\marg{prefix code}\marg{append code}}
- This handler adds code to an existing key. The \meta{prefix code} is added
- to the code stored in \meta{key}|/.@cmd| at the beginning, the \meta{append
- code} is added to this code at the end. Either can be empty. The argument
- list of \meta{code} cannot be changed using this handler. Note that both
- \meta{prefix code} and \meta{append code} may contain parameters like |#2|.
- %
-\begin{codeexample}[code only]
-\pgfkeys{/par indent/.code={\parindent=#1}}
-\newdimen\myparindent
-\pgfkeys{/par indent/.add code={}{\myparindent=#1}}
-...
-\pgfkeys{/par indent=1cm} % This will set both \parindent and
- % \myparindent to 1cm
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.prefix code}|=|\meta{prefix code}}
- This handler is a shortcut for \meta{key}|/.add code={|\meta{prefix
- code}|}{}|. That is, this handler adds the \meta{prefix code} at the
- beginning of the code stored in \meta{key}|/.@cmd|.
-\end{handler}
-
-\begin{handler}{{.append code}|=|\meta{append code}}
- This handler is a shortcut for \meta{key}|/.add code={}{|\meta{append
- code}|}{}|.
-\end{handler}
-
-
-\subsubsection{Defining Styles}
-
-The following handlers allow you to define \emph{styles}. A style is a key list
-that is processed whenever the style is given as a key in a key list. Thus, a
-style ``stands for'' a certain key value list. Styles can be parameterized just
-like normal code.
-
-\begin{handler}{{.style}|=|\meta{key list}}
- This handler sets things up so that whenever \meta{key}|=|\meta{value} is
- encountered in a key list, then the \meta{key list}, with every occurrence
- of |#1| replaced by \meta{value}, is processed instead. As always, if no
- \meta{value} is given, the default value is used, if defined, or the
- special value |\pgfkeysnovalue|.
-
- You can achieve the same effect by writing
- \meta{key}|/.code=\pgfkeysalso{|\meta{key list}|}|. This means, in
- particular, that the code of a key could also first execute some normal
- code and only then process some further keys.
- %
-\begin{codeexample}[code only]
-\pgfkeys{/par indent/.code={\parindent=#1}}
-\pgfkeys{/no indent/.style={/par indent=0pt}}
-\pgfkeys{/normal indent/.style={/par indent=2em}}
-\pgfkeys{/no indent}
-...
-\pgfkeys{/normal indent}
-\end{codeexample}
- %
- The following example shows a parameterized style ``in action''.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[outline/.style={draw=#1,fill=#1!20}]
- \node [outline=red] {red box};
- \node [outline=blue] at (0,-1) {blue box};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.estyle}|=|\meta{key list}}
- This handler works like |/.style|, only the \meta{code} is set using
- |\edef| rather than |\def|. Thus, all macros in the \meta{code} are
- expanded prior to saving the style.
-\end{handler}
-
-For styles the corresponding handlers as for normal code exist:
-
-\begin{handler}{{.style 2 args}|=|\meta{key list}}
- This handler works like |/.code 2 args|, only for styles. Thus, the
- \meta{key list} may contain occurrences of both |#1| and |#2| and when the
- style is used, two parameters must be given as \meta{value}.
- %
-\begin{codeexample}[code only]
-\pgfkeys{/paper height/.code={\paperheight=#1},/paper width/.code={\paperwidth=#1}}
-\pgfkeys{/page size/.style 2 args={/paper height=#1,/paper width=#2}}
-\pgfkeys{/page size={30cm}{20cm}}
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.estyle 2 args}|=|\meta{key list}}
- This handler works like |/.style 2 args|, only an |\edef| is used rather
- than a |\def| to define the macro.
-\end{handler}
-
-\begin{handler}{{.style n args}|=|\marg{argument count}\meta{key list}}
- This handler works like |/.code n args|, only for styles. Here, \meta{key
- list} may depend on all \meta{argument count} parameters.
-\end{handler}
-
-\begin{handler}{{.add style}|=|\marg{prefix key list}\marg{append key list}}
- This handler works like |/.add code|, only for styles. However, it is
- permissible to add styles to keys that have previously been set using
- |/.code|. (It is also permissible to add normal \meta{code} to a key that
- has previously been set using |/.style|). When you add a style to a key
- that was previously set using |/.code|, the following happens: When
- \meta{key} is processed, the \meta{prefix key list} will be processed
- first, then the \meta{code} that was previously stored in
- \meta{key}|/.@cmd|, and then the keys in \meta{append key list} are
- processed.
- %
-\begin{codeexample}[code only]
-\pgfkeys{/par indent/.code={\parindent=#1}}
-\pgfkeys{/par indent/.add style={}{/my key=#1}}
-...
-\pgfkeys{/par indent=1cm} % This will set \parindent and
- % then execute /my key=#1
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.style args}|=|\marg{argument pattern}\marg{key list}}
- This handler works like |/.code args|, only for styles.
-\end{handler}
-
-\begin{handler}{{.estyle args}|=|\marg{argument pattern}\marg{code}}
- This handler works like |/.ecode args|, only for styles.
-\end{handler}
-
-\begin{handler}{{.prefix style}|=|\meta{prefix key list}}
- Works like |/.add style|, but only for the prefix key list.
-\end{handler}
-
-\begin{handler}{{.append style}|=|\meta{append key list}}
- Works like |/.add style|, but only for the append key list.
-\end{handler}
-
-
-\subsubsection{Defining Value-, Macro-, If- and Choice-Keys}
-
-For some keys, the code that should be executed for them is rather
-``specialized''. For instance, it happens often that the code for a key just
-sets a certain \TeX-if to true or false. For these cases, predefined handlers
-make it easier to install the necessary code.
-
-However, we start with some handlers that are used to manage the value that is
-directly stored in a key.
-
-\begin{handler}{{.initial}|=|\meta{value}}
- This handler sets the value of \meta{key} to \meta{value}. Note that no
- subkeys are involved. After this handler has been used, by the rules
- governing keys, you can subsequently change the value of the \meta{key} by
- just writing \meta{key}|=|\meta{value}. Thus, this handler is used to set
- the initial value of key.
- %
-\begin{codeexample}[code only]
-\pgfkeys{/my key/.initial=red}
-% "/my key" now stores the value "red"
-\pgfkeys{/my key=blue}
-% "/my key" now stores the value "blue"
-\end{codeexample}
-
- Note that with this configuration, writing |\pgfkeys{/my key}| will not
- have the effect you might expect (namely that |blue| is inserted into the
- main text). Rather, |/my key| will be promoted to |/my key=\pgfkeysnovalue|
- and, thus, |\pgfkeysnovalue| will be stored in |/my key|.
-
- To retrieve the value stored in a key, the handler |/.get| is used.
-
- \medskip
- \emph{Remark:} A key can both store a value and execute commands%
- \footnote{This behavior was partially changed in \pgfname{} 3.1.6 and then
- restored in 3.1.7. For compatibility reasons, this behavior will not be
- changed in future releases anymore.}.
- If so, using \meta{key} will \emph{always} execute commands with the passed
- value, or the default value |\pgfkeysnovalue| if no value is provided.
- Note that the stored value is never used. To update the stored value, the
- handler |/.initial| or command |\pgfkeyssetvalue| is used.
- %
-\begin{codeexample}[]
-\pgfkeys{/my key/.initial=red}
-\pgfkeys{/my key/.code=#1}
-% "/my key" now both stores the value "red" and executes commands
-\pgfkeys{/my key=blue}
-% "/my key" now still stores the value "red"
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.get}|=|\meta{macro}}
- Executes a |\let| command so that \meta{macro} contains the contents stored
- in \meta{key}.
- %
-\begin{codeexample}[]
-\pgfkeys{/my key/.initial=red}
-\pgfkeys{/my key=blue}
-\pgfkeys{/my key/.get=\mymacro}
-\mymacro
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.add}|=|\marg{prefix value}\marg{append value}}
- Adds the \meta{prefix value} at the beginning and the \meta{append value}
- at the end of the value stored in \meta{key}.
-\end{handler}
-
-\begin{handler}{{.prefix}|=|\marg{prefix value}}
- Adds the \meta{prefix value} and the beginning of the value stored in
- \meta{key}.
-\end{handler}
-
-\begin{handler}{{.append}|=|\marg{append value}}
- Adds the \meta{append value} at the end of the value stored in \meta{key}.
-\end{handler}
-
-\begin{handler}{{.link}|=|\meta{another key}}
- Stores the value |\pgfkeysvalueof{|\meta{another key}|}| in the \meta{key}.
- The idea is that when you expand the \meta{key}, the value of \meta{another
- key} is expanded instead. This corresponds loosely to the notion of soft
- links in Unix, hence the name.
-\end{handler}
-
-The next handler is useful for the common situation where
-\meta{key}|=|\meta{value} should cause the \meta{value} to be stored in some
-macro. Note that, typically, you could just as well store the value in the key
-itself.
-
-\begin{handler}{{.store in}|=|\meta{macro}}
- This handler has the following effect: When you write
- \meta{key}|=|\meta{value}, the code |\def|\meta{macro}|{|\meta{value}|}| is
- executed. Thus, the given value is ``stored'' in the \meta{macro}.
- %
-\begin{codeexample}[]
-\pgfkeys{/text/.store in=\mytext}
-\def\a{world}
-\pgfkeys{/text=Hello \a!}
-\def\a{Gruffalo}
-\mytext
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.estore in}|=|\meta{macro}}
- This handler is similar to |/.store in|, only the code
- |\edef|\meta{macro}|{|\meta{value}|}| is used. Thus, the macro-expanded
- version of \meta{value} is stored in the \meta{macro}.
- %
-\begin{codeexample}[]
-\pgfkeys{/text/.estore in=\mytext}
-\def\a{world}
-\pgfkeys{/text=Hello \a!}
-\def\a{Gruffalo}
-\mytext
-\end{codeexample}
- %
-\end{handler}
-
-In another common situation a key is used to set a \TeX-if to true or false.
-
-\begin{handler}{{.is if}|=|\meta{\TeX-if name}}
- This handler has the following effect: When you write
- \meta{key}|=|\meta{value}, it is first checked that \meta{value} is |true|
- or |false| (the default is |true| if no \meta{value} is given). If this is
- not the case, the error key |/errors/boolean expected| is executed.
- Otherwise, the code |\|\meta{\TeX-if name}\meta{value} is executed, which
- sets the \TeX-if accordingly.
- %
-\begin{codeexample}[]
-\newif\iftheworldisflat
-\pgfkeys{/flat world/.is if=theworldisflat}
-\pgfkeys{/flat world=false}
-\iftheworldisflat
- Flat
-\else
- Round?
-\fi
-\end{codeexample}
- %
-\end{handler}
-
-The next handler deals with the problem when a \meta{key}|=|\meta{value} makes
-sense only for a small set of possible \meta{value}s. For instance, the line
-cap can only be |rounded| or |rect| or |butt|, but nothing else. For this
-situation the following handler is useful.
-
-\begin{handler}{{.is choice}}
- This handler sets things up so that writing \meta{key}|=|\meta{value} will
- cause the subkey \meta{key}|/|\meta{value} to be executed. So, each of the
- different possible choices should be given by a subkey of \meta{key}.
- %
-\begin{codeexample}[code only]
-\pgfkeys{/line cap/.is choice}
-\pgfkeys{/line cap/round/.code={\pgfsetbuttcap}}
-\pgfkeys{/line cap/butt/.code={\pgfsetroundcap}}
-\pgfkeys{/line cap/rect/.code={\pgfsetrectcap}}
-\pgfkeys{/line cap/rectangle/.style={/line cap=rect}}
-...
-\draw [/line cap=butt] ...
-\end{codeexample}
- %
- If the subkey \meta{key}|/|\meta{value} does not exist, the error key
- |/errors/unknown choice value| is executed.
-\end{handler}
-
-
-\subsubsection{Expanded and Multiple Values}
-
-When you write \meta{key}|=|\meta{value}, you usually wish to use the
-\meta{value} ``as is''. Indeed, great care is taken to ensure that you can even
-use things like |#1| or unbalanced \TeX-ifs inside \meta{value}. However,
-sometimes you want the \meta{value} to be expanded before it is used. For
-instance, \meta{value} might be a macro name like |\mymacro| and you do not
-want |\mymacro| to be used as the macro, but rather the \emph{contents} of
-|\mymacro|. Thus, instead of using \meta{value}, you wish to use whatever
-\meta{value} expands to. Instead of using some fancy |\expandafter| hackery,
-you can use the following handlers:
-
-\begin{handler}{{.expand once}|=|\meta{value}}
- This handler expands \meta{value} once (more precisely, it executes an
- |\expandafter| command on the first token of \meta{value}) and then process
- the resulting \meta{result} as if you had written
- \meta{key}|=|\meta{result}. Note that if \meta{key} contains a handler
- itself, this handler will be called normally.
- %
-\begin{codeexample}[]
-\def\a{bottom}
-\def\b{\a}
-\def\c{\b}
-
-\pgfkeys{/key1/.initial=\c}
-\pgfkeys{/key2/.initial/.expand once=\c}
-\pgfkeys{/key3/.initial/.expand twice=\c}
-\pgfkeys{/key4/.initial/.expanded=\c}
-
-\def\a{{\ttfamily\string\a}}
-\def\b{{\ttfamily\string\b}}
-\def\c{{\ttfamily\string\c}}
-
-\begin{tabular}{ll}
-Key 1:& \pgfkeys{/key1} \\
-Key 2:& \pgfkeys{/key2} \\
-Key 3:& \pgfkeys{/key3} \\
-Key 4:& \pgfkeys{/key4}
-\end{tabular}
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.expand twice}|=|\meta{value}}
- This handler works like saying
- \meta{key}|/.expand once/.expand once=|\meta{value}.
-\end{handler}
-
-\begin{handler}{{.expanded}|=|\meta{value}}
- This handler will completely expand \meta{value} (using |\edef|) before
- processing \meta{key}|=|\meta{result}.
-\end{handler}
-
-\begin{handler}{{.evaluated}|=|\meta{value}}
- This handler will evaluate \meta{value} as a mathematical
- expression with |\pgfmathparse| and assign \meta{key}|=\pgfmathresult|.
- %
-\begin{codeexample}[]
-\pgfkeys{
- /golden ratio/.initial/.evaluated={(1 + sqrt(5))/2},
-}
-\pgfkeys{/golden ratio}
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.list}|=|\meta{comma-separated list of values}}
- This handler causes the key to be used repeatedly, namely once for every
- element of the list of values. Note that the list of values should
- typically be surrounded by braces since, otherwise, \TeX\ will not be able
- to tell whether a comma starts a new key or a new value.
-
- The \meta{list of values} is processed using the |\foreach| statement, so
- you can use the |...| notation.
- %
-\begin{codeexample}[]
-\pgfkeys{/foo/.code=(#1)}
-\pgfkeys{/foo/.list={a,b,0,1,...,5}}
-\end{codeexample}
- %
-\end{handler}
-
-
-\subsubsection{Handlers for Forwarding}
-
-\begin{handler}{{.forward to}|=|\meta{another key}}
- This handler causes the \meta{key} to ``forward'' its argument to
- \meta{another key}. When the \meta{key} is used, its normal code will be
- executed first. Then, the value is (additionally) passed to \meta{another
- key}. If the \meta{key} has not yet been defined prior to the use of
- |.forward to|, it will be defined then (and do nothing by itself, expect
- for forwarding it to \meta{key name}). The \meta{another key} must be a
- fully qualified key name.
- %
-\begin{codeexample}[]
-\pgfkeys{
- /a/.code=(a:#1),
- /b/.code=(b:#1),
- /b/.forward to=/a,
- /c/.forward to=/a
-}
-\pgfkeys{/b=1} \pgfkeys{/c=2}
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.search also}=\marg{path list}}
- A style which installs a |/.unknown| handler into \meta{key}. This
- |/.unknown| handler will then search for unknown keys in every path
- provided in \marg{path list}.
- %
-\begin{codeexample}[]
-% define a key:
-\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}}
-
-% set up a search path:
-\pgfkeys{/main path/.search also={/secondary path}}
-
-% try searching for `option=value' in '/main path':
-% -> this finds `/secondary path/option'!
-\pgfkeys{/main path/.cd,option=value}
-\end{codeexample}
-
- The |/.search also| handler follows the strategy
- %
- \begin{enumerate}
- \item If a user provides a fully qualified key which could not be
- found, for example the full string |/main path/option|, it assumes
- that the user knew what she is doing -- and does \emph{not}
- continue searching for |option| in \marg{path list}.
- \item If a user provides only the key's name, for example |option| and
- |option| cannot be found in the current default path (which is
- |/main path| in our example above), the current default path is set
- to the next element in \marg{path list} (which is |/secondary path|
- here) and |\pgfkeys| will be restarted.
-
- This will be iterated until either a match has been found or all
- elements in \marg{path list} have been tested.
- \item If all
- elements in \marg{path list} have been checked and the key is still
- unknown, the fall-back handler |/handlers/.unknown| will be
- invoked.
- \end{enumerate}
- %
-\begin{codeexample}[]
-% define a key:
-\pgfkeys{/secondary path/option/.code={Invoking /secondary path/option with `#1'}}
-
-% set up a search path:
-\pgfkeys{/main path/.search also={/secondary path}}
-
-% try searching for `option=value' in '/main path':
-% -> this finds `/secondary path/option'!
-\pgfkeys{/main path/.cd,option=value}
-
-% negative example:
-% try searching for fully qualified key /main path/option.
-% This won't be handled by .search also.
-\pgfkeys{/handlers/.unknown/.code={Found unknown option \pgfkeyscurrentkeyRAW={#1}!}}%
-\pgfkeys{/main path/.cd,/main path/option=value}
-\end{codeexample}
-
- Please note that the strategy of |/.search also| is different from the
- first example provided in section~\ref{sec:pgf:unknown:keys} ``Unknown
- Keys'' because |/.search also| only applies to keys that are not fully
- qualified.
-
- For those who are familiar with |\pgfkeys|, the actual implementation of
- |/.search also| might be interesting:
- %
- \begin{enumerate}
- \item |\pgfkeys{/path/.search also={/tikz}}| is equivalent to
- %
-\begin{codeexample}[code only]
-\pgfkeys{/path/.unknown/.code={%
- \def\pgfkeys@searchalso@temp@value{#1}%
- \ifpgfkeysaddeddefaultpath
- \expandafter\pgfkeys@firstoftwo
- \else
- \expandafter\pgfkeys@secondoftwo
- \fi{%
- % only process keys for which no full path has been
- % provided:
- \pgfkeyssuccessfalse
- \let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW
- \ifpgfkeyssuccess
- \else
- % search with /tikz as default path:
- \pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.expand once=%
- \pgfkeys@searchalso@temp@value}%
- \fi
- }{%
- \pgfkeysgetvalue{/handlers/.unknown/.@cmd}{\pgfkeys@code}%
- \expandafter\pgfkeys@code\pgfkeys@searchalso@temp@value\pgfeov
- }%
- }
-}
-\end{codeexample}
- %
- \item |\pgfkeys{/path/.search also={/tikz,/pgf}}| is equivalent to
- %
-\begin{codeexample}[code only]
-\pgfkeys{/path/.unknown/.code={%
- \def\pgfkeys@searchalso@temp@value{#1}%
- \ifpgfkeysaddeddefaultpath
- \expandafter\pgfkeys@firstoftwo
- \else
- \expandafter\pgfkeys@secondoftwo
- \fi{%
- \pgfkeyssuccessfalse
- \let\pgfkeys@searchalso@name=\pgfkeyscurrentkeyRAW
- \ifpgfkeyssuccess
- \else
- % step 1: search in /tikz with .try:
- \pgfqkeys{/tikz}{\pgfkeys@searchalso@name/.try/.expand once=%
- \pgfkeys@searchalso@temp@value}%
- \fi
- \ifpgfkeyssuccess
- \else
- % step 2: search in /pgf (without .try!):
- \pgfqkeys{/pgf}{\pgfkeys@searchalso@name/.expand once=\pgfkeys@searchalso@}%
- \fi
- }{%
- \pgfkeysgetvalue{/handlers/.unknown/.@cmd}{\pgfkeys@code}%
- \expandafter\pgfkeys@code\pgfkeys@searchalso@temp@value\pgfeov
- }%
- }
-}
-\end{codeexample}
- \end{enumerate}
-
- To also enable searching for styles (or other handled keys), consider
- changing the configuration for handled keys to
- |/handler config=full or existing| when you use |/.search also|, that is,
- use
- %
-\begin{codeexample}[code only]
-\pgfkeys{
- /main path/.search also={/secondary path},
- /handler config=full or existing}
-\end{codeexample}
- %
-\end{handler}
-
-
-\subsubsection{Handlers for Testing Keys}
-
-\begin{handler}{{.try}|=|\meta{value}}
- This handler causes the same things to be done as if
- \meta{key}|=|\meta{value} had been written instead. However, if neither
- \meta{key}|/.@cmd| nor the key itself is defined, no handlers will be
- called. Instead, the execution of the key just stops. Thus, this handler
- will ``try'' to use the key, but no further action is taken when the key is
- not defined.
-
- The \TeX-if |\ifpgfkeyssuccess| will be set according to whether the
- \meta{key} was successfully executed or not.
- %
-\begin{codeexample}[]
-\pgfkeys{/a/.code=(a:#1)}
-\pgfkeys{/b/.code=(b:#1)}
-\pgfkeys{/x/.try=hmm,/a/.try=hallo,/b/.try=welt}
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.retry}|=|\meta{value}}
- This handler works just like |/.try|, only it will not do anything if
- |\ifpgfkeyssuccess| is false. Thus, this handler will only retry to set a
- key if ``the last attempt failed''.
- %
-\begin{codeexample}[]
-\pgfkeys{/a/.code=(a:#1)}
-\pgfkeys{/b/.code=(b:#1)}
-\pgfkeys{/x/.try=hmm,/a/.retry=hallo,/b/.retry=welt}
-\end{codeexample}
- %
-\end{handler}
-
-\begin{handler}{{.lastretry}|=|\meta{value}}
- This handler works like |/.retry|, only it will invoke the usual handlers
- for unknowns keys if |\ifpgfkeyssuccess| is false. Thus, this handler
- will only try to set a key if ``the last attempt failed''. Furthermore,
- this here is the last such attempt.
-\end{handler}
-
-
-\subsubsection{Handlers for Key Inspection}
-
-\begin{handler}{{.show value}}
- This handler executes a |\show| command on the value stored in \meta{key}.
- This is useful mostly for debugging.
-
- \example |\pgfkeys{/my/obscure key/.show value}|
-\end{handler}
-
-\begin{handler}{{.show code}}
- This handler executes a |\show| command on the code stored in
- \meta{key}|/.@cmd|. This is useful mostly for debugging.
-
- \example |\pgfkeys{/my/obscure key/.show code}|
-\end{handler}
-
-The following key is not a handler, but it also commonly used for inspecting
-things:
-%
-\begin{key}{/utils/exec=\meta{code}}
- This key will simply execute the given \meta{code}.
-
- % FIXME: there is a bug in the pretty printer ... fix it!
- \example \verb|\pgfkeys{some key=some value,/utils/exec=\show\hallo,obscure key=obscure}|
-\end{key}
-
-
-\subsection{Error Keys}
-
-In certain situations errors can occur, like using an undefined key. In these
-situations error keys are executed. They should store a macro that gets two
-arguments: The first is the offending key (possibly only after macro
-expansion), the second is the value that was passed as a parameter (also
-possibly only after macro expansion).
-
-Currently, error keys are simply executed. In the future it might be a good
-idea to have different subkeys that are executed depending on the language
-currently set so that users get a localized error message.
-
-\begin{key}{/errors/value required=\marg{offending key}\marg{value}}
- This key is executed whenever an \meta{offending key} is used without a
- value when a value is actually required.
-\end{key}
-
-\begin{key}{/errors/value forbidden=\marg{offending key}\marg{value}}
- This key is executed whenever a key is used with a value when a value is
- actually forbidden.
-\end{key}
-
-\begin{key}{/errors/boolean expected=\marg{offending key}\marg{value}}
- This key is executed whenever a key set up using |/.is if| gets called with
- a \meta{value} other than |true| or |false|.
-\end{key}
-
-\begin{key}{/errors/unknown choice value=\marg{offending key}\marg{value}}
- This key is executed whenever a choice is used as a \meta{value} for a key
- set up using the |/.is choice| handler that is not defined.
-\end{key}
-
-\begin{key}{/errors/unknown key=\marg{offending key}\marg{value}}
- This key is executed whenever a key is unknown and no specific |/.unknown|
- handler is found.
-\end{key}
-
-
-\input{pgfmanual-en-pgfkeysfiltered.tex}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeysfiltered.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeysfiltered.tex
deleted file mode 100644
index f0891afd7b..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfkeysfiltered.tex
+++ /dev/null
@@ -1,579 +0,0 @@
-
-\subsection{Key Filtering}
-\begingroup
-
-{\small \emph{An extension by Christian Feuersänger}}
-\vspace{0.4cm}%
-
-\noindent Normally, a call to |\pgfkeys| sets all keys provided in its argument
-list. This is usually what users expect it to do. However, implementations of
-different packages or \pgfname-libraries may need more control over the key
-setting procedure: library~A may want to set its options directly and
-communicate all remaining ones to library~B.
-
-This section describes key filtering methods of \pgfname, including options for
-family groupings. If you merely want to use \pgfname\ (or its libraries), you
-can skip this section. It is addressed to package (or library) authors.
-
-
-\subsubsection{Starting With An Example}
-\label{section-key-filter-example}
-
-Users of |xkeyval| are familiar with the concept of key families: keys belong
-to groups and those keys can be `filtered' out of other options. \pgfname\
-supports family groupings and more abstract key selection mechanism with
-|\pgfkeysfiltered|, a variant of |\pgfkeys|. Suppose we have the example key
-grouping
-
-\begin{codeexample}[setup code,hidden]
-\pgfkeys{
- /my group/A1/.code=(A1:#1),
- /my group/A2/.code=(A2:#1),
- /my group/A3/.code=(A3:#1),
- /my group/B/.code=(B:#1),
- /my group/C/.code=(B:#1),
- /my group/A/.is family,
- /my group/A1/.belongs to family=/my group/A,
- /my group/A2/.belongs to family=/my group/A,
- /my group/A3/.belongs to family=/my group/A,
- /pgf/key filters/active families/.install key filter,
- /my group/A/.activate family,
-}
-\end{codeexample}
-%
-\begin{codeexample}[code only]
-\pgfkeys{
- /my group/A1/.code=(A1:#1),
- /my group/A2/.code=(A2:#1),
- /my group/A3/.code=(A3:#1),
- /my group/B/.code=(B:#1),
- /my group/C/.code=(B:#1),
-}
-\end{codeexample}
-
-\noindent and we want to set options |A1|, |A2| and |A3| only. A call to
-|\pgfkeys| yields
-%
-\begin{codeexample}[]
-\pgfkeys{/my group/A1=a1, /my group/A2=a2, /my group/B=b, /my group/C=c}
-\end{codeexample}
-%
-\noindent because all those command option are processed consecutively.
-
-Now, let's define a family named |A| which contains |A1|, |A2| and |A3| and set
-only family members of |A|. We prepare our key settings with
-%
-\begin{codeexample}[code only]
-\pgfkeys{
- /my group/A/.is family,
- /my group/A1/.belongs to family=/my group/A,
- /my group/A2/.belongs to family=/my group/A,
- /my group/A3/.belongs to family=/my group/A,
-}
-\end{codeexample}
-%
-\noindent and
-%
-\begin{codeexample}[code only]
-\pgfkeys{/pgf/key filters/active families/.install key filter}
-\end{codeexample}
-%
-\noindent After this preparation, we can use |\pgfkeysfiltered| with
-%
-\begin{codeexample}[]
-\pgfkeys{/my group/A/.activate family}
-\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2,
- /my group/B=b, /my group/C=c}
-\end{codeexample}
-%
-\noindent or
-%
-\begin{codeexample}[]
-\pgfkeys{/my group/A/.activate family}
-\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2,
- /my group/B=b, /my group/C=c, /tikz/color=blue, /my group/A3=a3}
-\end{codeexample}
-%
-\noindent to set only keys which belong to an `active' family -- in our case,
-only family~|A| was active, so the remaining options have not been processed.
-The family processing is quite fast and allows an arbitrary number of active
-key families.
-
-Unprocessed options can be collected into a macro (similar to |xkeyval|'s
-|\xkv@rm|), discarded or handled manually. The details of key selection and
-family declaration are described in the following sections.
-
-
-\subsubsection{Setting Filters}
-
-The command |\pgfkeysfiltered| is the main tool to process only selected
-options. It works as follows.
-%
-\begin{command}{\pgfkeysfiltered\marg{key--value-list}}
- Processes all options in exactly the same way as
- |\pgfkeys|\marg{key--value-list}, but a key filter is considered as soon as
- key identification is complete.
-
- The key filter tells |\pgfkeysfiltered| whether it should continue to apply
- the current option (return value is `true') or whether something different
- shall be done (filter returns `false').
-
- There is exactly one key filter in effect, and it is installed by the
- |.install key filter| handler or by |\pgfkeysinstallkeyfilter|.
-
- If the key filter returns `false', a unique key filter handler gets
- control. This handler is installed by the |.install key filter handler|
- method and has access to the key's full name, value and (possibly) path.
-
- Key filtering applies to any (possibly nested) call to |\pgfkeys|,
- |\pgfkeysalso|, |\pgfqkeys| and |\pgfqkeysalso| during the evaluation of
- \marg{key--value-list}. It does \emph{not} apply to routines like
- |\pgfkeyssetvalue| or |\pgfkeysgetvalue|. Furthermore, keys belonging to
- |/errors| are always processed. Key filtering routines can't be nested: you
- can't combine different key filters automatically.
-\end{command}
-
-\begin{command}{\pgfqkeysfiltered\marg{default-path}\marg{key--value-list}}
- A variant of |\pgfkeysfiltered| which uses the `quick' search path setting.
- It is the |\pgfqkeys| variant of |\pgfkeysfiltered|, see the documentation
- for |\pgfqkeys| for more details.
-\end{command}
-
-\begin{command}{\pgfkeysalsofrom\marg{macro}}
- A variant of |\pgfkeysalso| which loads its key list from \marg{macro}.
-
- It is useful in conjunction with the
- |/pgf/key filter handlers/append filtered to=|\meta{macro} handler.
-
- The following example uses the same settings as in the intro
- section~\ref{section-key-filter-example}.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/key filter handlers/append filtered to/.install key filter handler=\remainingoptions}
-\def\remainingoptions{}
-\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2,
- /my group/B=b, /my group/C=c, /tikz/color=blue, /my group/A3=a3}
-
-Remaining: `\remainingoptions'.
-\pgfkeysalsofrom{\remainingoptions}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfkeysalsofiltered\marg{key--value-list}}
- This command works as |\pgfkeysfiltered|, but it does not change the
- current default path. See the documentation of |\pgfkeysalso| for more
- details.
-\end{command}
-
-\begin{command}{\pgfkeysalsofilteredfrom\marg{macro}}
- A variant of |\pgfkeysalsofiltered| which loads its key list from
- \marg{macro}.
-\end{command}
-
-\begin{handler}{{.install key filter}|=|\meta{optional arguments}}
- This handler installs a key filter. A key filter is a command key which
- sets the \TeX-boolean |\ifpgfkeysfiltercontinue|, that means a key with
- existing `|/.@cmd|' suffix. A simple example is a key filter which returns
- always true:
- %
-\begin{codeexample}[code only]
-\pgfkeys{/foo/bar/true key filter/.code={\pgfkeysfiltercontinuetrue}}
-\pgfkeys{/foo/bar/true key filter/.install key filter}
-\end{codeexample}
- %
- If key filters require arguments, they are installed by
- |.install key filter| as well. An example is the |/pgf/key filters/equals|
- handler:
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/key filters/equals/.install key filter={/my group/A1}}
-\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2,
-/my group/B=b, /my group/C=c, /tikz/color=blue, /my group/A3=a3}
-\end{codeexample}
- %
- If a key filter requires more than one argument, you need to provide the
- complete argument list in braces like |{{first}{second}}|.
-
- You can also use |\pgfkeysinstallkeyfilter|\meta{full key}\meta{optional
- arguments}, it has the same effect.
-
- See section~\ref{section-key-writing-filters} for how to write key filters.
-\end{handler}
-
-\begin{handler}{{.install key filter handler}|=|\meta{optional arguments}}
- This handler installs the routine which will be invoked for every
- \emph{unprocessed} option, that means any option for which the key filter
- returned `false'.
-
- The |.install key filter handler| is used in the same way as
- |.install key filter|. There exists a macro version,
- |\pgfkeysinstallkeyfilterhandler|\meta{full key}\meta{optional arguments},
- which has the same effect.
-
- See section~\ref{section-key-writing-filters} for how to write key filter
- handlers.
-\end{handler}
-
-
-\subsubsection{Handlers For Unprocessed Keys}
-
-Each option for which key filters decided to skip them is handed over to a `key
-filter handler'. There are several predefined key filter handlers.
-
-\begin{key}{/pgf/key filter handlers/append filtered to=\marg{macro}}
- Install this filter handler to append any unprocessed options to macro
- \marg{macro}.
- %
-\begin{codeexample}[]
-\pgfkeys{/pgf/key filter handlers/append filtered to/.install key filter handler=\remainingoptions}
-\def\remainingoptions{}
-\pgfkeysfiltered{/my group/A1=a1, /my group/A2=a2,
- /my group/B=b, /my group/C=c, /tikz/color=blue}
-
-Remaining options: `\remainingoptions'.
-\end{codeexample}
- %
- This example uses the same keys as defined in the intro
- section~\ref{section-key-filter-example}.
-\end{key}
-
-\begin{key}{/pgf/key filter handlers/ignore}
- Install this filter handler if you simply want to ignore any unprocessed
- option. This is the default.
-\end{key}
-
-\begin{key}{/pgf/key filter handlers/log}
- This key filter handler writes messages for any unprocessed option to your
- logfile (and terminal).
-\end{key}
-
-
-\subsubsection{Family Support}
-
-\pgfname{} supports a family concept: every option can be associated with (at
-most) one family. Families form loose key groups which are independent of the
-key hierarchy. For example, |/my tree/key1| can belong to family |/tikz|.
-
-It is possible to `activate' or `deactivate' single families. Furthermore, it
-is possible to set only keys which belong to active families using appropriate
-key filter handlers.
-
-The family support is fast: if there are $N$ options in a key--value-list and
-there are $K$ active families, the runtime for |\pgfkeysfiltered| is $O(N+K)$
-(activate every family $O(K)$, check every option $O(N)$, deactivate every
-family $O(K)$).
-
-\begin{handler}{{.is family}}
- Defines a new family. This option has already been described in
- section~\ref{section-is family-handler} on page~\pageref{section-is
- family-handler}.
-\end{handler}
-
-\begin{handler}{{.activate family}}
- Activates a family. The family needs to be defined, otherwise
- |/errors/family unknown| will be raised.
-
- Activation means a \TeX-boolean will be set to |true|, indicating that a
- family should be processed.
-
- You can also use |\pgfkeysactivatefamily|\meta{full path} to get the same
- effect. Furthermore, you can use |\pgfkeysactivatefamilies|\meta{list of
- families}\meta{macro name for de-activation} to activate a list of families
- (see section~\ref{section-key-filter-api}).
-\end{handler}
-
-\begin{handler}{{.deactivate family}}
- Deactivates a family. The family needs to be defined, otherwise
- |/errors/family unknown| will be raised.
-
- You can also use |\pgfkeysdeactivatefamily|\meta{full path} to get the same
- effect.
-\end{handler}
-
-\begin{handler}{{.belongs to family}|=|\marg{family name}}
- Associates the current option with \marg{family name}, which is expected to
- be a full path of a family.
- %
-\begin{codeexample}[code only]
-\pgfkeys{/foo/bar/.is family}
-\pgfkeys{
- /foo/a/.belongs to family=/foo/bar,
- /foo/b/.belongs to family=/foo/bar
-}
-\end{codeexample}
- %
- Each option can have up to one family, |.belongs to family| overwrites any
- old setting.
-\end{handler}
-
-\begin{key}{/pgf/key filters/active families}
- Install this key filter if |\pgfkeysfiltered| should only process activated
- families. If a key does not belong to any family, it is not processed. If a
- key is completely unknown within the default path, the normal `unknown'
- handlers of |\pgfkeys| are invoked.
-\end{key}
-
-\begin{key}{/pgf/key filters/active families or no family=\marg{key filter 1}\marg{key filter 2}}
- This key filter configures |\pgfkeysfiltered| to work as follows.
- %
- \begin{enumerate}
- \item If the current key belongs to a family, set
- |\ifpgfkeysfiltercontinue| to true if and only if its family is
- active.
- \item If the current key does \emph{not} belong to a family, assign
- |\ifpgfkeysfiltercontinue| as result of \marg{key filter 1}.
- \item If the current key is unknown within the default path, assign
- |\ifpgfkeysfiltercontinue| as result of \marg{key filter 2}.
- \end{enumerate}
- %
- The arguments \marg{key filter 1} and \marg{key filter 2} are other key
- filters (possibly with options) and allow fine-grained control over the
- filtering process.
- %
-\begin{codeexample}[code only]
- \pgfkeysinstallkeyfilter
- {/pgf/key filters/active families or no family}
- {{/pgf/key filters/is descendant of=/tikz}% for keys without family
- {/pgf/key filters/false}% for unknown keys
- }%
-\end{codeexample}
- %
- This key filter will return true for any option with active family. If an
- option has no family, the return value is true if and only if it belongs to
- |/tikz|. If the option is unknown, the return value is |false| and unknown
- handlers won't be called.
-\end{key}
-
-\begin{key}{/pgf/key filters/active families or no family DEBUG=\marg{key filter 1}\marg{key filter 2}}
- A variant of |active families or no family| which protocols each action on
- your terminal (log-file).
-\end{key}
-
-\begin{key}{/pgf/key filters/active families and known}
- A fast alias for
-
- |/pgf/key filters/active families or no family=|\par
- \noindent\hskip10pt|{/pgf/keys filters/false}|\par
- \noindent\hskip10pt|{/pgf/keys filters/false}|.
-\end{key}
-%
-\begin{key}{/pgf/key filters/active families or descendants of=\marg{path prefix}}
- A fast alias for
-
- |/pgf/key filters/active families or no family=|\par
- \noindent\hskip10pt|{/pgf/keys filters/is descendant of=|\marg{path prefix}|}|\par
- \noindent\hskip10pt|{/pgf/keys filters/false}|.
-\end{key}
-
-\begin{command}{\pgfkeysactivatefamiliesandfilteroptions\marg{family list}\marg{key--value-list}}
- A simple shortcut macro which activates any family in the comma separated
- \marg{family list}, invokes |\pgfkeysfiltered|\meta{key--value-list} and
- deactivates the families afterwards.
-
- Please note that you will need to install a family key filter, otherwise
- family activation has no effect.
-\end{command}
-%
-\begin{command}{\pgfqkeysactivatefamiliesandfilteroptions\marg{family list}\marg{default path}\marg{key--value-list}}
- The `quick' default path variant of |\pgfkeysactivatefamiliesandfilteroptions|.
-\end{command}
-
-\begin{command}{\pgfkeysactivatesinglefamilyandfilteroptions\marg{family name}\marg{key--value-list}}
- A shortcut macro which activates a single family and invokes |\pgfkeysfiltered|.
-
- Please note that you will need to install a family key filter, otherwise
- family activation has no effect.
-\end{command}
-%
-\begin{command}{\pgfqkeysactivatesinglefamilyandfilteroptions\marg{family name}\marg{default path}\marg{key--value-list}}%
- The `quick' default path variant of |\pgfkeysactivatesinglefamilyandfilteroptions|.
-\end{command}
-
-
-\subsubsection{Other Key Filters}
-
-There are some more key filters which have nothing to do with family handling.
-%
-\begin{key}{/pgf/key filters/is descendant of=\marg{path}}
- Install this key filter to process only options belonging to the key tree
- \meta{path}. It returns true for every key whose key path is equal to
- \meta{path}. It also returns true for any unknown key, that means unknown
- keys are processed using the standard unknown handlers of \pgfname.
- %
-\begin{codeexample}[]
-\pgfkeys{
-/group 1/A/.code={(A:#1)},
-/group 1/foo/bar/B/.code={(B:#1)},
-/group 2/C/.code={(C:#1)},
-/pgf/key filters/is descendant of/.install key filter=/group 1}
-\pgfkeysfiltered{/group 1/A=a,/group 1/foo/bar/B=b,/group 2/C=c}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/key filters/equals=\marg{full key}}
- Install this key filter to process only the fully qualified option
- \marg{full key}. The filter returns true for any unknown key or if the key
- equals \marg{full key}.
- %
-\begin{codeexample}[]
-\pgfkeys{
-/group 1/A/.code={(A:#1)},
-/group 1/B/.code={(B:#1)},
-/pgf/key filters/equals/.install key filter=/group 1/A}
-\pgfqkeysfiltered{/group 1}{A=a,B=b}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/key filters/not=\marg{key filter}}
- This key filter logically inverts the result of \marg{key filter}.
- %
-\begin{codeexample}[]
-\pgfkeys{
-/group 1/A/.code={(A:#1)},
-/group 1/foo/bar/B/.code={(B:#1)},
-/group 2/C/.code={(C:#1)},
-/pgf/key filters/not/.install key filter=
- {/pgf/key filters/is descendant of=/group 1}}
-\pgfkeysfiltered{/group 1/A=a,/group 1/foo/bar/B=b,/group 2/C=c}
-\end{codeexample}
- %
- Please note that unknown keys will be handed to the usual unknown handlers.
-\end{key}
-
-\begin{key}{/pgf/key filters/and=\marg{key filter 1}\marg{key filter 2}}
- This key filter returns true if and only if both, \marg{key filter 1} and
- \marg{key filter 2} return true.
-\end{key}
-
-\begin{key}{/pgf/key filters/or=\marg{key filter 1}\marg{key filter 2}}
- This key filter returns true if one of \marg{key filter 1} and \marg{key
- filter 2} returns true.
-\end{key}
-
-\begin{key}{/pgf/key filters/true}
- This key filter returns always true.
-\end{key}
-
-\begin{key}{/pgf/key filters/false}
- This key filter returns always false (including unknown keys).
-\end{key}
-
-\begin{key}{/pgf/key filters/defined}
- This key filter returns false if the current key is unknown, which avoids
- calling the unknown handlers.
-\end{key}
-
-
-\subsubsection{Programmer Interface}
-\label{section-key-filter-api}
-
-\begin{plainenvironment}{{pgfkeysinterruptkeyfilter}}
- Temporarily disables key filtering inside the environment. If key filtering
- is not active, this has no effect at all.
-
- Please note that no \TeX-group is introduced.
-\end{plainenvironment}
-
-\begin{command}{\pgfkeyssavekeyfilterstateto\marg{macro}}
- Creates \marg{macro} which contains commands to re-activate the current key
- filter and key filter handler. It can be used to temporarily switch the key
- filter.
-\end{command}
-
-\begin{command}{\pgfkeysinstallkeyfilter\marg{full key}\marg{optional arguments}}
- The command
- |\pgfkeysinstallkeyfilter{|\meta{full key}|}{|\meta{optional arguments}|}|
- has the same effect as
- |\pgfkeys{|\meta{full key}|/.install key filter={|\meta{optional arguments}|}}|.
-\end{command}
-
-\begin{command}{\pgfkeysinstallkeyfilterhandler\marg{full key}\marg{optional arguments}}
- The command
- |\pgfkeysinstallkeyfilterhandler{|\meta{full key}|}{|\meta{optional arguments}|}|
- has the same effect as
- |\pgfkeys{|\meta{full key}|/.install key filter handler={|\meta{optional arguments}|}}|.
-\end{command}
-
-\begin{command}{\pgfkeysactivatefamily\marg{family name}}
- Equivalent to |\pgfkeys{|\meta{family name}|/.activate family}|.
-\end{command}
-
-\begin{command}{\pgfkeysdeactivatefamily\marg{family name}}
- Equivalent to |\pgfkeys{|\meta{family name}|/.deactivate family}|.
-\end{command}
-
-\begin{command}{\pgfkeysactivatefamilies\marg{family list}\marg{deactivate macro name}}
- Activates each family in \meta{family list} and creates a macro
- \meta{deactivate macro name} which deactivates each family in \meta{family
- list}.
- %
-\begin{codeexample}[code only]
-\pgfkeysactivatefamilies{/family 1,/family 2,/family 3}{\deactivatename}
-\pgfkeysfiltered{foo,bar}
-\deactivatename
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfkeysiffamilydefined\marg{family}\marg{true case}\marg{false case}}%
- Checks whether the full key \meta{family} is a family and executes either
- \meta{true case} or \meta{false case}.
-\end{command}
-
-\begin{command}{\pgfkeysisfamilyactive\marg{family}}
- Sets the \TeX-boolean |\ifpgfkeysfiltercontinue| to whether \meta{family}
- is active or not.
-\end{command}
-
-\begin{command}{\pgfkeysgetfamily\marg{full key}\marg{resultmacro}}
- Returns the family associated to a \meta{full key} into macro
- \meta{resultmacro}.
-\end{command}
-
-\begin{command}{\pgfkeyssetfamily\marg{full key}\marg{family}}
- The command |\pgfkeyssetfamily|\marg{full key}\marg{family} has the same
- effect as |\pgfkeys{|\meta{full key}|/.belongs to family=|\marg{family}|}|.
-\end{command}
-
-
-\subsubsection{Defining Own Filters Or Filter Handlers}
-\label{section-key-writing-filters}
-
-During |\pgfkeysfiltered|, the key filter code will be invoked. At this time,
-the full key path including key name is available as |\pgfkeyscurrentkey|, the
-key name before default paths have been considered as |\pgfkeyscurrentkeyRAW|
-and the values as |\pgfkeyscurrentvalue|.
-
-Furthermore, the macro |\pgfkeyscasenumber| contains the current key's type as
-an integer:
-%
-\begin{itemize}
- \item[\meta{1}] The key is a command key (i.e.\ |.../.@cmd| exists).
- \item[\meta{2}] The key contains its value directly.
- \item[\meta{3}] The key is handled (for example it is |.code| or |.cd|).
-
- In this case, the macros |\pgfkeyscurrentname| and
- |\pgfkeyscurrentpath| are set to the handlers name and path,
- respectively. Invoke |\pgfkeyssplitpath{}| to extract these values for
- non-handled keys.
- \item[\meta{0}] The key is unknown.
-\end{itemize}
-%
-Any key filter or key filter handler can access these variables. Key filters
-are expected to set the \TeX-boolean |\ifpgfkeysfiltercontinue| to whether the
-current key shall be processed or not.
-
-\begin{command}{\pgfkeysevalkeyfilterwith\marg{full key}=\marg{filter arguments}}
- Evaluates a fully qualified key filter \meta{full key} with argument(s)
- \meta{filter arguments}.
- %
-\begin{codeexample}[code only]
-\pgfkeysevalkeyfilterwith{/pgf/key filters/equals=/tikz}
-\end{codeexample}
- %
-\end{command}
-
-\endgroup
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-animations.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-animations.tex
deleted file mode 100644
index 2f115ca1b3..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-animations.tex
+++ /dev/null
@@ -1,1654 +0,0 @@
-% 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{Animation System Layer}
-\label{section-pgfsys-anim}
-
-\begin{codeexample}[setup code,hidden]
-\makeatletter
-
-\def\animationexample#1#2#3{%
- \tikz[fill=blue!25, draw=blue, ultra thick] {
- \pgfidrefnextuse{\objid}{#1}
- \pgfsysanimkeywhom{\objid}{#2}
- \pgfidrefnextuse{\nodeid}{node}
- \pgfsysanimkeyevent{\nodeid}{}{click}{}{begin}
- #3
- \node [font=\footnotesize, circle, fill, draw, align=center]
- (node) {Click \\ here};
- }%
-}
-\end{codeexample}
-
-In conjunction with the right output format (namely \textsc{svg}), you can
-specify that certain parts of you graphics can be animated. For this, there are
-a number of commands that cover, currently, what \textsc{svg 1.1} can do
-regarding animations. For a detailed introduction to animations, please see
-Section~\ref{section-base-animations}; the current section assumes that you are
-familiar with the concepts explained there.
-
-The animation system consists of two layer itself: Commands starting with
-|\pgfsys@anim...| and commands starting with |\pgfsysanim|. These work as
-follows:
-%
-\begin{enumerate}
- \item The commands starting with |\pgfsys@anim...| insert the actual
- animation commands into the output stream. A driver must implement
- these commands.
- \item The command starting with |\pgfsysanim...| provide an. These
- commands, which are the ones that should be called by higher layers,
- implement the snapshot mechanism: When the command
- |\pgfsysanimsnapshot| is used, the |\pgfsysanim...| commands do
- \emph{not} call the |\pgfsys@anim...| commands but, instead, insert
- non-animation commands to show the values of the attributes at the
- snapshot's time. To use this abstraction layer, you have to load the
- file |pgfsysanimations.code.tex|, which is not loaded by default (but
- is loaded by the \pgfname\ module |animations|).
-\end{enumerate}
-
-The bottom line is that if you wish to implement a new driver, you need to
-implement the |\pgfsys@anim...| commands, if you use the animation layer, you
-call the |\pgfsysanim...| commands.
-
-
-\subsection{Animations and Snapshots}
-
-To add an animation to a graphic, use the following command (as described
-above, the first command is the one you actually call, the second is the one a
-driver implements):
-
-\begin{command}{\pgfsysanimate\marg{attribute}}
-\end{command}
-
-\begin{command}{\pgfsys@animate\marg{attribute}}
- The system layer animation subsystem follows the following philosophy: An
- animation always concerns an \emph{attribute} of a \emph{graphic object}. A
- \emph{timeline} specifies how the attribute changes its value over time.
- Finally, a set of \emph{keys} configures the animation as a whole like
- whether the timeline repeats or a event that triggers the start of the
- animation. The four parts of an animation, namely the \emph{attribute}, the
- \emph{graphic object}, the \emph{timeline}, and the \emph{keys}, are
- specified in different ways:
- %
- \begin{enumerate}
- \item You choose the \emph{attribute} using the system layer command
- |\pgfsysanimate|.
- \item The \emph{graphic object} whose attribute is to be animated is
- \emph{always} specified by naming the ID of the graphic object
- \emph{before} this object is created, see
- Section~\ref{section-sys-id}. (However, in the context of
- \tikzname, it suffices that the animation is given in the object's
- options since these are executed before the actual object is
- created).
- \item The \emph{timeline} is specified using the commands
- |\pgfsysanimkeytime|, which specifies a time in seconds, and
- |\pgfsys@animation@val...|, which specify a value at this
- particular time. The timeline specifies for a sequence of times the
- values the attribute will have at these times. In between these
- \emph{key times,} the value is interpolated.
- \item The \emph{animation keys} are specified by commands starting
- |\pgfsys@animation@...| and have the following effect: They set
- some property (like, say, whether the animation repeats or whether
- its effect is additive) to a given value \emph{for the current
- \TeX\ scope,} but do not create any animations. Rather, when
- |\pgfsysanimate| is called, a snapshot of the current values of all
- animation keys is taken and added to this animation of the
- attribute.
-
- When you set an animation key to a value, this will replace the
- value previously stored for the key (all keys are empty by default
- at the beginning).
-
- Note that animation keys are local to \TeX\ scopes, not graphics
- scopes; indeed, they have little to do with the settings of the
- graphics scope other than the fact that a graphic scope is also a
- \TeX\ scope and thereby influence the values of these keys.
- \end{enumerate}
-
- A typical example of how all of this works is the following:
- %
-\begin{codeexample}[code only]
-\pgfsysanimkeyrepeatindefinite % Both of the following animations
- % repeat indefinitely
-{
- \pgfsysanimkeywhom{\someid}{}% The id of a later object
- \pgfsysanimkeyevent{}{}{click}{0}{begin}% Begin on a click ...
- \pgfsysanimkeytime{5}{1}{1}{0}{0} % Timeline starts after 5s
- \pgfsysanimvalscalar{0} % With a value of 0
- \pgfsysanimkeytime{8}{1}{1}{0}{0} % Timeline ends after 8s
- \pgfsysanimvalscalar{0.9} % With a value of 0.9
- \pgfsysanimate{fillopacity}% ... and the attribute is the fill opacity
-}
-{
- \pgfsysanimkeywhom{\someid}{}% The id of a later object
- \pgfsysanimkeyoffset{0}{begin}% Begin right away ...
- \pgfsysanimkeytime{1}{1}{1}{0}{0} % Timeline starts after 1s
- \pgfsysanimvalcurrent % With the current value
- \pgfsysanimkeytime{5}{1}{1}{0}{0} % Timeline ends after 5s
- \pgfsysanimvaldimension{5pt} % With a value of 5pt
- \pgfsysanimate{linewidth}% ... and the attribute is the line width
-}
-\end{codeexample}
- %
- As a real-life example, consider the following definitions, which will be
- used in many examples in the rest of this section: Both take three
- parameters: The \pgfname/\tikzname\ name of a to-be animated object, a type
- (relevant for objects that have subtypes or parts), and some code for
- triggering the actual animation. The animation will always start when the
- button is clicked. The second macro sets up things in such a way that the
- animation will last two seconds, while the first leaves the timing open.
- %
-\begin{codeexample}[code only]
-\def\animationexample#1#2#3{
- \tikz[fill=blue!25, draw=blue, ultra thick] {
- \pgfidrefnextuse{\objid}{#1}
- \pgfsysanimkeywhom{\objid}{#2}
- \pgfidrefnextuse{\nodeid}{node}
- \pgfsysanimkeyevent{\nodeid}{}{click}{}{begin}
- #3
- \node [font=\scriptsize, circle, fill, draw, align=center]
- (node) {Click \\ here};
- }
-}
-\end{codeexample}
- %
- Now the example, where the circle will disappear, when clicked:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2}]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{1}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}
- \pgfsysanimate{opacity}
-}
-\end{codeexample}
- %
-\end{command}
-
-The ``opposite'' of |\pgfsysanimate| is the following command:
-
-\begin{command}{\pgfsysanimsnapshot\marg{time}}
- Use this command in a scope prior to calling any other commands documented
- in this section concerning the configuration of animations. In this case,
- all uses of |\pgfsysanimate| inside the \TeX\ scope no longer insert an
- animation into the output file. Instead, a ``snapshot'' is inserted of what
- the animation ``would like at time \meta{time}''. For instance, if an
- animation inserts a movement of an object by 4cm over a time of 2s and you
- take a snapshot with $\meta{time} = 2\mathrm s$, you get a picture in which
- the object is moved by 1cm.
-
- A lot of care has been taken to make the output produced by the snapshot be
- as close as possible as what the animation really would look like at time
- \meta{time}, but note the following restrictions:
- %
- \begin{enumerate}
- \item Interactive events of all kinds (like |click| or |mouseover|)
- make little sense for snapshots, which are created once and for all
- during the typesetting of the document. For this reason, all events
- are ignored for snapshots (even sync bases, and |begin| and |end|
- events, which might make some sense also in a snapshot setting).
-
- However, there is one command which helps you with ``simulating''
- the effect of events:
- %
- \begin{command}{\pgfsysanimkeysnapshotstart\marg{time offset}}
- This command specifies that for the current animation the
- ``moment |0s|'' of the timeline is at \meta{time offset}. Thus,
- it works like |\pgfsysanimkeyoffset|, only the offset is now
- solely for the snapshot timeline. It has no effect on the
- actual animation.
- \end{command}
- %
- \item The command |\pgfsysanimvalcurrent| cannot be used with snapshots
- since \pgfname\ has no chance of computing the correct current
- value. You always have to specify the start value explicitly.
- \item The computation of time splines (entry and exit splines) and the
- accumulation of values after a large number of repeats may not be
- numerically stable.
- \end{enumerate}
- %
-\begin{codeexample}[width=5cm,preamble={\usetikzlibrary{animations}}]
-\foreach \t in {0.5,1,1.5,2} {
- \pgfsysanimsnapshot{\t}
- \tikz {
- \pgfidrefnextuse{\objid}{node}
- \pgfsysanimkeywhom{\objid}{}
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{1}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}
- \pgfsysanimate{opacity}
- \node (node) [draw = blue, very thick, fill=blue!20, circle] {Hi};
- }
-}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsysanimsnapshotafter\marg{time}}
- Works like the previous command, only the ``moment'' that \meta{time}
- refers to is conceptually $\meta{time} + \epsilon$: When timeline specifies
- several values for \meta{time}, this command will select the last value at
- \meta{time}, while |\pgfsnapshot| will select the first value at
- \meta{time}. Similarly, when a timeline ends at \meta{time}, |\pgfsnapshot|
- will select the last value of the timeline while |\pgfsnapshotafter| will
- not apply the animation any more.
-\end{command}
-
-
-\subsection{Commands for Animating an Attribute: Color, Opacity, Visibility, Staging}
-
-The commands from this and the next sections specify that some attribute should
-be animated. We start with rather basic animation attributes for color,
-visibility, and opacity.
-
-\begin{sysanimateattribute}{opacity}
- Adds an animation of the opacity to the graphic object specified using
- |\pgfsysanimkeywhom|. If the driver supports this, this is a bit different
- from animating the fill and stroke opacities individually: Paths are
- treated as transparency groups for this key. Typically, ``this is what you
- want''.
-
- Specify values with |\pgfsysanimvalscalar|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{1}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}
- \pgfsysanimate{opacity}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{fillopacity}
- Adds an animation of only the opacity of fill operations.
-
- Specify values with |\pgfsysanimvalscalar|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{1}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}
- \pgfsysanimate{fillopacity}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{strokeopacity}
- Adds an animation of only the opacity of draw (stroke) operations.
-
- Specify values with |\pgfsysanimvalscalar|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{1}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}
- \pgfsysanimate{strokeopacity}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{visibility}
- Adds an animation of the ``visibility''.
-
- Specify values with |\pgfsysanimvaltext|. However, only two values are
- allowed: |visible| and |hidden|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={-1,0,1,2,3},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltext{hidden}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltext{hidden}
- \pgfsysanimate{visibility}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{strokecolor}
- Adds an animation of the stroke color.
-
- Specify values with |\pgfsysanimvalcolorrgb| and friends.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalcolorrgb{0}{0}{0}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalcolorrgb{1}{0}{0}
- \pgfsysanimate{strokecolor}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{fillcolor}
- Adds an animation of the fill color.
-
- Specify values with |\pgfsysanimvalcolorrgb| and friends.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalcolorrgb{0}{0}{0}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalcolorrgb{1}{0}{0}
- \pgfsysanimate{fillcolor}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-
-\subsection{Commands for Animating an Attribute: Paths and Their Rendering}
-
-The following attributes influence paths and how they are rendered.
-
-\begin{sysanimateattribute}{path}
- Adds an animation of the path itself. That means that the path will morph
- its form from one path to another. When morphing a path, all ``values'',
- which are the paths, must consist of the \emph{exact same} path
- construction commands; they may only differ with respect to the numbers
- used in these descriptions.
-
- Specify values with |\pgfsysanimvalpath|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
- animation bb={(0.9,-0.1)rectangle(2.1,1.1)},
-]
-\animationexample{my path}{path}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalpath{\pgfsys@moveto{1cm}{0cm}%
- \pgfsys@lineto{1cm}{1cm}%
- \pgfsys@lineto{2cm}{0cm}}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalpath{\pgfsys@moveto{1cm}{1cm}%
- \pgfsys@lineto{2cm}{1cm}%
- \pgfsys@lineto{1cm}{0cm}}
- \pgfsysanimate{path}
- \filldraw [ultra thick,draw=blue,fill=blue!20, name=my path]
- (1,0) -- (1,1) -- (2,0); }
-\end{codeexample}
-
- You can attach arrow tips to paths that are animated and these arrow tips
- will correctly ``rotate and move along'' with the path's end points
- \emph{if} you take the following points into considerations:
- %
- \begin{itemize}
- \item Arrow tips that ``rotate and move along'' with a path must be
- specified using a special animation command, see below. The normal
- arrow tips added to a path would \emph{not} be animated
- automatically and, indeed, if you add arrow tips to a path using
- |\pgfsetarrows| and then animate the path, you will get an error
- message.
- \item Internally, the arrow tips that ``rotate and move along'' are
- drawn using so-called \emph{markers}. These are little graphic
- objects that can be added to the start and end of paths and that
- are automatically rotated and move along with the path.
-
- In principle, the rendering rules used by \textsc{svg} for markers
- are the same as for normal arrow tips: The markers are rotated and
- moved so that the point along a tangent of the path at the start or
- end of the path. However, when it comes to special cases such as a
- path with multiple segments, a path with degenerate segments, a
- closed path, and so on, the rules used by for instance \textsc{svg}
- may differ from the placement that \pgfname\ will compute.
-
- Thus, it is best to add arrow tips only to ``normal'' paths
- consisting of a single open path segment whose ends can be
- shortened a bit without causing degeneration.
- \item When an arrow tip is added to a path, the path must typically be
- shortened a bit so that the \emph{tip} of the arrow ends where the
- path would usually end. This shortening is not done by the system
- layer for to-be-animated paths; you must compute and then animate
- these shortened paths yourself. (However, the basic layer animation
- module will do this for you, so you only have to worry about this
- when you use the system layer directly.)
- \end{itemize}
-
- Let us now have a look at how we add arrow tip markers:
- %
- \begin{command}{\pgfsysanimkeytipmarkers\marg{start marker}\marg{end marker}}
- \end{command}
- %
- \begin{command}{\pgfsys@animation@tip@markers\marg{start marker}\marg{end marker}}
- This command specifies that during a path animation the two markers
- provided as parameters should be added (and rotated and moved along
- with the path) at the start and end. The \meta{start marker} must
- either be empty (in which case no marker is added at the start) or it
- must be a macro storing a value returned by the command
- |\pgfsys@marker@declare|. In this case, the marker declared symbol will
- be added to the start during the animation. The same situation applies
- to the end of the path.
-
- As pointed out earlier, only arrow tips / markers added to paths using
- this command will be animated along with the path. In particular, you
- should \emph{not} add arrow tips to to-be-animated paths using
- |\pgfsetarrow|. However, when you use a base value
- (|\pgfsys@animation@base|) to set a path, the arrow tips will also be
- added to this base path.
-
- To sum up, the ``correct'' way of adding arrow tips to a path that is
- animated is to proceed as follows:
- %
- \begin{enumerate}
- \item You specify arrow tips for a path using this command.
- \item You specify times and values of the to-be-animated path,
- shortened as necessary to accommodate the length of the arrow
- tips.
- \item You specify the first (or, possibly, some other) value in the
- time--value sequence as a base value.
- \item You create a path animation that applies to a future path.
- \item You create this future path as an empty path without arrow
- tips and draw it. Because of the setting of the base value,
- instead of the empty path the base path will be used as the
- ``real'' path and the animation's arrow tips will be added as
- arrow tips.
- \end{enumerate}
-
- When you have more than one animation for a given path, these different
- animations may use different arrow tips / markers. This allows you to
- animate (change) which arrow tip is used on a path over time.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
- animation bb={(0.7,-0.3)rectangle(2.3,1.3)},
-]
-% Declare a marker:
-\pgfsys@marker@declare\mymarker{%
- \pgfscope%
- \pgfsetcolor{red!75}%
- \pgfpathmoveto{\pgfpoint{0pt}{5pt}}\pgfpathlineto{\pgfpoint{8pt}{0pt}}%
- \pgfpathlineto{\pgfpoint{0pt}{0pt}}\pgfpathclose%
- \pgfusepathqfill%
- \endpgfscope%
- \pgfpathmoveto{\pgfpoint{0pt}{5pt}}\pgfpathlineto{\pgfpoint{8pt}{0pt}}%
- \pgfpathlineto{\pgfpoint{0pt}{-5pt}}\pgfpathclose%
- \pgfusepathqstroke%
-}%
-\animationexample{my path}{path}{
- \pgfsysanimkeytipmarkers{\mymarker}{\mymarker}
- \pgfsysanimkeybase
- \pgfsysanimvalpath{\pgfsys@moveto{1cm}{0cm}%
- \pgfsys@lineto{1cm}{1cm}%
- \pgfsys@lineto{2cm}{0cm}}
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalpath{\pgfsys@moveto{1cm}{0cm}%
- \pgfsys@lineto{1cm}{1cm}%
- \pgfsys@lineto{2cm}{0cm}}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalpath{\pgfsys@moveto{1cm}{1cm}%
- \pgfsys@lineto{2cm}{1cm}%
- \pgfsys@lineto{1cm}{0cm}}
- \pgfsysanimate{path}
- \filldraw [ultra thick,draw=blue,fill=blue!20, name=my path];
- \path (1,0) (2,1);}
-\end{codeexample}
- \end{command}
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{linewidth}
- Adds an animation of the line width.
-
- Specify values with |\pgfsysanimvaldimension|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaldimension{1pt}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaldimension{10pt}
- \pgfsysanimate{linewidth}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{dash}
- Adds an animation of the dash phase and pattern (like |\pgfsys@setdash|).
-
- Specify values with |\pgfsysanimvaldash|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaldash{1pt,10pt}{0pt}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaldash{10pt,3pt}{0pt}
- \pgfsysanimate{dash}
-}
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaldash{1cm,1pt}{0pt}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaldash{1cm,1pt}{1cm}
- \pgfsysanimate{dash}
-}
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaldash{3pt,1pt}{0pt}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaldash{1pt,3pt}{10pt}
- \pgfsysanimate{dash}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-
-\subsection{Commands for Animating an Attribute: Transformations and Views}
-
-The commands in this section allow you to animate the canvas transformation
-matrix of a scope. However, there is one command that needs to be explained
-first.
-
-\begin{command}{\pgfsysanimkeycanvastransform\marg{pre}\marg{post}}
-\end{command}
-%
-\begin{command}{\pgfsys@animation@canvas@transform\marg{pre}\marg{post}}
- In order to animate the canvas, you specify that, for instance, the canvas
- should be shifted over, say, one second by 2cm from left to right. In order
- to specify this, you specify that an additional shift should be added to
- the canvas transformation matrix that starts out as $(0,0)$ and ends at
- $(2\,\mathrm{cm},0)$. However, it is not immediately clear what ``to the
- right'' or $(2\,\mathrm{cm},0)$ actually means: ``Right'' relative to the
- paper? ``Right'' relative to the coordinate system at the point when the
- animation is created? ``Right'' relative to the object's local coordinate
- system?
-
- Using this command you can specify the coordinate system relative to which
- all canvas animations are specified. In detail, when you add an animation
- $a$ of the canvas of an object foo, the following happens:
- %
- \begin{enumerate}
- \item We start with the canvas transformation matrix that is installed
- when the object starts. More precisely, this is the canvas
- transformation matrix that is in force when the command
- |\pgfsys@begin@idscope| is called for the object. The canvas
- transformation matrix that is in force when the animation is
- created (which is typically ``way before'' the object is created
- and may even be in a totally different graphics scope) is
- irrelevant for the animation.
- \item Now, when the object is created, the code \meta{pre} is executed.
- It should call |\pgfsys@transformcm| at most once. This canvas
- transformation is added to the object's canvas transformation.
- \item Now, the animation $a$ of the canvas is relative to the resulting
- canvas transformation. That means, when the animation shifts the
- object ``to the right'' the animation will actually be along the
- current direction of ``right'' in the canvas transformation
- resulting from the two transformations above.
- \item Finally, at the point of creation of the to-be-animation object
- the code \meta{post} is executed. Again, the code should call
- |\pgfsys@transformcm| at most once. The resulting transformation is
- also added to the object's canvas transformation, but does
- \emph{not} influence the animation.
- \end{enumerate}
-
- The net effect of the above is that, normally, you use the \meta{pre} code
- to setup a transformation matrix relative to which you wish to perform your
- animation and, normally, you use \meta{post} to undo this transformation
- (using the inverted matrix) to ensure that when no animation is in force,
- the object is placed at the same position as if no animation were used.
-
- Let us now have a look at some examples. We use the following macro, which
- takes a pre and a post code and animates a red ball over 1cm to the right
- in two seconds and rotates the blue ball over 90$^\circ$ around the origin.
- The ball is placed at $(1,0)$.
- %
-\begin{codeexample}[code only,setup code]
-\def\animationcanvasexample#1#2{%
- \animationexample{ball}{}{%
- \pgfsysanimkeycanvastransform{#1}{#2}%
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}%
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{1cm}{0cm}%
- \pgfsysanimate{translate}
- \fill [ball color=red,name=ball] (1,0) circle [radius=3mm]; }
- \animationexample{ball}{}{%
- \pgfsysanimkeycanvastransform{#1}{#2}%
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}%
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{90}%
- \pgfsysanimate{rotate}
- \fill [ball color=blue,name=ball] (1,0) circle [radius=3mm]; } }
-\end{codeexample}
- %
-% TODOsp: codeexamples: this definition is needed for the next 4 `codeexample`s
-% but because of the hash sign it can't simply be added `pre`
-\def\animationcanvasexample#1#2{%
- \animationexample{ball}{}{%
- \pgfsysanimkeycanvastransform{#1}{#2}%
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}%
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{1cm}{0cm}%
- \pgfsysanimate{translate}
- \fill [ball color=red,name=ball] (1,0) circle [radius=3mm]; }
- \animationexample{ball}{}{%
- \pgfsysanimkeycanvastransform{#1}{#2}%
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}%
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{90}%
- \pgfsysanimate{rotate}
- \fill [ball color=blue,name=ball] (1,0) circle [radius=3mm]; } }
-
-\begin{codeexample}[
- width=9.9cm,
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationcanvasexample
-{}
-{}
-\end{codeexample}
- %
-\begin{codeexample}[
- width=9.9cm,
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationcanvasexample
-{\pgfsys@transformshift{10mm}{0mm}}
-{\pgfsys@transformshift{-10mm}{0mm}}
-\end{codeexample}
- %
-\begin{codeexample}[
- width=9.9cm,
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationcanvasexample
-{\pgfsys@transformcm{0.5}{0.5}{-0.5}{0.5}
- {0pt}{0pt}}
-{}
-\end{codeexample}
- %
-\begin{codeexample}[
- width=9.9cm,
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationcanvasexample
-{\pgfsys@transformcm{0.5}{0.5}{-0.5}{0.5}
- {0pt}{0pt}}
-{\pgfsys@transformcm{1}{-1}{1}{1}
- {0pt}{0pt}}
-\end{codeexample}
- %
-\end{command}
-
-\begin{sysanimateattribute}{translate}
- Adds an (additional) translate animation. Effectively, this causes the
- group to be shifted to different positions.
-
- Specify values with |\pgfsysanimvaltranslate|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}%
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{5mm}{-1cm}
- \pgfsysanimate{translate}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{scale}
- Adds an animation of the scaling relative to the origin. This causes a
- scaling of the canvas, including fonts and line widths.
-
- Specify values with |\pgfsysanimvalscale|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscale{1}{1}%
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscale{0.5}{2}
- \pgfsysanimate{scale}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{rotate}
- Adds a rotation animation around the origin.
-
- Specify values with |\pgfsysanimvalscalar|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
- ]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}%
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{90}
- \pgfsysanimate{rotate}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{skewx}
- Adds an animation of a skewing of the canvas along the $x$-axis. Unlike the
- |slant| options of \tikzname, the skew is given in degrees.
-
- Specify values with |\pgfsysanimvalscalar|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}%
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{45}
- \pgfsysanimate{skewx}
-}
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{skewy}
- Adds an animation of a skewing of the canvas along the $y$-axis.
-
- Specify values with |\pgfsysanimvalscalar|.
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{motion}
- Works a bit like |\pgfsysanimvaltranslate|: It also adds an animated shift
- transformation of the canvas. However, instead of specifying some shift
- coordinates as values, you now specify a whole path (which may include
- curves). The effect is that an animated translate transformation for the
- different points on this path gets installed. Furthermore, if you use
- |\pgfsysanimkeyrotatealong|, an additional adaptive rotation transformation
- will be added so that the animated graphic scope ``points along'' the path.
-
- You specify the path along which you wish to move objects along using
- |\pgfsysanimkeymovealong|. You use the timeline to specify how far the
- object gets moved along this path using scalar values where |0| is the
- beginning of the path and |1| is the end. Thus, setting the timeline to the
- scalar value of |0| at time $t_0$ and to |1| at time $t_1$ will cause the
- object o move along the complete path between times $t_0$ and $t_1$.
-
- Specify values with |\pgfsysanimvalscalar|.
-
- \begin{command}{\pgfsysanimkeymovealong\marg{path}}
- \end{command}
- %
- \begin{command}{\pgfsys@animation@movealong\marg{path}}
- Defines the \meta{path} along which the motion will occur. It will
- simply be executed and must call |\pgfsys@lineto| and similar
- path-construction commands, but should not call other commands.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
- render instead={
-\animationexample{node}{}{
- \pgfsysanimkeymovealong{
- \pgfsyssoftpath@movetotoken{0pt}{0pt}
- \pgfsyssoftpath@linetotoken{0pt}{-5mm}
- \pgfsyssoftpath@curvetosupportatoken{0pt}{-1cm}%
- \pgfsyssoftpath@curvetosupportbtoken{0pt}{-1cm}%
- \pgfsyssoftpath@curvetotoken{-5mm}{-1cm} }
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{1}
- \pgfsysanimate{motion}
-}
- }]
-\animationexample{node}{}{
- \pgfsysanimkeymovealong{
- \pgfsyssoftpath@movetotoken{0pt}{0pt}
- \pgfsyssoftpath@linetotoken{0pt}{-5mm}
- \pgfsyssoftpath@curvetosupportatoken{0pt}{-1cm}%
- \pgfsyssoftpath@curvetosupportbtoken{0pt}{-1cm}%
- \pgfsyssoftpath@curvetotoken{-5mm}{-1cm} }
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{1}
- \pgfsysanimate{motion}
-}
-\end{codeexample}
- \end{command}
-
- \begin{command}{\pgfsysanimkeynorotatealong}
- \end{command}
- %
- \begin{command}{\pgfsys@animation@norotatealong}
- Indicates that no additional rotation should be added during the
- movement. This is the default.
- \end{command}
-
- \begin{command}{\pgfsysanimkeyrotatealong}
- \end{command}
- %
- \begin{command}{\pgfsys@animation@rotatealong}
- Indicates that the to-be-animated group should be rotated automatically
- so that it points along the path as time progresses. This option is
- only applicable to motion animations.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
- render instead={
-\animationexample{node}{}{
- \pgfsysanimkeyrotatealong
- \pgfsysanimkeymovealong{
- \pgfsyssoftpath@movetotoken{0pt}{0pt}
- \pgfsyssoftpath@linetotoken{0pt}{-5mm}
- \pgfsyssoftpath@curvetosupportatoken{0pt}{-1cm}%
- \pgfsyssoftpath@curvetosupportbtoken{0pt}{-1cm}%
- \pgfsyssoftpath@curvetotoken{-5mm}{-1cm} }
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{1}
- \pgfsysanimate{motion}
-}}]
-\animationexample{node}{}{
- \pgfsysanimkeyrotatealong
- \pgfsysanimkeymovealong{%
- \pgfsyssoftpath@movetotoken{0pt}{0pt}%
- \pgfsyssoftpath@linetotoken{0pt}{-5mm}%
- \pgfsyssoftpath@curvetosupportatoken{0pt}{-1cm}%
- \pgfsyssoftpath@curvetosupportbtoken{0pt}{-1cm}%
- \pgfsyssoftpath@curvetotoken{-5mm}{-1cm}}
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalscalar{0}%
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalscalar{1}
- \pgfsysanimate{motion}
-}
-\end{codeexample}
- \end{command}
-\end{sysanimateattribute}
-
-\begin{sysanimateattribute}{viewbox}
- Adds an animation of the view box. The graphic scope to which this
- animation is added must have been created using |\pgfsys@viewboxmeet| or
- |\pgfsys@viewboxslice|; adding it to other scopes has no effect. Note that
- this command does \emph{not} change or animate the scope's transformation
- matrix -- it only animates the ``what we see through the view box''.
-
- Specify values with |\pgfsysanimvalviewbox|.
- %
-\begin{codeexample}[
- width=5cm,
- preamble={\usetikzlibrary{animations,views}},
- animation list={0.5,1,1.5,2},
- animation bb={(0.9,-2.1) rectangle (3.1,2.1)},
-]
-\animationexample{my view}{view}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvalviewbox{-10mm}{-20mm}{10mm}{20mm}%
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvalviewbox{15mm}{-15mm}{27mm}{8mm}%
- \pgfsysanimate{viewbox}
- \scoped [xshift=2cm] {
- \draw [red] (-1,-2) rectangle (1,2) node [font=\scriptsize,
- below left, align=right] {original\\ view\\ box};
- \scoped [meet={(-1,-2) (1,2)}, name=my view] {
- \draw (-5mm,-15mm) rectangle (7mm,8mm)
- node [font=\scriptsize, align=right, below left]
- {target\\ view\\ box}; ;
- \filldraw (0,0) circle [radius=3mm];
-} } }
-\end{codeexample}
- %
-\end{sysanimateattribute}
-
-
-\subsection{Commands for Specifying the Target Object}
-
-\begin{command}{\pgfsysanimkeywhom\marg{id}\marg{type}}
-\end{command}
-%
-\begin{command}{\pgfsys@animation@whom\marg{id}\marg{type}}
- Sets the target of the animation. The \marg{id} must previously have been
- created using |\pgfsys@new@id|, \marg{type} must be a type (the empty type
- is also allowed). See Section~\ref{section-sys-id} for details on ids and
- types.
-\end{command}
-
-
-\subsection{Commands for Specifying Timelines: Specifying Times}
-
-Animations are specified using \emph{timelines}, which are functions mapping
-times to values for these times. The functions are cubic splines, which are
-specified using time--value pairs plus control points.
-
-In order to specify a time--value pair, you first use the command
-|\pgfsysanimkeytime| to specify a time. Next, you use |\pgfsysanimval...| to
-specify a value, which adds the time--value pair to the timeline. Note that the
-times must be given in non-decreasing order. Between time--value pairs, the
-values are interpolated using a spline.
-
-The first and last times of the timeline are a bit special: The timeline starts
-on the first time and the duration of the timeline is the difference between
-the first and last time. ``Starting'' on the start time actually means that any
-beginnings (see the commands for specifying beginnings and endings) get as
-offset the start time; similarly end times are offset by this value.
-
-\begin{command}{\pgfsysanimkeytime\marg{time}\marg{entry spline
- control x}\marg{entry spline control y}\marg{exit spline
- control x}\marg{exit spline control y}%
-}
-\end{command}
-\begin{command}{\pgfsys@animation@time\marg{time}\marg{entry spline
- control x}\marg{entry spline control y}\marg{exit spline
- control x}\marg{exit spline control y}%
-}
- The \meta{time} is a number representing seconds (so |0.5| means 500\,ms).
-
- The spline between a time--value pair and the next is specified using the
- four parameters following the time. The first two of these specify the
- second control point of the interval preceding the time--value pair (called
- the ``entry'' control point), the last two parameters specify the first
- control point of the interval following the pair (called the ``exit''
- control point). Consider for instance, the following calls:
- %
-\begin{codeexample}[code only]
-\pgfsysanimkeytime{10}{0.1}{0.2}{0.3}{0.4}
-\pgfsysanimvalscalar{100}
-\pgfsysanimkeytime{15}{0.5}{0.6}{0.7}{0.8}
-\pgfsysanimvalscalar{200}
-\end{codeexample}
- %
- This will create (at least) the time interval $[10\,\mathrm s,15\,\mathrm
- s]$ and the control points for this interval will be $(0.3,0.4)$ and
- $(0.5,0.6)$.
-
- Control points are specified in a different ``coordinate'' system from the
- time--value pairs themselves: While the time--value pairs are specified
- using a number representing seconds and a value using some special
- commands, the control points are specified as numbers between $0$ and $1$,
- each time representing a fraction of the time interval or the value
- interval. In the example, the time interval is $[10\,\mathrm s,15\,\mathrm
- s]$ and the value interval is $[100,200]$. This means that a control point
- of $(0.3,0.4)$ actually refers to the time--value $(11.5\,\mathrm s,140)$.
- The ``time--value curve'' in the interval thus ``\texttt{(10s,100) ..
- controls (11.5s,140) and (12.5s,160) .. (15s,200)}''.
-
- Note that by setting the control points always to $(1,1)$ and $(0,0)$ you
- get a linear interpolation between time--value pairs.
-
- Two special cases are the following: When the two last parameters, the exit
- spline, take the special values |stay| and |0|, the attribute's value
- ``stays'' until the next value for the next time (it then ``jumps'' to the
- next value then). This corresponds, roughly, to an ``infinite'' \meta{exit
- spline control x}. Similarly, when the entry spline parameters take the
- special values |jump| and |1|, the value immediately jumps from the
- previous value to the next value when the previous value was specified.
-\end{command}
-
-\begin{command}{\pgfsysanimkeybase}
-\end{command}
-%
-\begin{command}{\pgfsys@animation@base}
- This command can be used in any place where |\pgfsys@animation@time| is
- usually used. The effect is that the next value does not become part of the
- timeline, but will become the value used for the attribute when no
- animation is active. (Normally, when the animation is not active, no value
- is set at all and the value is inherited from the surrounding scope.)
-\end{command}
-
-It may happen that there is more than one timeline active that is ``trying to
-modify'' a given attribute. In this case, the following rules are used to
-determine, which timeline ``wins'':
-%
-\begin{enumerate}
- \item If no animation is active at the current time (all animation either
- have not yet started or they have already ended), then the base value
- given in the animation encountered last in the code is used. (If there
- are no base values, the attribute is taken from the surrounding scope.)
- \item If there are several active animations, the one that has started last
- is used and the its value is used.
- \item If there are several active animations that have started at the same
- time, the one that comes last in the code is used.
-\end{enumerate}
-
-Note that these rules do not apply to transformations of the canvas since these
-are always additive (or, phrased differently, they are always all active and
-the effects accumulate).
-
-
-\subsection{Commands for Specifying Timelines: Specifying Values}
-
-The following commands are used to specify the values of a timeline. Each use
-of one of the following commands adds one time--value pair to the timeline.
-Which of the commands must be used depends on the type of the to-be-animated
-attribute (see the |\pgfsysanimate| command instances, which list the command
-that must be used).
-
-\begin{command}{\pgfsysanimvalcurrent}
-\end{command}
-\begin{command}{\pgfsys@animation@val@current}
- Creates a time--value pairs where the value is the current value that the
- attribute has. This command can only be used in conjunction with ``real''
- animations, when you use it with a snapshot an error is raised.
-\end{command}
-
-\begin{command}{\pgfsysanimvaltext\marg{text}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@text\marg{text}}
- Creates a time--value pairs where the value is some text. Which texts are
- permissible depends on the to-be-animated attribute.
-\end{command}
-
-\begin{command}{\pgfsysanimvalscalar\marg{number}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@scalar\marg{number}}
- Creates a time--value pairs where the value is a number like |0.5| or
- |-2.25|.
-\end{command}
-
-\begin{command}{\pgfsysanimvaldimension\marg{dimension}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@dimension\marg{dimension}}
- Creates a time--value pairs where the value is a \TeX\ dimension like
- |0.5pt| or |-2in|.
-\end{command}
-
-\begin{command}{\pgfsysanimvalcolorrgb\marg{red}\marg{green}\marg{blue}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@color@rgb\marg{red}\marg{green}\marg{blue}}
- Creates a time--value pairs where the value is color specified by three
- fractional values between 0 and 1 for the red, the green, and the blue
- part.
-\end{command}
-
-\begin{command}{\pgfsysanimvalcolorcmyk\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@color@cmyk\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}}
- Creates a time--value pairs where the value is color specified by four
- fractional values between 0 and 1 for the cyan, magenta, yellow, and black
- part.
-\end{command}
-
-\begin{command}{\pgfsysanimvalcolorcmy\marg{cyan}\marg{magenta}\marg{yellow}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@color@cmy\marg{cyan}\marg{magenta}\marg{yellow}}
- Like the |\pgfsysanimvalcolorcmyk| only without the black part.
-\end{command}
-
-\begin{command}{\pgfsysanimvalcolorgray\marg{gray value}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@color@gray\marg{gray value}}
- Creates a time--value pairs where the value is gray value (a
- fraction between 0 and 1).
-\end{command}
-
-\begin{command}{\pgfsysanimvalpath\marg{low-level path construction commands}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@path\marg{low-level path construction command}}
- Creates a time--value pairs where the value is path. The \meta{low-level
- commands} must consist of a sequence of path construction commands like
- |\pgfsys@lineto| or |\pgfsyssoftpath@linetotoken| (more precisely, the
- commands must form a list of \TeX\ tokens and dimensions surrounded by
- braces). For each call of this command, the sequence of tokens and numbers
- must be the some. During the animation, only and exactly the numbers will
- be interpolated.
-\end{command}
-
-\begin{command}{\pgfsysanimvaltranslate\marg{x dimension}\marg{y dimension}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@translate\marg{x dimension}\marg{y dimension}}
- Creates a time--value pairs where the value is a coordinate. The dimensions
- must be \TeX\ dimensions.
-\end{command}
-
-\begin{command}{\pgfsysanimvalscale\marg{x scale}\marg{y scale}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@scale\marg{x scale}\marg{y scale}}
- Creates a time--value pairs where the value is pair of scalar values.
-\end{command}
-
-\begin{command}{\pgfsysanimvalviewbox\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@viewbox\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}}
- Creates a time--value pairs where the value is view box. The lower left
- corner is given by $(x_1,y_1)$, consisting of two \TeX\ dimensions, and the
- upper right corner is $(x_2,y_2)$.
-\end{command}
-
-\begin{command}{\pgfsysanimvaldash\marg{pattern}\marg{phase}}
-\end{command}
-\begin{command}{\pgfsys@animation@val@dash\marg{pattern}\marg{phase}}
- Creates a time--value pairs where the value is dash pattern and phase with
- the same syntax as |\pgfsys@setdash|.
-\end{command}
-
-
-\subsection{Commands for Specifying Timing: Repeats}
-
-\begin{command}{\pgfsysanimkeyrepeat{number of times}}
-\end{command}
-\begin{command}{\pgfsys@animation@repeat\marg{number of times}}
- Specifies that the animation should repeat the specified \meta{number of
- times}, which may be a fractional number.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5,6,7,8},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyrepeat{2.5}
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsysanimkeyrepeatindefinite}
-\end{command}
-\begin{command}{\pgfsys@animation@repeat@indefinite}
- Specifies that the animation should repeat indefinitely.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5,6,7,8},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyrepeatindefinite
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsysanimkeyrepeatdur\meta{seconds}}
-\end{command}
-\begin{command}{\pgfsys@animation@repeat@dur\meta{seconds}}
- Specifies that the animation should repeat until \meta{seconds} have
- elapsed.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5,6,7,8},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyrepeatdur{5}
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Commands for Specifying Timing: Beginning and Ending}
-
-Normally, animations start when a graphic is displayed. Using the following
-commands, you can change this behavior: For instance, you can specify that the
-animation should start when, say, some button has been pressed or a key has
-been hit. Similarly, you can also use the commands to specify that the
-animation should stop early, for instance when a button is pressed.
-
-Note that all of the commands for specifying a nonstandard begin (or end) of an
-animation's timeline refer to when the time $0\,\mathrm s$ of the timeline
-should actually be. If the first time--value point for a timeline is at, say,
-2\,s and you specify that the begin of the animation is one second after the
-click of a button, the attribute will attain the value specified by the
-time--value point three seconds after the button has been pressed.
-
-All of the following commands take either the text |begin| or |end| as their
-last argument.
-
-You can call the commands several times. This will result in several different
-possible beginnings (or endings).
-
-\begin{command}{\pgfsysanimkeyoffset\marg{time offset}\marg{begin or end}}
-\end{command}
-\begin{command}{\pgfsys@animation@offset\marg{time offset}\marg{begin or end}}
- Specifies that (in addition to any other beginnings or endings) the
- animation's timeline should begin (or end) \meta{time offset} many seconds
- after the graphic is shown. For instance, in the next example the animation
- will start automatically after 5\,s \emph{or} when then button is pressed.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5,6,7,8},
-render instead={
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyoffset{5}{begin}
- \pgfsysanimkeysnapshotstart{5}
- \pgfsysanimate{translate} }
- }]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyoffset{5}{begin}
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsysanimkeysyncbegin\marg{sync base id}\marg{type}\marg{time offset}\marg{begin or end}}
-\end{command}
-\begin{command}{\pgfsys@animation@syncbegin\marg{sync base id}\marg{type}\marg{time offset}\marg{begin or end}}
- Specifies that the animation should begin \meta{time offset} many seconds
- after the \meta{sync base id} with the given \meta{type} has begun. Here,
- the \meta{sync base id} must have been obtained using |\pgfsys@new@id|.
-
- The idea behind a sync base is that you setup an animation and name it,
- other animations can start alongside this animation. An animation whose
- sole purpose is to orchestrate other animations in this way is called a
- \emph{sync base}.
-\end{command}
-
-\begin{command}{\pgfsysanimkeysyncend\marg{sync base id}\marg{type}\marg{time offset}\marg{begin or end}}
-\end{command}
-\begin{command}{\pgfsys@animation@syncend\marg{sync base id}\marg{type}\marg{time offset}\marg{begin or end}}
- Works like |\pgfsysanimkeysyncbegin| only the animation begin (or ends)
- when the sync base ends.
-\end{command}
-
-\begin{command}{\pgfsysanimkeyevent\marg{id}\marg{type}\marg{event name}\marg{time offset}\marg{begin or end}}
-\end{command}
-\begin{command}{\pgfsys@animation@event\marg{id}\marg{type}\marg{event name}\marg{time offset}\marg{begin or end}}
- Specifies that the animation should begin (or end) \meta{time offset} many
- seconds after a certain \emph{event} has occurred. Which events are
- possible depends on the specific output language, here are the events
- currently supported in \textsc{svg}:
- %
- \begin{itemize}
- \item |click| occurs when the object with the given \meta{id} and
- \meta{type} has been clicked.
- \item |focusin| and |focusout| occur when the focus enters or leaves
- the object.
- \item |mouseup|, |mousedown|, |mouseover|, |mousemove|, and |mouseout|
- occur when the mouse is pressed up or down on the object, moved
- onto the object, moved over the object, or moved off the object.
- \end{itemize}
- %
-\begin{codeexample}[
- width=2cm,
- preamble={\usetikzlibrary{animations}},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyevent{\nodeid}{}{mouseup}{}{begin}
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\begin{codeexample}[
- width=2cm,
- preamble={\usetikzlibrary{animations}},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyevent{\nodeid}{}{mousedown}{}{begin}
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\begin{codeexample}[
- width=2cm,
- preamble={\usetikzlibrary{animations}},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyevent{\nodeid}{}{mouseover}{}{begin}
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\begin{codeexample}[
- width=2cm,
- preamble={\usetikzlibrary{animations}},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyevent{\nodeid}{}{mousemove}{}{begin}
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\begin{codeexample}[
- width=2cm,
- preamble={\usetikzlibrary{animations}},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyevent{\nodeid}{}{mouseout}{}{begin}
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsysanimkeyrepeatevent\marg{id}\marg{type}\marg{repeat count}\marg{time offset}\marg{begin or end}}
-\end{command}
-\begin{command}{\pgfsys@animation@repeat@event\marg{id}\marg{type}\marg{repeat count}\marg{time offset}\marg{begin or end}}
- The animation begins (or end) with a certain offset when another animation
- has reached a certain repeat count.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5,6,7,8},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-5mm}
- \pgfsysanimkeyrepeatdur{5}
- \pgfsys@new@id{\animationid}
- \pgfsys@use@id{\animationid}
- \pgfsysanimate{translate}
- \global\let\animationid\animationid }
-\tikz {
- \pgfidrefnextuse{\objid}{other}
- \pgfsysanimkeyrepeatevent{\animationid}{}{2}{0}{begin}
- \pgfsysanimkeysnapshotstart{4}
- \pgfsysanimkeywhom{\objid}{}
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-5mm}
- \pgfsysanimate{translate}
- \node [fill=red, text=white, circle] (other) {Other}; }
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsysanimkeyaccesskey\marg{character}\marg{time offset}\marg{begin or end}}
-\end{command}
-\begin{command}{\pgfsys@animation@accesskey\marg{character}\marg{time offset}\marg{begin or end}}
- Begin or end the animation when a certain key is pressed. Note that this
- event may not be supported by some browsers for security reasons (prevent
- key loggers).
- %
-\begin{codeexample}[
- width=2cm,
- preamble={\usetikzlibrary{animations}},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyaccesskey{s}{}{begin}
- \pgfsysanimate{translate}
-}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Commands for Specifying Timing: Restart Behaviour}
-
-\begin{command}{\pgfsysanimkeyrestartalways}
-\end{command}
-\begin{command}{\pgfsys@animation@restart@always}
- Defines that the animation can be restarted at any time. This is the
- default.
- %
-\begin{codeexample}[
- width=2cm,
- preamble={\usetikzlibrary{animations}},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyrestartalways
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsysanimkeyrestartnever}
-\end{command}
-\begin{command}{\pgfsys@animation@restart@never}
- Defines that the animation cannot be restarted once it has run.
- %
-\begin{codeexample}[
- width=2cm,
- preamble={\usetikzlibrary{animations}},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyrestartnever
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsysanimkeyrestartwhennotactive}
-\end{command}
-\begin{command}{\pgfsys@animation@restart@whennotactive}
- Defines that the animation cannot be restarted while it is running.
- %
-\begin{codeexample}[
- width=2cm,
- preamble={\usetikzlibrary{animations}},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyrestartwhennotactive
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsysanimkeyfreezeatend}
-\end{command}
-\begin{command}{\pgfsys@animation@freezeatend}
- When an animation ends, the question is whether the ``effect'' of the
- animation (like changing a color or translating the coordinate system)
- should disappear or ``remain in force''. Using this key, you specify that
- at the end of the animation the last value of the attributes stays in
- effect.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5,6,7,8},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyfreezeatend
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsysanimkeyremoveatend}
-\end{command}
-\begin{command}{\pgfsys@animation@removeatend{}}
- The opposite of |\pgfsysanimkeyfreezeatend|. This is the default.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5,6,7,8},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-1cm}
- \pgfsysanimkeyremoveatend
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Commands for Specifying Accumulation}
-
-Animations specify how an attribute of an object changes over time. When more
-than one animation changes the same value at the same time, the last value
-given for the attribute ``wins'', except for animations of the canvas, which
-always accumulate. Additionally, when a repeat is specified for an attribute,
-during each repeat the values can add up:
-
-\begin{command}{\pgfsysanimkeyaccumulate{}}
-\end{command}
-\begin{command}{\pgfsys@animation@accumulate{}}
- Specifies that each repeat of an animation works as if the last values
- attained during previous repeats are added to the current value.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5,6,7,8},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-5mm}
- \pgfsysanimkeyaccumulate
- \pgfsysanimkeyrepeatdur{5}
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsysanimkeynoaccumulate{}}
-\end{command}
-\begin{command}{\pgfsys@animation@noaccumulate{}}
- Specifies that each repeat resets the to-be-animated value. This is the
- default.
- %
-\begin{codeexample}[
- width=6cm,
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5,6,7,8},
-]
-\animationexample{node}{}{
- \pgfsysanimkeytime{0}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{0cm}
- \pgfsysanimkeytime{2}{1}{1}{0}{0}
- \pgfsysanimvaltranslate{0cm}{-5mm}
- \pgfsysanimkeynoaccumulate
- \pgfsysanimkeyrepeatdur{5}
- \pgfsysanimate{translate} }
-\end{codeexample}
- %
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-commands.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-commands.tex
deleted file mode 100644
index 7bf200c044..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-commands.tex
+++ /dev/null
@@ -1,1390 +0,0 @@
-% 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{Commands of the System Layer}
-
-\makeatletter
-
-\subsection{Beginning and Ending a Stream of System Commands}
-
-A ``user'' of the \pgfname\ system layer (like the basic layer or a frontend)
-will interface with the system layer by calling a stream of commands starting
-with |\pgfsys@|. From the system layer's point of view, these commands form a
-long stream. Between calls to the system layer, control goes back to the user.
-
-The driver files implement system layer commands by inserting |\special|
-commands that implement the desired operation. For example, |\pgfsys@stroke|
-will be mapped to |\special{pdf: S}| by the driver file for |pdftex|.
-
-For many drivers, when such a stream of specials starts, it is necessary to
-install an appropriate transformation and perhaps perform some more
-bureaucratic tasks. For this reason, every stream will start with a
-|\pgfsys@beginpicture| and will end with a corresponding ending command.
-
-\begin{command}{\pgfsys@beginpicture}
- Called at the beginning of a |{pgfpicture}|. This command should ``set up
- things''.
-
- Most drivers will need to implement this command.
-\end{command}
-
-\begin{command}{\pgfsys@endpicture}
- Called at the end of a |{pgfpicture}|.
-
- Most drivers will need to implement this command.
-\end{command}
-
-\begin{command}{\pgfsys@typesetpicturebox\marg{box}}
- Called \emph{after} a |{pgfpicture}| has been typeset. The picture will
- have been put in box \meta{box}. This command should insert the box into
- the normal text. The box \meta{box} will still be a ``raw'' box that
- contains only the |\special|'s that make up the description of the picture.
- The job of this command is to resize and shift \meta{box} according to the
- baseline shift and the size of the box.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-\end{command}
-
-\begin{command}{\pgfsys@beginpurepicture}
- This version of the |\pgfsys@beginpicture| picture command can be used for
- pictures that are guaranteed not to contain any escaped boxes (see below).
- In this case, a driver might provide a more compact version of the command.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-\end{command}
-
-\begin{command}{\pgfsys@endpurepicture}
- Called at the end of a ``pure'' |{pgfpicture}|.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-\end{command}
-
-Inside a stream it is sometimes necessary to ``escape'' back into normal
-typesetting mode; for example to insert some normal text, but with all of the
-current transformations and clippings being in force. For this escaping, the
-following command is used:
-
-\begin{command}{\pgfsys@hbox\marg{box number}}
- Called to insert a (horizontal) TeX box inside a |{pgfpicture}|.
-
- Most drivers will need to (re-)implement this command.
-\end{command}
-
-\begin{command}{\pgfsys@hboxsynced\marg{box number}}
- Called to insert a (horizontal) TeX box inside a |{pgfpicture}|, but with
- the current coordinate transformation matrix synced with the canvas
- transformation matrix.
-
- This command should do the same as if you used |\pgflowlevelsynccm|
- followed by |\pgfsys@hbox|. However, the default implementation of this
- command will use a ``TeX-translation'' for the translation part of the
- transformation matrix. This will ensure that hyperlinks ``survive'' at
- least translations. On the other hand, a driver may choose to revert to a
- simpler implementation. This is done, for example, for the \textsc{svg}
- implementation, where a \TeX-translation makes no sense.
-\end{command}
-
-\begin{command}{\pgfsys@pictureboxsynced\marg{box number}}
- Basically, this should do the same as doing a (scoped) low level sync
- followed by inserting the box \meta{box number} directly into the output
- stream. However, the default implementation uses |\pgfsys@hboxsynced| in
- conjunction with |\pgfsys@beginpicture| to ensure that, if possible,
- hyperlinks survive in \textsc{pdf}s. Drivers that are sensitive to
- picture-in-picture scopes should replace this implementation by
- %
-\begin{codeexample}[code only]
-\pgfsys@beginscope\pgflowlevelsynccm\box#1\pgfsys@endscope
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Scoping System Commands}
-
-The scoping commands are used to keep changes of the graphics state local.
-
-\begin{command}{\pgfsys@beginscope}
- Saves the current graphic state on a graphic state stack. All changes to
- the graphic state parameters mentioned for |\pgfsys@stroke| and
- |\pgfsys@fill| will be local to the current graphic state and the old
- values will be restored after |\pgfsys@endscope| is used.
-
- \emph{Warning:} \pdf\ and PostScript differ with respect to the question of
- whether the current path is part of the graphic state or not. For this
- reason, you should never use this command unless the path is currently
- empty. For example, it might be a good idea to use |\pgfsys@discardpath|
- prior to calling this command.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@endscope}
- Restores the last saved graphic state.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-
-\subsection{Path Construction System Commands}
-
-\begin{command}{\pgfsys@moveto\marg{x}\marg{y}}
- This command is used to start a path at a specific point $(x,y)$ or to move
- the current point of the current path to $(x,y)$ without drawing anything
- upon stroking (the current path is ``interrupted'').
-
- Both \meta{x} and \meta{y} are given as \TeX\ dimensions. It is the
- driver's job to transform these to the coordinate system of the backend.
- Typically, this means converting the \TeX\ dimension into a dimensionless
- multiple of $\frac{1}{72}\mathrm{in}$. The function |\pgf@sys@bp| helps
- with this conversion.
-
- \example Draw a line from $(10\mathrm{pt},10\mathrm{pt})$ to the origin of
- the picture.
- %
-\begin{codeexample}[code only]
-\pgfsys@moveto{10pt}{10pt}
-\pgfsys@lineto{0pt}{0pt}
-\pgfsys@stroke
-\end{codeexample}
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@lineto\marg{x}\marg{y}}
- Continue the current path to $(x,y)$ with a straight line.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@curveto\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}\marg{$x_3$}\marg{$y_3$}}
- Continue the current path to $(x_3,y_3)$ with a Bézier curve that has the
- two control points $(x_1,y_1)$ and $(x_2,y_2)$.
-
- \example Draw a good approximation of a quarter circle:
- %
-\begin{codeexample}[code only]
-\pgfsys@moveto{10pt}{0pt}
-\pgfsys@curveto{10pt}{5.55pt}{5.55pt}{10pt}{0pt}{10pt}
-\pgfsys@stroke
-\end{codeexample}
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@rect\marg{x}\marg{y}\marg{width}\marg{height}}
- Append a rectangle to the current path whose lower left corner is at
- $(x,y)$ and whose width and height in big points are given by \meta{width}
- and \meta{height}.
-
- This command can be ``mapped back'' to |\pgfsys@moveto| and
- |\pgfsys@lineto| commands, but it is included since \pdf\ has a special,
- quick version of this command.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@closepath}
- Close the current path. This results in joining the current point of the
- path with the point specified by the last |\pgfsys@moveto| operation.
- Typically, this is preferable over using |\pgfsys@lineto| to the last point
- specified by a |\pgfsys@moveto|, since the line starting at this point and
- the line ending at this point will be smoothly joined by
- |\pgfsys@closepath|.
-
- \example Consider
- %
-\begin{codeexample}[code only]
-\pgfsys@moveto{0pt}{0pt}
-\pgfsys@lineto{10bp}{10bp}
-\pgfsys@lineto{0bp}{10bp}
-\pgfsys@closepath
-\pgfsys@stroke
-\end{codeexample}
- %
- and
- %
-\begin{codeexample}[code only]
-\pgfsys@moveto{0bp}{0bp}
-\pgfsys@lineto{10bp}{10bp}
-\pgfsys@lineto{0bp}{10bp}
-\pgfsys@lineto{0bp}{0bp}
-\pgfsys@stroke
-\end{codeexample}
-
- The difference between the above will be that in the second triangle the
- corner at the origin will be wrong; it will just be the overlay of two
- lines going in different directions, not a sharp pointed corner.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-
-\subsection{Canvas Transformation System Commands}
-
-\begin{command}{\pgfsys@transformcm\marg{a}\marg{b}\marg{c}\marg{d}\marg{e}\marg{f}}
- Perform a concatenation of the canvas transformation matrix with the matrix
- given by the values \meta{a} to \meta{f}, see the \pdf\ or PostScript
- manual for details. The values \meta{a} to \meta{d} are dimensionless
- factors, \meta{e} and \meta{f} are \TeX\ dimensions
-
- \example |\pgfsys@transformcm{1}{0}{0}{1}{1cm}{1cm}|.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@transformshift\marg{x displacement}\marg{y displacement}}
- This command will change the origin of the canvas to $(x,y)$.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@transformxyscale\marg{x scale}\marg{y scale}}
- This command will scale the canvas (and everything that is drawn) by a
- factor of \meta{x scale} in the $x$-direction and \meta{y scale} in the
- $y$-direction. Note that this applies to everything, including lines. So a
- scaled line will have a different width and may even have a different width
- when going along the $x$-axis and when going along the $y$-axis, if the
- scaling is different in these directions. Usually, you do not want this.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@viewboxmeet\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}%
- \marg{$x'_1$}\marg{$y'_1$}\marg{$x'_2$}\marg{$y'_2$}%
-}
- Starts a ``view box'' scope, which must be ended using |\pgfsys@endviewbox|
- later on (with matching scopes).
-
- The effect of this command is as follows: Consider the rectangles $R$ with
- lower left corner $(x_1,y_1)$ and upper right corner $(x_2,y_2)$ and $R'$
- with corners $(x'_1,y'_1)$ and $(x'_2,y'_2)$. The command will install a
- canvas translation and uniform scaling such that $R'$ then has the same
- center as~$R$ and additionally, has maximum size such that it still fits
- inside~$R$. (Think of this as ``viewing'' $R'$ through $R$ such that the
- aspect ratio is kept.)
-
- This command has a default implementation. Its main purpose is to allow
- animations of the view box; for static drawings it is better to compute the
- necessary transformations directly.
-\end{command}
-
-\begin{command}{\pgfsys@viewboxslice\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}%
- \marg{$x'_1$}\marg{$y'_1$}\marg{$x'_2$}\marg{$y'_2$}%
-}
- Works like the previous command, but now $R'$ has minimal size such that it
- encompasses all of $R$.
-\end{command}
-
-\begin{command}{\pgfsys@endviewbox}
- Ends a viewbox previously started using |\pgfsys@viewboxmeet| or the
- |...slice| variant.
-\end{command}
-
-
-\subsection{Stroking, Filling, and Clipping System Commands}
-
-\begin{command}{\pgfsys@stroke}
- Stroke the current path (as if it were drawn with a pen). A number of
- graphic state parameters influence this, which can be set using appropriate
- system commands described later.
- %
- \begin{description}
- \item[Line width] The ``thickness'' of the line. A width of 0 is the
- thinnest width renderable on the device. On a high-resolution
- printer this may become invisible and should be avoided. A good
- choice is 0.4pt, which is the default.
- \item[Stroke color] This special color is used for stroking. If it is
- not set, the current color is used.
- \item[Cap] The cap describes how the endings of lines are drawn. A
- round cap adds a little half circle to these endings. A butt cap
- ends the lines exactly at the end (or start) point without anything
- added. A rectangular cap ends the lines like the butt cap, but the
- lines protrude over the endpoint by the line thickness. (See also
- the \pdf\ manual.) If the path has been closed, no cap is drawn.
- \item[Join] This describes how a bend (a join) in a path is rendered. A
- round join draws bends using small arcs. A bevel join just draws
- the two lines and then fills the join minimally so that it becomes
- convex. A miter join extends the lines so that they form a single
- sharp corner, but only up to a certain miter limit. (See the \pdf\
- manual once more.)
- \item[Dash] The line may be dashed according to a dashing pattern.
- \item[Clipping area] If a clipping area is established, only those
- parts of the path that are inside the clipping area will be drawn.
- \end{description}
-
- In addition to stroking a path, the path may also be used for clipping
- after it has been stroked. This will happen if the |\pgfsys@clipnext| is
- used prior to this command, see there for details.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@closestroke}
- This command should have the same effect as first closing the path and then
- stroking it.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-
-\begin{command}{\pgfsys@fill}
- This command fills the area surrounded by the current path. If the path has
- not yet been closed, it is closed prior to filling. The path itself is not
- stroked. For self-intersecting paths or paths consisting of multiple parts,
- the nonzero winding number rule is used to determine whether a point is
- inside or outside the path, except if |\ifpgfsys@eorule| holds -- in which
- case the even-odd rule should be used. (See the \pdf\ or PostScript manual
- for details.)
-
- The following graphic state parameters influence the filling:
- %
- \begin{description}
- \item[Interior rule] If |\ifpgfsys@eorule| is set, the even-odd rule is
- used, otherwise the non-zero winding number rule.
- \item[Fill color] If the fill color is not especially set, the current
- color is used.
- \item[Clipping area] If a clipping area is established, only those
- parts of the filling area that are inside the clipping area will be
- drawn.
- \end{description}
-
- In addition to filling the path, the path will also be used for clipping if
- |\pgfsys@clipnext| is used prior to this command.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@fillstroke}
- First, the path is filled, then the path is stroked. If the fill and stroke
- colors are the same (or if they are not specified and the current color is
- used), this yields almost the same as a |\pgfsys@fill|. However, due to the
- line thickness of the stroked path, the fill-stroked area will be slightly
- larger.
-
- In addition to stroking and filling the path, the path will also be used
- for clipping if |\pgfsys@clipnext| is used prior to this command.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@discardpath}
- Normally, this command should ``throw away'' the current path. However,
- after |\pgfsys@clipnext| has been called, the current path should
- subsequently be used for clipping. See |\pgfsys@clipnext| for details.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@clipnext}
- This command should be issued after a path has been constructed, but before
- it has been stroked and/or filled or discarded. When the command is used,
- the next stroking/filling/discarding command will first be executed
- normally. Then, afterwards, the just-used path will be used for subsequent
- clipping. If there has already been a clipping region, this region is
- intersected with the new clipping path (the clipping cannot get bigger).
- The nonzero winding number rule is used to determine whether a point is
- inside or outside the clipping area or the even-odd rule, depending on
- whether |\ifpgfsys@eorule| holds.
-\end{command}
-
-
-\subsection{Graphic State Option System Commands}
-
-\begin{command}{\pgfsys@setlinewidth\marg{width}}
- Sets the width of lines, when stroked, to \meta{width}, which must be a
- \TeX\ dimension.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@buttcap}
- Sets the cap to a butt cap. See |\pgfsys@stroke|.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@roundcap}
- Sets the cap to a round cap. See |\pgfsys@stroke|.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@rectcap}
- Sets the cap to a rectangular cap. See |\pgfsys@stroke|.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@miterjoin}
- Sets the join to a miter join. See |\pgfsys@stroke|.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@setmiterlimit\marg{factor}}
- Sets the miter limit of lines to \meta{factor}. See the \pdf\ or PostScript
- for details on what the miter limit is.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@roundjoin}
- Sets the join to a round join. See |\pgfsys@stroke|.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@beveljoin}
- Sets the join to a bevel join. See |\pgfsys@stroke|.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@setdash\marg{pattern}\marg{phase}}
- Sets the dashing patter. \meta{pattern} should be a list of \TeX\
- dimensions separated by commas. \meta{phase} should be a single dimension.
-
- \example |\pgfsys@setdash{3pt,3pt}{0pt}|
-
- The list of values in \meta{pattern} is used to determine the lengths of
- the ``on'' and ``off'' phases of the dashing. For example, if
- \meta{pattern} is |3bp,4bp|, then the dashing pattern is ``3bp on followed
- by 4bp off, followed by 3bp on, followed by 4bp off, and so on''. A pattern
- of |.5pt,4pt,3pt,1.5pt| means ``.5pt on, 4pt off, 3pt on, 1.5pt off, .5pt
- on, \dots'' If the number of entries is odd, the last one is used twice, so
- |3pt| means ``3pt on, 3pt off, 3pt on, 3pt off, \dots'' An empty list means
- ``always on''.
-
- The second argument determines the ``phase'' of the pattern. For example,
- for a pattern of |3bp,4bp| and a phase of |1bp|, the pattern would start:
- ``2bp on, 4bp off, 3bp on, 4bp off, 3bp on, 4bp off, \dots''
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-{\let\ifpgfsys@eorule=\relax
-\begin{command}{\ifpgfsys@eorule}
- Determines whether the even odd rule is used for filling and clipping or
- not.
-\end{command}
-}
-
-
-\subsection{Color System Commands}
-
-The \pgfname\ system layer provides a number of system commands for setting
-colors. These command coexist with commands from the |color| and |xcolor|
-package, which perform similar functions. However, the |color| package does not
-support having two different colors for stroking and filling, which is a useful
-feature that is supported by \pgfname. For this reason, the \pgfname\ system
-layer offers commands for setting these colors separately. Also, plain \TeX\
-profits from the fact that \pgfname\ can set colors.
-
-For \pdf, implementing these color commands is easy since \pdf\ supports
-different stroking and filling colors directly. For PostScript, a more
-complicated approach is needed in which the colors need to be stored in special
-PostScript variables that are set whenever a stroking or a filling operation is
-done.
-
-\begin{command}{\pgfsys@color@rgb\marg{red}\marg{green}\marg{blue}}
- Sets the color used for stroking and filling operations to the given
- red/green/blue tuple (numbers between 0 and 1).
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@rgb@stroke\marg{red}\marg{green}\marg{blue}}
- Sets the color used for stroking operations to the given red/green/blue
- tuple (numbers between 0 and 1).
-
- \example Make stroked text dark red: |\pgfsys@color@rgb@stroke{0.5}{0}{0}|
-
- The special stroking color is only used if the stroking color has been set
- since the last |\color| or |\pgfsys@color@...| command. Thus, each |\color|
- command will reset both the stroking and filling colors by calling
- |\pgfsys@color@reset|.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@rgb@fill\marg{red}\marg{green}\marg{blue}}
- Sets the color used for filling operations to the given red/green/blue
- tuple (numbers between 0 and 1). This color may be different from the
- stroking color.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@cmyk\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}}
- Sets the color used for stroking and filling operations to the given cmyk
- tuple (numbers between 0 and 1).
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@cmyk@stroke\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}}
- Sets the color used for stroking operations to the given cmyk tuple
- (numbers between 0 and 1).
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@cmyk@fill\marg{cyan}\marg{magenta}\marg{yellow}\marg{black}}
- Sets the color used for filling operations to the given cmyk tuple (numbers
- between 0 and 1).
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@cmy\marg{cyan}\marg{magenta}\marg{yellow}}
- Sets the color used for stroking and filling operations to the given cmy
- tuple (numbers between 0 and 1).
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@cmy@stroke\marg{cyan}\marg{magenta}\marg{yellow}}
- Sets the color used for stroking operations to the given cmy tuple (numbers
- between 0 and 1).
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@cmy@fill\marg{cyan}\marg{magenta}\marg{yellow}}
- Sets the color used for filling operations to the given cmy tuple (numbers
- between 0 and 1).
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@gray\marg{black}}
- Sets the color used for stroking and filling operations to the given black
- value, where 0 means black and 1 means white.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@gray@stroke\marg{black}}
- Sets the color used for stroking operations to the given black value, where
- 0 means black and 1 means white.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@gray@fill\marg{black}}
- Sets the color used for filling operations to the given black value, where
- 0 means black and 1 means white.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@color@reset}
- This command will be called when the |\color| command is used. It should
- purge any internal settings of stroking and filling color. After this call,
- till the next use of a command like |\pgfsys@color@rgb@fill|, the current
- color installed by the |\color| command should be used.
-
- If the \TeX-if |\pgfsys@color@reset@inorder| is set to true, this command
- may ``assume'' that any call to a color command that sets the fill or
- stroke color came ``before'' the call to this command and may try to
- optimize the output accordingly.
-
- An example of an incorrect ``out of order'' call would be using
- |\pgfsys@color@reset| at the beginning of a box that is constructed using
- |\setbox|. Then, when the box is constructed, no special fill or stroke
- color might be in force. However, when the box is later on inserted at some
- point, a special fill color might already have been set. In this case, this
- command is not guaranteed to reset the color correctly.
-\end{command}
-
-\begin{command}{\pgfsys@color@reset@inordertrue}
- Sets the optimized ``in order'' version of the color resetting. This is the
- default.
-\end{command}
-
-\begin{command}{\pgfsys@color@reset@inorderfalse}
- Switches off the optimized color resetting.
-\end{command}
-
-\begin{command}{\pgfsys@color@unstacked\marg{\LaTeX\ color}}
- This slightly obscure command causes the color stack to be tricked. When
- called, this command should set the current color to \meta{\LaTeX\ color}
- without causing any change in the color stack.
-
- \example |\pgfsys@color@unstacked{red}|
-\end{command}
-
-
-\subsection{Pattern System Commands}
-
-\begin{command}{\pgfsys@declarepattern
- \marg{name}\marg{$x_1$}\marg{$y_1$}\marg{$x_2$}\marg{$y_2$}%
- \marg{$x$ step}\marg{$y$ step}%
- \marg{$a$}\marg{$b$}\marg{$c$}\marg{$d$}\allowbreak\marg{$e$}\marg{$f$}%
- \marg{code}\marg{flag}%
-}
- This command declares a new colored or uncolored pattern, depending on
- whether \meta{flag} is |0|, which means uncolored, or |1|, which means
- colored. Uncolored patterns have no inherent color, the color is provided
- when they are set. Colored patters have an inherent color.
-
- The \meta{name} is a name for later use when the pattern is to be shown.
- The pairs $(x_1,y_1)$ and $(x_2,y_2)$ must describe a bounding box of the
- pattern \meta{code}.
-
- The tiling step of the pattern is given by \meta{$x$ step} and \meta{$y$
- step}.
-
- The parameters \meta{$a$} to \meta{$f$} are entries of the transformation
- matrix that is applied to the pattern, see |\pgfsys@patternmatrix| for more
- information.
-
- \example
- %
-\begin{codeexample}[code only]
-\pgfsys@declarepattern
- {hori}{-.5pt}{0pt}{.5pt}{3pt}{3pt}{3pt}%
- {1.0}{0.0}{0.0}{1.0}{0.0pt}{0.0pt}%
- {\pgfsys@moveto{0pt}{0pt}\pgfsys@lineto{0pt}{3pt}\pgfsys@stroke}
- {0}
-\end{codeexample}
- %
-\end{command}
-
-
-\begin{command}{\pgfsys@patternmatrix}
- For convenience \pgfname\ defines the transformation matrix that is applied
- to all patterns defined with |\pgfdeclarepatternformonly| and
- |\pgfdeclarepatterninherentlycolored| in a macro. This can be used as an
- extension point for ad-hoc transformation of existing patterns. The
- default definition is the
- identity matrix:
- %
-\begin{codeexample}[code only]
-\def\pgfsys@patternmatrix{{1.0}{0.0}{0.0}{1.0}{0.0pt}{0.0pt}}
-\end{codeexample}
- %
- The entries of the enclosed array
- |{|\meta{$a$}|}{|\meta{$b$}|}{|\meta{$c$}|}{|\meta{$d$}|}{|\meta{$e$}|}{|\meta{$f$}|}|
- are entries in the transformation matrix, identified as in the following
- transformation prescription:
- \begin{equation*}
- \begin{pmatrix}
- x' \\
- y' \\
- 1 \\
- \end{pmatrix}
- =
- \begin{pmatrix}
- a & c & e \\
- b & d & f \\
- 0 & 0 & 1 \\
- \end{pmatrix}
- \begin{pmatrix}
- x \\
- y \\
- 1 \\
- \end{pmatrix} .
- \end{equation*}
- Carrying out the matrix multiplication results in the following system of
- equations
- \begin{align*}
- x' &= a x + c y + e , \\
- y' &= b x + d y + f .
- \end{align*}
- Evidently, the parameters \marg{$a$} to \marg{$d$} have to be dimensionless
- because they are scaling factors, but the parameters \marg{$e$} and
- \marg{$f$} are offsets, therefore they have to carry a unit.
-\end{command}
-
-\begin{command}{\pgfsys@setpatternuncolored\marg{name}\marg{red}\marg{green}\marg{blue}}
- Sets the fill color to the pattern named \meta{name}. This pattern must
- previously have been declared with \meta{flag} set to |0|. The color of the
- pattern is given in the parameters \meta{red}, \meta{green}, and
- \meta{blue} in the usual way.
-
- The fill color ``pattern'' will persist till the next color command that
- modifies the fill color.
-\end{command}
-
-\begin{command}{\pgfsys@setpatterncolored\marg{name}}
- Sets the fill color to the pattern named \meta{name}. This pattern must
- have been declared with the |1| flag.
-\end{command}
-
-
-\subsection{Image System Commands}
-
-The system layer provides some commands for image inclusion.
-
-\begin{command}{\pgfsys@imagesuffixlist}
- This macro should expand to a list of suffixes, separated by `:', that will
- be tried when searching for an image.
-
- \example |\def\pgfsys@imagesuffixlist{eps:epsi:ps}|
-\end{command}
-
-\begin{command}{\pgfsys@defineimage}
- Called, when an image should be defined.
-
- This command does not take any parameters. Instead, certain macros will be
- preinstalled with appropriate values when this command is invoked. These
- are:
- %
- \begin{itemize}
- \item\declare{|\pgf@filename|} File name of the image to be defined.
- \item\declare{|\pgf@imagewidth|} Will be set to the desired (scaled)
- width of the image.
- \item\declare{|\pgf@imageheight|} Will be set to the desired (scaled)
- height of the image.
-
- If this macro and also the height macro are empty, the image should
- have its ``natural'' size.
-
- If only one of them is specified, the undefined value the image is
- scaled so that the aspect ratio is kept.
-
- If both are set, the image is scaled in both directions
- independently, possibly changing the aspect ratio.
- \end{itemize}
-
- The following macros presumable mostly make sense for drivers that
- can handle \pdf:
- %
- \begin{itemize}
- \item \declare{|\pgf@imagepage|} The desired page number to be
- extracted from a multi-page ``image''.
- \item\declare{|\pgf@imagemask|} If set, it will be set to
- |/SMask x 0 R| where |x| is the \pdf\ object number of a soft mask
- to be applied to the image.
- \item\declare{|\pgf@imageinterpolate|} If set, it will be set to
- |/Interpolate true| or |/Interpolate false|, indicating whether the
- image should be interpolated in \pdf.
- \end{itemize}
-
- The command should now set up the macro |\pgf@image| such that calling this
- macro will result in typesetting the image. Thus, |\pgf@image| is the
- ``return value'' of the command.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-\end{command}
-
-
-\subsection{Shading System Commands}
-
-\begin{command}{\pgfsys@horishading\marg{name}\marg{height}\marg{specification}}
- Declares a horizontal shading for later use. The effect of this command
- should be the definition of a macro called |\@pgfshading|\meta{name}|!| (or
- |\csname @pdfshading|\meta{name}|!\endcsname|, to be precise). When
- invoked, this new macro should insert a shading at the current position.
-
- \meta{name} is the name of the shading, which is also used in the output
- macro name. \meta{height} is the height of the shading and must be given as
- a TeX dimension like |2cm| or |10pt|. \meta{specification} is a shading
- color specification as specified in Section~\ref{section-shadings}. The
- shading specification implicitly fixes the width of the shading.
-
- When |\@pgfshading|\meta{name}|!| is invoked, it should insert a box of
- height \meta{height} and the width implicit in the shading declaration.
-\end{command}
-
-\begin{command}{\pgfsys@vertshading\marg{name}\marg{width}\marg{specification}}
- Like the horizontal version, only for vertical shadings. This time, the
- height of the shading is implicit in \meta{specification} and the width is
- given as \meta{width}.
-\end{command}
-
-\begin{command}{\pgfsys@radialshading\marg{name}\marg{starting point}\marg{specification}}
- Declares a radial shading. Like the previous macros, this command should
- set up the macro |\@pgfshading|\meta{name}|!|, which upon invocation should
- insert a radial shading whose size is implicit in \meta{specification}.
-
- The parameter \meta{starting point} is a \pgfname\ point specifying the
- inner starting point of the shading.
-\end{command}
-
-\begin{command}{\pgfsys@functionalshading\marg{name}\marg{lower left corner}\meta{upper right corner}\marg{type 4 function}}
- Declares a shading using a PostScript-like function that provides a color
- for each point. Like the previous macros, this command should set up the
- macro |\@pgfshading|\meta{name}|!| so that it will produce a box containing
- the desired shading.
-
- Parameter \meta{name} is the name of the shading. Parameter \meta{type 4
- function} is a Postscript-like function (type 4 function of the PDF
- specification) as described in Section~3.9.4 of the PDF specification
- version 1.7. Parameters \meta{lower left corner} and \meta{upper right
- corner} are \pgfname\ points that specifies the lower left and upper right
- corners of the shading, respectively.
-
- When \meta{type 4 function} is evaluated, the coordinate of the current
- point will be on the (virtual) PostScript stack in bp units. After the
- function has been evaluated, the stack should consist of three numbers (not
- integers! -- the Apple PDF renderer is broken in this regard, so add cvrs
- at the end if needed) that represent the red, green, and blue components of
- the color.
-
- A buggy function will result is \emph{totally unpredictable chaos} during
- rendering.
-\end{command}
-
-
-\subsection{Transparency System Commands}
-
-\begin{command}{\pgfsys@opacity\marg{value}}
- Sets the opacity of all operations, treating stroking and filling as a
- transparency group. Some drivers support this operations, others do not and
- set the fill and stroke individually. This difference can only be seen when
- a path is stroked and filled at the same time: When the drawing and fill
- opacities are set individually, the effect of filling and drawing a path at
- the same time is the same as first filling the path and then drawing it. On
- the other, if the opacity is set using this command, the effect should
- rather be that same as first filling and then drawing the path without any
- opacity in an off-screen area and then copying the result to the target
- area with a homogeneous opacity of \meta{value}.
-
- Since \textsc{pdf} does not support this form of opacity, this command is
- only present on the system layer and not supported in the basic layer.
-\end{command}
-
-\begin{command}{\pgfsys@stroke@opacity\marg{value}}
- Sets the opacity of stroking operations.
-\end{command}
-
-\begin{command}{\pgfsys@fill@opacity\marg{value}}
- Sets the opacity of filling operations.
-\end{command}
-
-\begin{command}{\pgfsys@blend@mode\marg{value}}
- Sets the blend mode, see Section~7.2.4 of the \textsc{pdf} Specification,
- Version~1.7.
-\end{command}
-
-\begin{command}{\pgfsys@transparencygroupfrombox\marg{box}}
- This takes a \TeX\ box and converts it into a transparency group. This
- means that any transparency settings apply to the box as a whole. For
- instance, if a box contains two overlapping black circles and you draw the
- box and, thus, the two circles normally with 50\% transparency, then the
- overlap will be darker than the rest. By comparison, if the circles are
- part of a transparency group, the overlap will get the same color as the
- rest.
-\end{command}
-
-A transparency group can be \emph{isolated} and/or a \emph{knockout} group (see
-Sections~7.3.4 and 7.3.5 of the \textsc{pdf} Specification Version~1.7). Which
-of these is the case is dictated by the current settings of the following two
-ifs, which must be set before the above command is called:
-
-{\let\ifpgfsys@transparency@group@isolated=\relax
-\begin{command}{\ifpgfsys@transparency@group@isolated}
- Determines whether a transparency group should be isolated.
-\end{command}
-}
-
-{\let\ifpgfsys@transparency@group@knockout=\relax
-\begin{command}{\ifpgfsys@transparency@group@knockout}
- Determines whether a transparency group is a knockout group or not.
-\end{command}
-}
-
-\begin{command}{\pgfsys@fadingfrombox\marg{name}\marg{box}}
- Declares the fading \meta{name}. The \meta{box} is a \TeX-box. Its
- content's luminosity determines the opacity of the resulting fading. This
- means that the lighter a pixel inside the box, the more opaque the fading
- will be at this position.
-\end{command}
-
-\begin{command}{\pgfsys@usefading\meta{name}\marg{a}\marg{b}\marg{c}\marg{d}\marg{e}\marg{f}}
- Installs a previously declared fading \meta{name} in the current graphics
- state. Afterwards, all drawings will be masked by the fading. The fading
- should be centered on the origin and have its original size, except that
- the parameters \meta{a} to \meta{f} specify a transformation matrix that
- should be applied additionally to the fading before it is installed. The
- transformation should not apply to the following graphics, however.
-\end{command}
-
-\begin{command}{\pgfsys@clipfading}
- This command has a default implementation and need not be implemented by
- driver files other than |pgfsys-dvips.def|. The macro is called
- in |\pgfsetfadingforcurrentpath| and |\pgfsetfadingforcurrentpathstroked|
- of the basic layer, where it invokes the current path for clipping the
- shading just before installing it as an opacity mask for fading. The
- default implementation is actually a non-operation, but with |dvips| it
- is used to clip the fading as described.
-\end{command}
-
-\begin{command}{\pgfsys@definemask}
- This command declares a fading (known as a soft mask in this context) based
- on an image and for usage with images. It works similar to
- |\pgfsys@defineimage|: Certain macros are set when the command is called.
- The result should be to set the macro |\pgf@mask| to a pdf object count
- that can subsequently be used as a transparency mask. The following macros
- will be set when this command is invoked:
- %
- \begin{itemize}
- \item \declare{|\pgf@filename|}
- File name of the mask to be defined.
- \item \declare{|\pgf@maskmatte|}
- The so-called matte of the mask (see the \pdf\ documentation for
- details). The matte is a color specification consisting of 1, 3 or
- 4 numbers between 0 and 1. The number of numbers depends on the
- number of color channels in the image (not in the mask!). It will
- be assumed that the image has been preblended with this color.
- \end{itemize}
-\end{command}
-
-
-\subsection{Animation Commands}
-
-The animation system layer command (|\pgfsys@anim...|) are described in a
-separate section, Section~\ref{section-pgfsys-anim}.
-
-
-\subsection{Object Identification System Commands}
-\label{section-sys-id}
-
-The system layer provides commands for adding identification labels (ids) to
-different objects in a graphic. These can be used for hyperlinking, which is
-needed for instance in conjunction with animations.
-
-The following ``objects'' can get an id assigned to them:
-%
-\begin{enumerate}
- \item Graphic scopes (namely when |\pgfsys@begin@idscope| is called),
- \item view boxes (namely when |\pgfsys@viewboxmeet| or
- |\pgfsys@viewboxslice| are called),
- \item paths (namely when |\pgfsys@fill|, |\pgfsys@stroke|, and so on are
- called),
- \item text boxes (namely when |\pgfsys@hbox| or |\pgfsys@hboxsynced| is
- called), and
- \item animations (namely when |\pgfsys@animate| is called).
-\end{enumerate}
-
-Creating and using ids is a two-step process. First, you create the id using
-|\pgfsys@new@id|, which stores a fresh id in a macro. You can now pass this id
-around and clone it. Then, at some point, you wish one of the above objects to
-actually get this id. For this, you use |\pgfsys@use@id| just \emph{before} the
-object since this command always influences the \emph{next} object.
-
-The basic id management gets more powerful when you use \emph{id types}. The
-idea is as follows: In reality, the objects from above do not get assigned only
-an id, but rather a combination of an id and a type -- and you can set the type
-independently of the id. This is used, for instance, to allow easy access to
-the different parts of a node in animations: Each node has a single id, but
-consists of several graphic objects (normally, at least a background path and a
-text). Each of these uses the same underlying id of the node, but the path has
-the type |path| (actually |background.path|) while the text has the type
-|text|. The advantage is that for each node only one id must be stored instead
-of a great number of the many different possible parts of a node.
-
-\begin{command}{\pgfsys@new@id\marg{macro}}
- Creates a new id for later use and stores it in \meta{macro}. It is an
- internal text created by the driver and may not be changed or modified.
-\end{command}
-
-\begin{command}{\pgfsys@use@id\marg{id}}
- ``Uses'' an id previously created using |\pgfsys@new@id|. This causes the
- \emph{next} graphic object to get the \meta{id} (not the current one). Once
- used, the id-type-pair becomes \emph{invalid} and will not be attached to
- any other graphics objects. It is, however, not an error to try this. If
- \meta{id} is empty, no id-type-pair is attached to the next object.
-\end{command}
-
-\begin{command}{\pgfsys@use@type\marg{type}}
- Changes the type used with the next graphic object. As mentioned earlier,
- the id assigned to the next object is actually a pair consisting of the
- currently used id and the currently used type.
-\end{command}
-
-\begin{command}{\pgfsys@append@type\marg{text}}
- Appends the \meta{text} to the current type.
-\end{command}
-
-\begin{command}{\pgfsys@push@type}
- Pushes the current type on a global ``stack of types'' without opening a
- \TeX\ scope. The is useful when you temporarily wish to change the type
- (for instance, by appending something to it), but you cannot create a new
- scope.
-\end{command}
-
-\begin{command}{\pgfsys@pop@type}
- Restores the most recently pushed type.
-\end{command}
-
-\begin{command}{\pgfsys@begin@idscope}
- Starts a (graphics) scope whose sole purpose is to assign it an
- id-type-pair so that it can be referenced later. Note that this command
- does not always produce a graphics scope: If not id is currently in use or
- if the id-type-pair has already been used, a graphic scope may or may not
- be created as defined by the driver (but always a \TeX\ scope). This allows
- drivers to minimize the number of graphic scopes created.
-
- When an id scope is created, any code that has been ``attached'' to it
- using |\pgfsys@attach@to@id| gets executed, see that command.
-
- Note that |\pgfsys@beginscope| does not use the current id-type-pair. You
- need to call this command to attach an id to a group.
-\end{command}
-
-\begin{command}{\pgfsys@end@idscope}
- Ends the graphics id scope started by |\pgfsys@end@idscope|. It must nest
- correctly with other graphic scopes and \TeX\ scopes.
-\end{command}
-
-\begin{command}{\pgfsys@attach@to@id\marg{id}\marg{type}\marg{begin code}\marg{end code}\marg{setup code}}
- Attaches codes to the \meta{id}-\meta{type}-pair, where \meta{id} must have
- been created using |\pgfsys@new@id|. The effect is that just before the id
- scope for this pair is created, the \meta{setup code} is executed, then the
- scope is started, then the \meta{begin code} is executed at the beginning,
- and, finally, \meta{end code} gets executed just before the scope ends.
- Multiple calls of this macro accumulated.
-\end{command}
-
-
-\subsection{Resource Description Framework Annotations (RDFa)}
-\label{section-sys-rdf}
-
-With certain output formats (in particular, with \textsc{svg}) you can insert
-annotations into the output file following the standard set by the
-\emph{resource description framework} (\textsc{rdf}), please consult the
-literature on \textsc{rdf} for an introduction to resource descriptions and
-ontologies.
-
-The support for \textsc{rdf} annotations works as follows in \pgfname: You use
-the following commands before you create an id scope (using
-|\pgfsys@begin@idscope|). Then the attributes set by the commands will be added
-as an annotation to that object. Here is an example:
-%
-\begin{codeexample}[code only]
-\pgfsys@rdf@resource{/fruits/apple}
-\pgfsys@begin@idscope
- ...
-\pgfsys@end@idscope
-\end{codeexample}
-
-If \textsc{svg} output is produced, this results in the following code in the
-\textsc{svg} file:
-%
-\begin{codeexample}[code only]
-<g resource="/fruits/apple">
- ...
-</g>
-\end{codeexample}
-
-Note that a call to |\pgfsys@begin@idscope| adds all the set attributes, but
-then clears the settings (globally). Thus, you should set all attributes more
-or less right before the id scope is created. For most of these command, if you
-call them multiple times before starting the id scope, the ``last call wins'',
-that is, later values overwrite earlier ones. In contrast, for the commands
-|\pgfsys@rdf@property|, |\pgfsys@rdf@rel|, |\pgfsys@rdf@rev|, as well as
-|\pgfsys@rdf@typeof|, the calls accumulate, that is, the texts passed in each
-call will all be added to the output, properly separated to form a list of
-values. Consider for instance:
-%
-\begin{codeexample}[code only]
-\pgfsys@rdf@resource{/fruits/apple}
-\pgfsys@rdf@resource{/fruits/watermelon}
-\pgfsys@rdf@property{http://foo.com/props/juicy}
-\pgfsys@rdf@property{http://foo.com/props/green}
-\pgfsys@begin@idscope
- ...
-\pgfsys@end@idscope
-\end{codeexample}
-
-In the resulting id scope, we will have:
-%
-\begin{codeexample}[code only]
-<g resource="/fruits/watermelon"
- property="http://foo.com/props/juicy http://foo.com/props/green">
- ...
-</g>
-\end{codeexample}
-
-\begin{command}{\pgfsys@rdf@about\marg{text}}
- Adds the \textsc{rdf} attribute |about="|\meta{text}|"| to the next id
- scope (please see the \textsc{rdf}a specification for details on the
- semantics of |about| in the context of the resource description framework).
-\end{command}
-
-The following commands work the same way as the above command, except that the
-set attribute is different. Please see the \textsc{rdf}a specification for
-details on these attributes. Note that the |\pgfsys@rdf@inlist| command is the
-only one that takes no argument.
-
-\begin{command}{\pgfsys@rdf@content\marg{text}}
-\end{command}
-
-\begin{command}{\pgfsys@rdf@datatype\marg{text}}
-\end{command}
-
-\begin{command}{\pgfsys@rdf@href\marg{text}}
-\end{command}
-
-\begin{command}{\pgfsys@rdf@inlist}
-\end{command}
-
-\begin{command}{\pgfsys@rdf@prefix\marg{text}}
-\end{command}
-
-\begin{command}{\pgfsys@rdf@property\marg{text}}
-\end{command}
-
-\begin{command}{\pgfsys@rdf@rel\marg{text}}
-\end{command}
-
-\begin{command}{\pgfsys@rdf@resource\marg{text}}
-\end{command}
-
-\begin{command}{\pgfsys@rdf@rev\marg{text}}
-\end{command}
-
-\begin{command}{\pgfsys@rdf@src\marg{text}}
-\end{command}
-
-\begin{command}{\pgfsys@rdf@typeof\marg{text}}
-\end{command}
-
-\begin{command}{\pgfsys@rdf@vocab\marg{text}}
-\end{command}
-
-
-\subsection{Reusable Objects System Commands}
-
-\begin{command}{\pgfsys@invoke\marg{literals}}
- This command gets protocolled literals and should insert them into the
- |.pdf| or |.dvi| file using an appropriate |\special|.
-\end{command}
-
-\begin{command}{\pgfsys@defobject\marg{name}\marg{lower left}\marg{upper right}\marg{code}}
- Declares an object for later use. The idea is that the object can be
- precached in some way and then be rendered more quickly when used several
- times. For example, an arrow head might be defined and prerendered in this
- way.
-
- The parameter \meta{name} is the name for later use. \meta{lower left} and
- \meta{upper right} are \pgfname\ points specifying a bounding box for the
- object. \meta{code} is the code for the object. The code should not be too
- fancy.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-\end{command}
-
-\begin{command}{\pgfsys@useobject\marg{name}\marg{extra code}}
- Renders a previously declared object. The first parameter is the name of
- the object. The second parameter is extra code that should be executed
- right \emph{before} the object is rendered. Typically, this will be some
- transformation code.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-\end{command}
-
-\begin{command}{\pgfsys@marker@declare\marg{macro}\marg{code}}
- Declares a \emph{marker} symbol for later use. The command is very similar
- to |\pgfsys@defobject|, but the use case is slightly different: The graphic
- object defined using the \meta{code} is stored in such a way that it can be
- used as an \emph{arrow tip marker symbol} in animations. The \meta{macro}
- is set to an identifier by which the marker can be referenced later on.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-\end{command}
-
-\begin{command}{\pgfsys@marker@use\marg{macro}}
- Adds the marker object referenced by the \meta{macro} to the current
- output.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-\end{command}
-
-
-\subsection{Invisibility System Commands}
-
-All drawing or stroking or text rendering between calls of the following
-commands should be suppressed. A similar effect can be achieved by clipping
-against an empty region, but the following commands do not open a graphics
-scope and can be opened and closed ``orthogonally'' to other scopes.
-
-\begin{command}{\pgfsys@begininvisible}
- Between this command and the closing |\pgfsys@endinvisible| all output
- should be suppressed. Nothing should be drawn at all, which includes all
- paths, images and shadings. However, no groups (neither \TeX\ groups nor
- graphic state groups) should be opened by this command.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-\begin{command}{\pgfsys@endinvisible}
- Ends the invisibility section, unless invisibility blocks have been nested.
- In this case, only the ``last'' one restores visibility.
-
- This command has a default implementation and need not be implemented by a
- driver file.
-
- This command is protocolled, see Section~\ref{section-protocols}.
-\end{command}
-
-
-\subsection{Page Size Commands}
-
-The following commands can be used to set the page size of a document in a
-``portable'' way. Note, however, that many packages also (try to) set the page
-size.
-
-These commands are typically not given inside a |{pgfpicture}|, but on the
-outer level of compilation.
-
-\begin{command}{\pgfsys@papersize\marg{width}\marg{height}}
- Inserts the necessary |\special|s for the current driver into the output
- stream to ``locally'' change the page size. Whether such a ``local'' change
- is possible depends strongly on the driver. For instance, |dvips| will
- honor the first call to this command that is part of the shipped-out
- document and will ignore all other uses. In contrast, |pdftex| will use the
- current value of the paper size for each page and, additionally, setting
- the papersize is local to the current \TeX\ group.
-\end{command}
-
-\begin{command}{\pgfsys@global@papersize\marg{width}\marg{height}}
- Like the previous command, only for drivers where setting the paper size
- parameters is a \TeX-group-local operation, |\global| is prefixed to the
- setting of the page sizes.
-\end{command}
-
-\begin{command}{\pgfsys@thepageheight}
- This macro expands to the current page's height, provided \LaTeX\ is used,
- otherwise a best guess is returned (currently just |\the\vsize|).
-\end{command}
-
-\begin{command}{\pgfsys@thepagewidth}
- As above.
-\end{command}
-
-
-\subsection{Position Tracking Commands}
-
-The following commands are used to determine the position of text on a page.
-This is a rather complicated process in general since at the moment when the
-text is read by \TeX, the final position cannot be determined, yet. For
-example, the text might be put in a box which is later put in the headline or
-perhaps in the footline or perhaps even on a different page.
-
-For these reasons, position tracking is typically a two-stage process. In a
-first stage you indicate that a certain position is of interest by
-\emph{marking} it. This will (depending on the details of the backend driver)
-cause page coordinates or this position to be written to an |.aux| file when
-the page is shipped. Possibly, the position might also be determined at an even
-later stage. Then, on a second run of \TeX, the position is read from the
-|.aux| file and can be used.
-
-\begin{command}{\pgfsys@markposition\marg{name}}
- Marks a position on the page. This command should be given while normal
- typesetting is done such as in
- %
-\begin{codeexample}[code only]
-The value of $x$ is \pgfsys@markposition{here}important.
-\end{codeexample}
- %
- It causes the position |here| to be saved when the page is shipped out.
-\end{command}
-
-\begin{command}{\pgfsys@getposition\marg{name}\marg{macro}}
- This command retrieves a position that has been marked on an earlier run of
- \TeX\ on the current file. The \meta{macro} must be a macro name such as
- |\mymacro|. It will be redefined such that it is
- %
- \begin{itemize}
- \item either just |\relax| or
- \item a |\pgfpoint...| command.
- \end{itemize}
- %
- The first case will happen when the position has not been marked at all or
- when the file is typeset for the first time, when the coordinates are not
- yet available.
-
- In the second case, executing \meta{macro} yields the position on the page
- that is to be interpreted as follows: A coordinate like
- |\pgfpoint{2cm}{3cm}| means ``2cm to the right and 3cm up from the origin
- of the page''. The position of the origin of the page is not guaranteed to
- be at the lower left corner, it is only guaranteed that all pictures on a
- page use the same origin.
-
- To determine the lower left corner of a page, you can call
- |\pgfsys@getposition| with \meta{name} set to the special name
- |pgfpageorigin|. By shifting all positions by the amount returned by this
- call you can position things absolutely on a page.
-
- \example Referencing a point of the page:
- %
-\begin{codeexample}[code only]
-The value of $x$ is \pgfsys@markposition{here}important.
-
-Lots of text.
-
-\hbox{\pgfsys@markposition{myorigin}%
-\begin{pgfpicture}
- % Switch of size protocol
- \pgfpathmoveto{\pgfpointorigin}
- \pgfusepath{use as bounding box}
-
- \pgfsys@getposition{here}{\hereposition}
- \pgfsys@getposition{myorigin}{\thispictureposition}
-
- \pgftransformshift{\pgfpointscale{-1}{\thispictureposition}}
- \pgftransformshift{\hereposition}
-
- \pgfpathcircle{\pgfpointorigin}{1cm}
- \pgfusepath{draw}
-\end{pgfpicture}}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Internal Conversion Commands}
-
-The system commands take \TeX\ dimensions as input, but the dimensions that
-have to be inserted into \pdf\ and PostScript files need to be dimensionless
-values that are interpreted as multiples of $\frac{1}{72}\mathrm{in}$. For
-example, the \TeX\ dimension $2bp$ should be inserted as |2| into a \pdf\ file
-and the \TeX\ dimension $10\mathrm{pt}$ as |9.9626401|. To make this conversion
-easier, the following command may be useful:
-
-\begin{command}{\pgf@sys@bp\marg{dimension}}
- Inserts how many multiples of $\frac{1}{72}\mathrm{in}$ the
- \meta{dimension} is into the current protocol stream (buffered).
-
- \example |\pgf@sys@bp{\pgf@x}| or |\pgf@sys@bp{1cm}|.
-\end{command}
-
-Note that this command is \emph{not} a system command that can/needs to be
-overwritten by a driver.
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-overview.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-overview.tex
deleted file mode 100644
index ae1875bb9b..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-overview.tex
+++ /dev/null
@@ -1,79 +0,0 @@
-% Copyright 2018 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{Design of the System Layer}
-
-\makeatletter
-
-\subsection{Driver Files}
-\label{section-pgfsys}
-
-The \pgfname\ system layer mainly consists of a large number of commands
-starting with |\pgfsys@|. These commands will be called \emph{system commands}
-in the following. The higher layers ``interface'' with the system layer by
-calling these commands. The higher layers should never use |\special| commands
-directly or even check whether |\pdfoutput| is defined. Instead, all drawing
-requests should be ``channeled'' through the system commands.
-
-The system layer is loaded and set up by the following package:
-
-\begin{package}{pgfsys}
- This file provides ``default implementations'' of all system commands, but
- most simply produce a warning that they are not implemented. The actual
- implementations of the system commands for a particular driver like, say,
- |pdftex| reside in files called |pgfsys-xxxx.sty|, where |xxxx| is the
- driver name. These will be called \emph{driver files} in the following.
-
- When |pgfsys.sty| is loaded, it will try to determine which driver is used
- by loading |pgf.cfg|. This file should set up the macro |\pgfsysdriver|
- appropriately. The |pgfsys.sty| will input the appropriate
- |pgfsys-|\meta{drivername}|.sty|.
-\end{package}
-
-\begin{command}{\pgfsysdriver}
- This macro should expand to the name of the driver to be used by |pgfsys|.
- The default from |pgf.cfg| is |pgfsys-\Gin@driver|. This is very likely to
- be correct if you are using \LaTeX. For plain \TeX, the macro will be set
- to |pgfsys-pdftex.def| if |pdftex| is used and to |pgfsys-dvips.def|
- otherwise.
-\end{command}
-
-\begin{filedescription}{pgf.cfg}
- This file should set up the command |\pgfsysdriver| correctly. If
- |\pgfsysdriver| is already set to some value, the driver normally should
- not change it. Otherwise, it should make a ``good guess'' at which driver
- will be appropriate.
-\end{filedescription}
-
-The currently supported backend drivers are discussed in
-Section~\ref{section-drivers}.
-
-
-\subsection{Common Definition Files}
-
-Some drivers share many |\pgfsys@| commands. For the reason, files defining
-these ``common'' commands are available. These files are \emph{not} usable
-alone.
-
-\begin{filedescription}{pgfsys-common-postscript}
- This file defines some |\pgfsys@| commands so that they produce appropriate
- PostScript code.
-\end{filedescription}
-
-\begin{filedescription}{pgfsys-common-pdf}
- This file defines some |\pgfsys@| commands so that they produce appropriate
- \textsc{pdf} code.
-\end{filedescription}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-paths.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-paths.tex
deleted file mode 100644
index cf34900220..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-paths.tex
+++ /dev/null
@@ -1,217 +0,0 @@
-% Copyright 2018 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{The Soft Path Subsystem}
-\label{section-soft-paths}
-
-\makeatletter
-
-This section describes a set of commands for creating \emph{soft paths} as
-opposed to the commands of the previous section, which created \emph{hard
-paths}. A soft path is a path that can still be ``changed'' or ``molded''. Once
-you (or the \pgfname\ system) is satisfied with a soft path, it is turned into
-a hard path, which can be inserted into the resulting |.pdf| or |.ps| file.
-
-Note that the commands described in this section are ``high-level'' in the
-sense that they are not implemented in driver files, but rather directly by the
-\pgfname-system layer. For this reason, the commands for creating soft paths do
-not start with |\pgfsys@|, but rather with |\pgfsyssoftpath@|. On the other
-hand, as a user you will never use these commands directly, they are described
-as part of the low-level interface.
-
-
-\subsection{Path Creation Process}
-
-When the user writes a command like |\draw (0bp,0bp) -- (10bp,0bp);| quite a
-lot happens behind the scenes:
-%
-\begin{enumerate}
- \item The frontend command is translated by \tikzname\ into commands of the
- basic layer. In essence, the command is translated to something like
- %
-\begin{codeexample}[code only]
-\pgfpathmoveto{\pgfpoint{0bp}{0bp}}
-\pgfpathlineto{\pgfpoint{10bp}{0bp}}
-\pgfusepath{stroke}
-\end{codeexample}
- %
- \item The |\pgfpathxxxx| commands do \emph{not} directly call ``hard''
- commands like |\pgfsys@xxxx|. Instead, the command |\pgfpathmoveto|
- invokes a special command called |\pgfsyssoftpath@moveto| and
- |\pgfpathlineto| invokes |\pgfsyssoftpath@lineto|.
-
- The |\pgfsyssoftpath@xxxx| commands, which are described below,
- construct a soft path. Each time such a command is used, special tokens
- are added to the end of an internal macro that stores the soft path
- currently being constructed.
- \item When the |\pgfusepath| is encountered, the soft path stored in the
- internal macro is ``invoked''. Only now does a special macro iterate
- over the soft path. For each line-to or move-to operation on this path
- it calls an appropriate |\pgfsys@moveto| or |\pgfsys@lineto| in order
- to, finally, create the desired hard path, namely, the string of
- literals in the |.pdf| or |.ps| file.
- \item After the path has been invoked, |\pgfsys@stroke| is called to insert
- the literal for stroking the path.
-\end{enumerate}
-
-Why such a complicated process? Why not have |\pgfpathlineto| directly call
-|\pgfsys@lineto| and be done with it? There are two reasons:
-%
-\begin{enumerate}
- \item The \pdf\ specification requires that a path is not interrupted by
- any non-path-construction commands. Thus, the following code will
- result in a corrupted |.pdf|:
- %
-\begin{codeexample}[code only]
-\pgfsys@moveto{0}{0}
-\pgfsys@setlinewidth{1}
-\pgfsys@lineto{10}{0}
-\pgfsys@stroke
-\end{codeexample}
- %
- Such corrupt code is \emph{tolerated} by most viewers, but not always.
- It is much better to create only (reasonably) legal code.
- \item A soft path can still be changed, while a hard path is fixed. For
- example, one can still change the starting and end points of a soft
- path or do optimizations on it. Such transformations are not possible
- on hard paths.
-\end{enumerate}
-
-
-\subsection{Starting and Ending a Soft Path}
-
-No special action must be taken in order to start the creation of a soft path.
-Rather, each time a command like |\pgfsyssoftpath@lineto| is called, a special
-token is added to the (global) current soft path being constructed.
-
-However, you can access and change the current soft path. In this way, it is
-possible to store a soft path, to manipulate it, or to invoke it.
-
-\begin{command}{\pgfsyssoftpath@getcurrentpath\marg{macro name}}
- This command will store the current soft path in \meta{macro name}.
-\end{command}
-
-\begin{command}{\pgfsyssoftpath@setcurrentpath\marg{macro name}}
- This command will set the current soft path to be the path stored in
- \meta{macro name}. This macro should store a path that has previously been
- extracted using the |\pgfsyssoftpath@getcurrentpath| command and has
- possibly been modified subsequently.
-\end{command}
-
-\begin{command}{\pgfsyssoftpath@invokecurrentpath}
- This command will turn the current soft path in a ``hard'' path. To do so,
- it iterates over the soft path and calls an appropriate |\pgfsys@xxxx|
- command for each element of the path. Note that the current soft path is
- \emph{not changed} by this command. Thus, in order to start a new soft path
- after the old one has been invoked and is no longer needed, you need to set
- the current soft path to be empty. This may seem strange, but it is often
- useful to immediately use the last soft path again.
-\end{command}
-
-\begin{command}{\pgfsyssoftpath@flushcurrentpath}
- This command will invoke the current soft path and then set it to be empty.
-\end{command}
-
-
-\subsection{Soft Path Creation Commands}
-
-\begin{command}{\pgfsyssoftpath@moveto\marg{x}\marg{y}}
- This command appends a ``move-to'' segment to the current soft path. The
- coordinates \meta{x} and \meta{y} are given as normal \TeX\ dimensions.
-
- \example One way to draw a line:
- %
-\begin{codeexample}[code only]
-\pgfsyssoftpath@moveto{0pt}{0pt}
-\pgfsyssoftpath@lineto{10pt}{10pt}
-\pgfsyssoftpath@flushcurrentpath
-\pgfsys@stroke
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfsyssoftpath@lineto\marg{x}\marg{y}}
- Appends a ``line-to'' segment to the current soft path.
-\end{command}
-
-\begin{command}{\pgfsyssoftpath@curveto\marg{a}\marg{b}\marg{c}\marg{d}\marg{x}\marg{y}}
- Appends a ``curve-to'' segment to the current soft path with controls
- $(a,b)$ and $(c,d)$.
-\end{command}
-
-\begin{command}{\pgfsyssoftpath@rect\marg{lower left x}\marg{lower left y}\marg{width}\marg{height}}
- Appends a rectangle segment to the current soft path.
-\end{command}
-
-\begin{command}{\pgfsyssoftpath@closepath}
- Appends a ``close-path'' segment to the current soft path.
-\end{command}
-
-
-\subsection{The Soft Path Data Structure}
-
-A soft path is stored in a standardized way, which makes it possible to modify
-it before it becomes ``hard''. Basically, a soft path is a long sequence of
-triples. Each triple starts with a \emph{token} that identifies what is going
-on. This token is followed by two dimensions in braces. For example, the
-following is a soft path that means ``the path starts at $(0\mathrm{bp},
-0\mathrm{bp})$ and then continues in a straight line to $(10\mathrm{bp},
-0\mathrm{bp})$''.
-%
-\begin{codeexample}[code only]
-\pgfsyssoftpath@movetotoken{0bp}{0bp}\pgfsyssoftpath@linetotoken{10bp}{0bp}
-\end{codeexample}
-
-A curve-to is hard to express in this way since we need six numbers to express
-it, not two. For this reasons, a curve-to is expressed using three triples as
-follows: The command
-%
-\begin{codeexample}[code only]
-\pgfsyssoftpath@curveto{1bp}{2bp}{3bp}{4bp}{5bp}{6bp}
-\end{codeexample}
-%
-\noindent results in the following three triples:
-%
-\begin{codeexample}[code only]
-\pgfsyssoftpath@curvetosupportatoken{1bp}{2bp}
-\pgfsyssoftpath@curvetosupportbtoken{3bp}{4bp}
-\pgfsyssoftpath@curvetotoken{5bp}{6bp}
-\end{codeexample}
-
-These three triples must always ``remain together''. Thus, a lonely
-|supportbtoken| is forbidden.
-
-In details, the following tokens exist:
-%
-\begin{itemize}
- \item \declare{|\pgfsyssoftpath@movetotoken|} indicates a move-to
- operation. The two following numbers indicate the position to which the
- current point should be moved.
- \item \declare{|\pgfsyssoftpath@linetotoken|} indicates a line-to
- operation.
- \item \declare{|\pgfsyssoftpath@curvetosupportatoken|} indicates the first
- control point of a curve-to operation. The triple must be followed by a
- |\pgfsyssoftpath@curvetosupportbtoken|.
- \item \declare{|\pgfsyssoftpath@curvetosupportbtoken|} indicates the second
- control point of a curve-to operation. The triple must be followed by a
- |\pgfsyssoftpath@curvetotoken|.
- \item \declare{|\pgfsyssoftpath@curvetotoken|} indicates the target of a
- curve-to operation.
- \item \declare{|\pgfsyssoftpath@rectcornertoken|} indicates the corner of a
- rectangle on the soft path. The triple must be followed by a
- |\pgfsyssoftpath@rectsizetoken|.
- \item \declare{|\pgfsyssoftpath@rectsizetoken|} indicates the size of a
- rectangle on the soft path.
- \item \declare{|\pgfsyssoftpath@closepath|} indicates that the subpath
- begun with the last move-to operation should be closed. The parameter
- numbers are currently not important, but if set to anything different
- from |{0pt}{0pt}|, they should be set to the coordinate of the original
- move-to operation to which the path ``returns'' now.
-\end{itemize}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-protocol.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-protocol.tex
deleted file mode 100644
index 30a1d79cee..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-pgfsys-protocol.tex
+++ /dev/null
@@ -1,89 +0,0 @@
-% Copyright 2018 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{The Protocol Subsystem}
-\label{section-protocols}
-
-\makeatletter
-
-This section describes commands for \emph{protocolling} literal text created by
-\pgfname. The idea is that some literal text, like the string of commands used
-to draw an arrow head, will be used over and over again in a picture. It is
-then much more efficient to compute the necessary literal text just once and to
-quickly insert it ``in a single sweep''.
-
-When protocolling is ``switched on'', there is a ``current protocol'' to which
-literal text gets appended. Once all commands that needed to be protocolled
-have been issued, the protocol can be obtained and stored using
-|\pgfsysprotocol@getcurrentprotocol|. At any point, the current protocol can be
-changed using a corresponding setting command. Finally,
-|\pgfsysprotocol@invokecurrentprotocol| is used to insert the protocolled
-commands into the |.pdf| or |.dvi| file.
-
-Only those |\pgfsys@| commands can be protocolled that use the command
-|\pgfsysprotocol@literal| internally. For example, the definition of
-|\pgfsys@moveto| in |pgfsys-common-pdf.def| is
-%
-\begin{codeexample}[code only]
-\def\pgfsys@moveto#1#2{\pgfsysprotocol@literal{#1 #2 m}}
-\end{codeexample}
-%
-All ``normal'' system-level commands can be protocolled. However, commands for
-creating or invoking shadings, images, or whole pictures require special
-|\special|'s and cannot be protocolled.
-
-\begin{command}{\pgfsysprotocol@literalbuffered\marg{literal text}}
- Adds the \meta{literal text} to the current protocol, after it has been
- ``|\edef|ed''. This command will always be protocolled.
-\end{command}
-
-\begin{command}{\pgfsysprotocol@literal\marg{literal text}}
- First calls |\pgfsysprotocol@literalbuffered| on \meta{literal text}. Then,
- if protocolling is currently switched off, the \meta{literal text} is
- passed on to |\pgfsys@invoke|.
-\end{command}
-
-\begin{command}{\pgfsysprotocol@bufferedtrue}
- Turns on protocolling. All subsequent calls of |\pgfsysprotocol@literal|
- will append their argument to the current protocol.
-\end{command}
-
-\begin{command}{\pgfsysprotocol@bufferedfalse}
- Turns off protocolling. Subsequent calls of |\pgfsysprotocol@literal|
- directly insert their argument into the current |.pdf| or |.ps|.
-
- Note that if the current protocol is not empty when protocolling is
- switched off, the next call to |\pgfsysprotocol@literal| will first flush
- the current protocol, that is, insert it into the file.
-\end{command}
-
-\begin{command}{\pgfsysprotocol@getcurrentprotocol\marg{macro name}}
- Stores the current protocol in \meta{macro name} for later use.
-\end{command}
-
-\begin{command}{\pgfsysprotocol@setcurrentprotocol\marg{macro name}}
- Sets the current protocol to \meta{macro name}.
-\end{command}
-
-\begin{command}{\pgfsysprotocol@invokecurrentprotocol}
- Inserts the text stored in the current protocol into the |.pdf| or |.dvi|
- file. This does \emph{not} change the current protocol.
-\end{command}
-
-\begin{command}{\pgfsysprotocol@flushcurrentprotocol}
- First inserts the current protocol, then sets the current protocol to the
- empty string.
-\end{command}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-actions.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-actions.tex
deleted file mode 100644
index 2cd528bfa2..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-actions.tex
+++ /dev/null
@@ -1,1449 +0,0 @@
-% 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{Actions on Paths}
-
-\subsection{Overview}
-
-Once a path has been constructed, different things can be done with it. It can
-be drawn (or stroked) with a ``pen'', it can be filled with a color or shading,
-it can be used for clipping subsequent drawing, it can be used to specify the
-extend of the picture -- or any combination of these actions at the same time.
-
-To decide what is to be done with a path, two methods can be used. First, you
-can use a special-purpose command like |\draw| to indicate that the path should
-be drawn. However, commands like |\draw| and |\fill| are just abbreviations for
-special cases of the more general method: Here, the |\path| command is used to
-specify the path. Then, options encountered on the path indicate what should be
-done with the path.
-
-For example, |\path (0,0) circle (1cm);| means: ``This is a path consisting of
-a circle around the origin. Do not do anything with it (throw it away).''
-However, if the option |draw| is encountered anywhere on the path, the circle
-will be drawn. ``Anywhere'' is any point on the path where an option can be
-given, which is everywhere where a path command like |circle (1cm)| or
-|rectangle (1,1)| or even just |(0,0)| would also be allowed. Thus, the
-following commands all draw the same circle:
-%
-\begin{codeexample}[code only]
-\path [draw] (0,0) circle (1cm);
-\path (0,0) [draw] circle (1cm);
-\path (0,0) circle (1cm) [draw];
-\end{codeexample}
-%
-Finally, |\draw (0,0) circle (1cm);| also draws a path, because |\draw| is an
-abbreviation for |\path [draw]| and thus the command expands to the first line
-of the above example.
-
-Similarly, |\fill| is an abbreviation for |\path[fill]| and |\filldraw| is an
-abbreviation for the command |\path[fill,draw]|. Since options accumulate, the
-following commands all have the same effect:
-%
-\begin{codeexample}[code only]
-\path [draw,fill] (0,0) circle (1cm);
-\path [draw] [fill] (0,0) circle (1cm);
-\path [fill] (0,0) circle (1cm) [draw];
-\draw [fill] (0,0) circle (1cm);
-\fill (0,0) [draw] circle (1cm);
-\filldraw (0,0) circle (1cm);
-\end{codeexample}
-
-In the following subsection the different actions that can be performed on a
-path are explained. The following commands are abbreviations for certain sets
-of actions, but for many useful combinations there are no abbreviations:
-
-\begin{command}{\draw}
- Inside |{tikzpicture}| this is an abbreviation for |\path[draw]|.
-\end{command}
-
-\begin{command}{\fill}
- Inside |{tikzpicture}| this is an abbreviation for |\path[fill]|.
-\end{command}
-
-\begin{command}{\filldraw}
- Inside |{tikzpicture}| this is an abbreviation for |\path[fill,draw]|.
-\end{command}
-
-\begin{command}{\pattern}
- Inside |{tikzpicture}| this is an abbreviation for |\path[pattern]|.
-\end{command}
-
-\begin{command}{\shade}
- Inside |{tikzpicture}| this is an abbreviation for |\path[shade]|.
-\end{command}
-
-\begin{command}{\shadedraw}
- Inside |{tikzpicture}| this is an abbreviation for |\path[shade,draw]|.
-\end{command}
-
-\begin{command}{\clip}
- Inside |{tikzpicture}| this is an abbreviation for |\path[clip]|.
-\end{command}
-
-\begin{command}{\useasboundingbox}
- Inside |{tikzpicture}| this is an abbreviation for |\path[use as bounding box]|.
-\end{command}
-
-
-\subsection{Specifying a Color}
-
-The most unspecific option for setting colors is the following:
-%
-\begin{key}{/tikz/color=\meta{color name}}
- \indexoption{color option}%
- This option sets the color that is used for fill, drawing, and text inside
- the current scope. Any special settings for filling colors or drawing
- colors are immediately ``overruled'' by this option.
-
- The \meta{color name} is the name of a previously defined color. For
- \LaTeX\ users, this is just a normal ``\LaTeX-color'' and the |xcolor|
- extensions are allowed. Here is an example:
- %
-\begin{codeexample}[]
-\tikz \fill[color=red!20] (0,0) circle (1ex);
-\end{codeexample}
-
- It is possible to ``leave out'' the |color=| part and you can also write:
- %
-\begin{codeexample}[]
-\tikz \fill[red!20] (0,0) circle (1ex);
-\end{codeexample}
- %
- What happens is that every option that \tikzname\ does not know, like
- |red!20|, gets a ``second chance'' as a color name.
-
- For plain \TeX\ users, it is not so easy to specify colors since plain
- \TeX\ has no ``standardized'' color naming mechanism. Because of this,
- \pgfname\ emulates the |xcolor| package, though the emulation is
- \emph{extremely basic} (more precisely, what I could hack together in two
- hours or so). The emulation allows you to do the following:
- %
- \begin{itemize}
- \item Specify a new color using |\definecolor|. Only the color models
- |gray|, |rgb|, and |RGB| are supported\footnote{Con\TeX t users
- should be aware that \texttt{\textbackslash definecolor} has a
- different meaning in Con\TeX t. There is a low-level equivalent
- named \texttt{\textbackslash pgfutil@definecolor} which can be
- used instead.}.
- %
- \example |\definecolor{orange}{rgb}{1,0.5,0}|
- \item Use |\colorlet| to define a new color based on an old one.
- Here, the |!| mechanism is supported, though only ``once'' (use
- multiple |\colorlet| for more fancy colors).
- %
- \example |\colorlet{lightgray}{black!25}|
- \item Use |\color|\marg{color name} to set the color in the current
- \TeX\ group. |\aftergroup|-hackery is used to restore the color
- after the group.
- \end{itemize}
-\end{key}
-
-As pointed out above, the |color=| option applies to ``everything'' (except to
-shadings), which is not always what you want. Because of this, there are
-several more specialized color options. For example, the |draw=| option sets
-the color used for drawing, but does not modify the color used for filling.
-These color options are documented where the path action they influence is
-described.
-
-
-\subsection{Drawing a Path}
-
-You can draw a path using the following option:
-%
-\begin{key}{/tikz/draw=\meta{color} (default \normalfont is scope's color setting)}
- Causes the path to be drawn. ``Drawing'' (also known as ``stroking'') can
- be thought of as picking up a pen and moving it along the path, thereby
- leaving ``ink'' on the canvas.
-
- There are numerous parameters that influence how a line is drawn, like the
- thickness or the dash pattern. These options are explained below.
-
- If the optional \meta{color} argument is given, drawing is done using the
- given \meta{color}. This color can be different from the current filling
- color, which allows you to draw and fill a path with different colors. If
- no \meta{color} argument is given, the last usage of the |color=| option is
- used.
-
- If the special color name |none| is given, this option causes drawing to be
- ``switched off''. This is useful if a style has previously switched on
- drawing and you locally wish to undo this effect.
-
- Although this option is normally used on paths to indicate that the path
- should be drawn, it also makes sense to use the option with a |{scope}| or
- |{tikzpicture}| environment. However, this will \emph{not} cause all paths
- to be drawn. Instead, this just sets the \meta{color} to be used for
- drawing paths inside the environment.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \path[draw=red] (0,0) -- (1,1) -- (2,1) circle (10pt);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-The following subsections list the different options that influence how a path
-is drawn. All of these options only have an effect if the |draw| option is
-given (directly or indirectly).
-
-
-\subsubsection{Graphic Parameters: Line Width, Line Cap, and Line Join}
-\label{section-cap-joins}
-
-\begin{key}{/tikz/line width=\meta{dimension} (initially 0.4pt)}
- Specifies the line width. Note the space.
- %
-\begin{codeexample}[]
- \tikz \draw[line width=5pt] (0,0) -- (1cm,1.5ex);
-\end{codeexample}
- %
-\end{key}
-
-There are a number of predefined styles that provide more ``natural'' ways of
-setting the line width. You can also redefine these styles.
-
-\begin{stylekey}{/tikz/ultra thin}
- Sets the line width to 0.1pt.
- %
-\begin{codeexample}[]
- \tikz \draw[ultra thin] (0,0) -- (1cm,1.5ex);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/very thin}
- Sets the line width to 0.2pt.
- %
-\begin{codeexample}[]
- \tikz \draw[very thin] (0,0) -- (1cm,1.5ex);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/thin}
- Sets the line width to 0.4pt.
- %
-\begin{codeexample}[]
- \tikz \draw[thin] (0,0) -- (1cm,1.5ex);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/semithick}
- Sets the line width to 0.6pt.
- %
-\begin{codeexample}[]
- \tikz \draw[semithick] (0,0) -- (1cm,1.5ex);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/thick}
- Sets the line width to 0.8pt.
- %
-\begin{codeexample}[]
- \tikz \draw[thick] (0,0) -- (1cm,1.5ex);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/very thick}
- Sets the line width to 1.2pt.
- %
-\begin{codeexample}[]
- \tikz \draw[very thick] (0,0) -- (1cm,1.5ex);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/ultra thick}
- Sets the line width to 1.6pt.
- %
-\begin{codeexample}[]
- \tikz \draw[ultra thick] (0,0) -- (1cm,1.5ex);
-\end{codeexample}
- %
-\end{stylekey}
-
- \label{section-line-cap}
-\begin{key}{/tikz/line cap=\meta{type} (initially butt)}
- Specifies how lines ``end''. Permissible \meta{type} are |round|, |rect|,
- and |butt|. They have the following effects:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \begin{scope}[line width=10pt]
- \draw[line cap=round] (0,1 ) -- +(1,0);
- \draw[line cap=butt] (0,.5) -- +(1,0);
- \draw[line cap=rect] (0,0 ) -- +(1,0);
- \end{scope}
- \draw[white,line width=1pt]
- (0,0 ) -- +(1,0) (0,.5) -- +(1,0) (0,1 ) -- +(1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/line join=\meta{type} (initially miter)}
- Specifies how lines ``join''. Permissible \meta{type} are |round|, |bevel|,
- and |miter|. They have the following effects:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[line width=10pt]
- \draw[line join=round] (0,0) -- ++(.5,1) -- ++(.5,-1);
- \draw[line join=bevel] (1.25,0) -- ++(.5,1) -- ++(.5,-1);
- \draw[line join=miter] (2.5,0) -- ++(.5,1) -- ++(.5,-1);
- \useasboundingbox (0,1.5); % enlarge bounding box
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{key}{/tikz/miter limit=\meta{factor} (initially 10)}
- When you use the miter join and there is a very sharp corner (a small
- angle), the miter join may protrude very far over the actual joining
- point. In this case, if it were to protrude by more than \meta{factor}
- times the line width, the miter join is replaced by a bevel join.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[line width=5pt]
- \draw (0,0) -- ++(5,.5) -- ++(-5,.5);
- \draw[miter limit=25] (6,0) -- ++(5,.5) -- ++(-5,.5);
- \useasboundingbox (14,0); % make bounding box bigger
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{key}
-
-
-\subsubsection{Graphic Parameters: Dash Pattern}
-
-\begin{key}{/tikz/dash pattern=\meta{dash pattern}}
- Sets the dashing pattern. The syntax is the same as in \textsc{metafont}.
- For example following pattern |on 2pt off 3pt on 4pt off 4pt| means ``draw
- 2pt, then leave out 3pt, then draw 4pt once more, then leave out 4pt again,
- repeat''.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[dash pattern=on 2pt off 3pt on 4pt off 4pt]
- \draw (0pt,0pt) -- (3.5cm,0pt);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/dash phase=\meta{dash phase} (initially 0pt)}
- Shifts the start of the dash pattern by \meta{phase}.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[dash pattern=on 20pt off 10pt]
- \draw[dash phase=0pt] (0pt,3pt) -- (3.5cm,3pt);
- \draw[dash phase=10pt] (0pt,0pt) -- (3.5cm,0pt);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/dash=\meta{dash pattern}|phase|\meta{dash phase}}
- Sets the dashing pattern and phase at the same time.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw [dash=on 20pt off 10pt phase 0pt] (0pt,3pt) -- (3.5cm,3pt);
- \draw [dash=on 20pt off 10pt phase 10pt] (0pt,0pt) -- (3.5cm,0pt);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/dash expand off}
- Makes the |off| part of a dash pattern expandable such that it can stretch.
- This only works when there is a single |on| and a single |off| field and
- requires the |decorations| library. Right now this option has to be
- specified on the path where it is supposed to take effect after the
- |dash pattern| option because the dash pattern has to be known at the point
- where it is applied.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations}}]
-\begin{tikzpicture}[|-|, dash pattern=on 4pt off 2pt]
- \draw [dash expand off] (0pt,30pt) -- (26pt,30pt);
- \draw [dash expand off] (0pt,20pt) -- (24pt,20pt);
- \draw [dash expand off] (0pt,10pt) -- (22pt,10pt);
- \draw [dash expand off] (0pt, 0pt) -- (20pt, 0pt);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-As for the line thickness, some predefined styles allow you to set the dashing
-conveniently.
-
-\begin{stylekey}{/tikz/solid}
- Shorthand for setting a solid line as ``dash pattern''. This is the default.
- %
-\begin{codeexample}[]
-\tikz \draw[solid] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/dotted}
- Shorthand for setting a dotted dash pattern.
- %
-\begin{codeexample}[]
-\tikz \draw[dotted] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/densely dotted}
- Shorthand for setting a densely dotted dash pattern.
- %
-\begin{codeexample}[]
-\tikz \draw[densely dotted] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/loosely dotted}
- Shorthand for setting a loosely dotted dash pattern.
- %
-\begin{codeexample}[]
-\tikz \draw[loosely dotted] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/dashed}
- Shorthand for setting a dashed dash pattern.
- %
-\begin{codeexample}[]
-\tikz \draw[dashed] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/densely dashed}
- Shorthand for setting a densely dashed dash pattern.
- %
-\begin{codeexample}[]
-\tikz \draw[densely dashed] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/loosely dashed}
- Shorthand for setting a loosely dashed dash pattern.
- %
-\begin{codeexample}[]
-\tikz \draw[loosely dashed] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/dash dot}
- Shorthand for setting a dashed and dotted dash pattern.
- %
-\begin{codeexample}[]
-\tikz \draw[dash dot] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/densely dash dot}
- Shorthand for setting a densely dashed and dotted dash pattern.
- %
-\begin{codeexample}[]
-\tikz \draw[densely dash dot] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/loosely dash dot}
- Shorthand for setting a loosely dashed and dotted dash pattern.
- %
-\begin{codeexample}[]
-\tikz \draw[loosely dash dot] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/dash dot dot}
- Shorthand for setting a dashed and dotted dash pattern with more dots.
- %
-\begin{codeexample}[]
-\tikz \draw[dash dot dot] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/densely dash dot dot}
- Shorthand for setting a densely dashed and dotted dash pattern with more dots.
- %
-\begin{codeexample}[]
-\tikz \draw[densely dash dot dot] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/loosely dash dot dot}
- Shorthand for setting a loosely dashed and dotted dash pattern with more dots.
- %
-\begin{codeexample}[]
-\tikz \draw[loosely dash dot dot] (0pt,0pt) -- (50pt,0pt);
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsubsection{Graphic Parameters: Draw Opacity}
-
-When a line is drawn, it will normally ``obscure'' everything behind it as if
-you had used perfectly opaque ink. It is also possible to ask \tikzname\ to use
-an ink that is a little bit (or a big bit) transparent using the |draw opacity|
-option. This is explained in Section~\ref{section-tikz-transparency} on
-transparency in more detail.
-
-
-\subsubsection{Graphic Parameters: Double Lines and Bordered Lines}
-
-\begin{key}{/tikz/double=\meta{core color} (default white)}
- This option causes ``two'' lines to be drawn instead of a single one.
- However, this is not what really happens. In reality, the path is drawn
- twice. First, with the normal drawing color, secondly with the \meta{core
- color}, which is normally |white|. Upon the second drawing, the line width
- is reduced. The net effect is that it appears as if two lines had been
- drawn and this works well even with complicated, curved paths:
- %
-\begin{codeexample}[]
-\tikz \draw[double]
- plot[smooth cycle] coordinates{(0,0) (1,1) (1,0) (0,1)};
-\end{codeexample}
-
- You can also use the doubling option to create an effect in which a line
- seems to have a certain ``border'':
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) -- (1,1);
- \draw[draw=white,double=red,very thick] (0,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/double distance=\meta{dimension} (initially 0.6pt)}
- Sets the distance the ``two'' lines are spaced apart. In reality, this is
- the thickness of the line that is used to draw the path for the second
- time. The thickness of the \emph{first} time the path is drawn is twice the
- normal line width plus the given \meta{dimension}. As a side-effect, this
- option ``selects'' the |double| option.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[very thick,double] (0,0) arc (180:90:1cm);
- \draw[very thick,double distance=2pt] (1,0) arc (180:90:1cm);
- \draw[thin,double distance=2pt] (2,0) arc (180:90:1cm);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/double distance between line centers=\meta{dimension}}
- This option works like |double distance|, only the distance is not the
- distance between (inner) borders of the two main lines, but between their
- centers. Thus, the thickness the \emph{first} time the path is drawn is the
- normal line width plus the given \meta{dimension}, while the line width of
- the \emph{second} line that is drawn is \meta{dimension} minus the normal
- line width. As a side-effect, this option ``selects'' the |double| option.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[double distance between line centers=3pt]
- \foreach \lw in {0.5,1,1.5,2,2.5}
- \draw[line width=\lw pt,double] (\lw,0) -- ++(4mm,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[double distance=3pt]
- \foreach \lw in {0.5,1,1.5,2,2.5}
- \draw[line width=\lw pt,double] (\lw,0) -- ++(4mm,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{stylekey}{/tikz/double equal sign distance}
- This style selects a double line distance such that it corresponds to the
- distance of the two lines in an equal sign.
- %
-\begin{codeexample}[
- preamble={\usepackage{amsmath}
-\usetikzlibrary{arrows.meta}}
-]
-\Huge $=\implies$\tikz[baseline,double equal sign distance]
- \draw[double,thick,-{Implies[]}](0,0.55ex) --++(3ex,0);
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usepackage{amsmath}
-\usetikzlibrary{arrows.meta}}
-]
-\normalsize $=\implies$\tikz[baseline,double equal sign distance]
- \draw[double,-{Implies[]}](0,0.6ex) --++(3ex,0);
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usepackage{amsmath}
-\usetikzlibrary{arrows.meta}}
-]
-\tiny $=\implies$\tikz[baseline,double equal sign distance]
- \draw[double,very thin,-{Implies[]}](0,0.5ex) -- ++(3ex,0);
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsection{Adding Arrow Tips to a Path}
-\label{section-arrow-tip-action}
-
-In different situations, \tikzname\ will add arrow tips to the end of a path.
-For this to happen, a number of different things need to be specified:
-%
-\begin{enumerate}
- \item You must have used the |arrows| key, explained in detail in
- Section~\ref{section-tikz-arrows}, to setup which kinds of arrow tips
- you would like.
- \item The path may not be closed (like a circle or a rectangle) and, if
- it consists of several subpaths, further restrictions apply as
- explained in Section~\ref{section-tikz-arrows}.
- \item The |tips| key must be set to an appropriate value, see
- Section~\ref{section-tikz-arrows} once more.
-\end{enumerate}
-
-For the current section on paths, it is only important that when you add the
-|tips| option to a path that is not drawn, arrow tips will still be added at
-the beginning and at the end of the current path. This is true even when
-``only'' arrow tips get drawn for a path without drawing the path itself. Here
-is an example:
-%
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{arrows.meta,bending}}]
-\tikz \path[tips, -{Latex[open,length=10pt,bend]}] (0,0) to[bend left] (1,0);
-\end{codeexample}
-%
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{arrows.meta,bending}}]
-\tikz \draw[tips, -{Latex[open,length=10pt,bend]}] (0,0) to[bend left] (1,0);
-\end{codeexample}
-
-
-\subsection{Filling a Path}
-\label{section-rules}
-
-To fill a path, use the following option:
-%
-\begin{key}{/tikz/fill=\meta{color} (default \normalfont is scope's color setting)}
- This option causes the path to be filled. All unclosed parts of the path
- are first closed, if necessary. Then, the area enclosed by the path is
- filled with the current filling color, which is either the last color set
- using the general |color=| option or the optional color \meta{color}. For
- self-intersection paths and for paths consisting of several closed areas,
- the ``enclosed area'' is somewhat complicated to define and two different
- definitions exist, namely the nonzero winding number rule and the even odd
- rule, see the explanation of these options, below.
-
- Just as for the |draw| option, setting \meta{color} to |none| disables
- filling locally.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \fill (0,0) -- (1,1) -- (2,1);
- \fill (4,0) circle (.5cm) (4.5,0) circle (.5cm);
- \fill[even odd rule] (6,0) circle (.5cm) (6.5,0) circle (.5cm);
- \fill (8,0) -- (9,1) -- (10,0) circle (.5cm);
-\end{tikzpicture}
-\end{codeexample}
-
- If the |fill| option is used together with the |draw| option (either
- because both are given as options or because a |\filldraw| command is
- used), the path is filled \emph{first}, then the path is drawn
- \emph{second}. This is especially useful if different colors are selected
- for drawing and for filling. Even if the same color is used, there is a
- difference between this command and a plain |fill|: A ``filldrawn'' area
- will be slightly larger than a filled area because of the thickness of the
- ``pen''.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[fill=yellow!80!black,line width=5pt]
- \filldraw (0,0) -- (1,1) -- (2,1);
- \filldraw (4,0) circle (.5cm) (4.5,0) circle (.5cm);
- \filldraw[even odd rule] (6,0) circle (.5cm) (6.5,0) circle (.5cm);
- \filldraw (8,0) -- (9,1) -- (10,0) circle (.5cm);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Graphic Parameters: Fill Pattern}
-\label{section-fill-pattern}
-
-Instead of filling a path with a single solid color, it is also possible to
-fill it with a \emph{tiling pattern}. Imagine a small tile that contains a
-simple picture like a star. Then these tiles are (conceptually) repeated
-infinitely in all directions, but clipped against the path.
-
-Tiling patterns come in two variants: \emph{inherently colored patterns} and
-\emph{form-only patterns}. An inherently colored pattern is, say, a red star
-with a black border and will always look like this. A form-only pattern may
-have a different color each time it is used, only the form of the pattern will
-stay the same. As such, form-only patterns do not have any colors of their own,
-but when it is used the current \emph{pattern color} is used as its color.
-
-Patterns are not overly flexible. In particular, it is not possible to change
-the size or orientation of a pattern without declaring a new pattern. For
-complicated cases, it may be easier to use two nested |\foreach| statements to
-simulate a pattern, but patterns are rendered \emph{much} more quickly than
-simulated ones.
-
-\begin{key}{/tikz/pattern=\meta{name} (default \normalfont is scope's pattern)}
- This option causes the path to be filled with a pattern. If the \meta{name}
- is given, this pattern is used, otherwise the pattern set in the enclosing
- scope is used. As for the |draw| and |fill| options, setting \meta{name} to
- |none| disables filling locally.
-
- The pattern works like a fill color. In particular, setting a new fill
- color will fill the path with a solid color once more.
-
- Strangely, no \meta{name}s are permissible by default. You need to load for
- instance the |patterns| library, see
- Section~\ref{section-library-patterns}, to install predefined patterns.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
-\begin{tikzpicture}
- \draw[pattern=dots] (0,0) circle (1cm);
- \draw[pattern=fivepointed stars] (0,0) rectangle (3,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/pattern color=\meta{color}}
- This option is used to set the color to be used for form-only patterns.
- This option has no effect on inherently colored patterns.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
-\begin{tikzpicture}
- \draw[pattern color=red,pattern=fivepointed stars] (0,0) circle (1cm);
- \draw[pattern color=blue,pattern=fivepointed stars] (0,0) rectangle (3,1);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
-\begin{tikzpicture}
- \def\mypath{(0,0) -- +(0,1) arc (180:0:1.5cm) -- +(0,-1)}
- \fill [red] \mypath;
- \pattern[pattern color=white,pattern=bricks] \mypath;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Graphic Parameters: Interior Rules}
-
-The following two options can be used to decide how interior points should be
-determined:
-%
-\begin{key}{/tikz/nonzero rule}
- If this rule is used (which is the default), the following method is used
- to determine whether a given point is ``inside'' the path: From the point,
- shoot a ray in some direction towards infinity (the direction is chosen
- such that no strange borderline cases occur). Then the ray may hit the
- path. Whenever it hits the path, we increase or decrease a counter, which
- is initially zero. If the ray hits the path as the path goes ``from left to
- right'' (relative to the ray), the counter is increased, otherwise it is
- decreased. Then, at the end, we check whether the counter is nonzero (hence
- the name). If so, the point is deemed to lie ``inside'', otherwise it is
- ``outside''. Sounds complicated? It is.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \filldraw[fill=yellow!80!black]
- % Clockwise rectangle
- (0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle
- % Counter-clockwise rectangle
- (0.25,0.25) -- (0.75,0.25) -- (0.75,0.75) -- (0.25,0.75) -- cycle;
-
- \draw[->] (0,1) -- (.4,1);
- \draw[->] (0.75,0.75) -- (0.3,.75);
-
- \draw[->] (0.5,0.5) -- +(0,1) node[above] {crossings: $-1+1 = 0$};
-
- \begin{scope}[yshift=-3cm]
- \filldraw[fill=yellow!80!black]
- % Clockwise rectangle
- (0,0) -- (0,1) -- (1,1) -- (1,0) -- cycle
- % Clockwise rectangle
- (0.25,0.25) -- (0.25,0.75) -- (0.75,0.75) -- (0.75,0.25) -- cycle;
-
- \draw[->] (0,1) -- (.4,1);
- \draw[->] (0.25,0.75) -- (0.4,.75);
-
- \draw[->] (0.5,0.5) -- +(0,1) node[above] {crossings: $1+1 = 2$};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/even odd rule}
- This option causes a different method to be used for determining the inside
- and outside of paths. While it is less flexible, it turns out to be more
- intuitive.
-
- With this method, we also shoot rays from the point for which we wish to
- determine whether it is inside or outside the filling area. However, this
- time we only count how often we ``hit'' the path and declare the point to
- be ``inside'' if the number of hits is odd.
-
- Using the even-odd rule, it is easy to ``drill holes'' into a path.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \filldraw[fill=yellow!80!black,even odd rule]
- (0,0) rectangle (1,1) (0.5,0.5) circle (0.4cm);
- \draw[->] (0.5,0.5) -- +(0,1) [above] node{crossings: $1+1 = 2$};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Graphic Parameters: Fill Opacity}
-\label{section-fill-opacity}
-
-Analogously to the |draw opacity|, you can also set the fill opacity. Please
-see Section~\ref{section-tikz-transparency} for more details.
-
-
-\subsection{Generalized Filling: Using Arbitrary Pictures to Fill a Path}
-
-Sometimes you wish to ``fill'' a path with something even more complicated than
-a pattern, let alone a single color. For instance, you might wish to use an
-image to fill the path or some other, complicated drawing. In principle, this
-effect can be achieved by first using the path for clipping and then,
-subsequently, drawing the desired image or picture. However, there is an option
-that makes this process much easier:
-
-\begin{key}{/tikz/path picture=\meta{code}}
- When this option is given on a path and when the \meta{code} is not empty,
- the following happens: After all other ``filling'' operations are done with
- the path, which are caused by the options |fill|, |pattern| and |shade|, a
- local scope is opened and the path is temporarily installed as a clipping
- path. Then, the \meta{code} is executed, which can now draw something.
- Then, the local scope ends and, possibly, the path is stroked, provided the
- |draw| option has been given.
-
- As with other keys like |fill| or |draw| this option needs to be given on a
- path, setting the |path picture| outside a path has no effect (the path
- picture is cleared at the beginning of each path).
-
- The \meta{code} can be any normal \tikzname\ code like |\draw ...| or
- |\node ...|. As always, when you include an external graphic, you need to
- put it inside a |\node|.
-
- Note that no special actions are taken to transform the origin in any way.
- This means that the coordinate |(0,0)| is still where is was when the path
- was being constructed and not -- as one might expect -- at the lower left
- corner of the path. However, you can use the following special node to
- access the size of the path:
- %
- \begin{predefinednode}{path picture bounding box}
- This node is of shape |rectangle|. Its size and position are those of
- |current path bounding box| just before the \meta{code} of the path
- picture started to be executed. The \meta{code} can construct its own
- paths, so accessing the |current path bounding box| inside the
- \meta{code} yields the bounding box of any path that is currently being
- constructed inside the \meta{code}.
- \end{predefinednode}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- \filldraw [fill=blue!10,draw=blue,thick] (1.5,1) circle (1)
- [path picture={
- \node at (path picture bounding box.center) {
- This is a long text.
- };}
- ];
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[cross/.style={path picture={
- \draw[black]
- (path picture bounding box.south east) --
- (path picture bounding box.north west)
- (path picture bounding box.south west) --
- (path picture bounding box.north east);
- }}]
- \draw [help lines] (0,0) grid (3,2);
- \filldraw [cross,fill=blue!10,draw=blue,thick] (1,1) circle (1);
- \path [cross,top color=red,draw=red,thick] (2,0) -- (3,2) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
- \begin{tikzpicture}[path image/.style={
- path picture={
- \node at (path picture bounding box.center) {
- \includegraphics[height=3cm]{#1}
- };}}]
- \draw [help lines] (0,0) grid (3,2);
-
- \draw [path image=brave-gnu-world-logo,draw=blue,thick]
- (0,1) circle (1);
- \draw [path image=brave-gnu-world-logo,draw=red,very thick,->]
- (1,0) parabola[parabola height=2cm] (3,0);
-
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Shading a Path}
-
-You can shade a path using the |shade| option. A shading is like a filling,
-only the shading changes its color smoothly from one color to another.
-
-\begin{key}{/tikz/shade}
- Causes the path to be shaded using the currently selected shading (more on
- this later). If this option is used together with the |draw| option, then
- the path is first shaded, then drawn.
-
- It is not an error to use this option together with the |fill| option, but
- it makes no sense.
- %
-\begin{codeexample}[]
-\tikz \shade (0,0) circle (1ex);
-\end{codeexample}
-
-\begin{codeexample}[]
-\tikz \shadedraw (0,0) circle (1ex);
-\end{codeexample}
- %
-\end{key}
-
-For some shadings it is not really clear how they can ``fill'' the path. For
-example, the |ball| shading normally looks like this:
-\tikz \shade[shading=ball] (0,0) circle (0.75ex);. How is this supposed to
-shade a rectangle? Or a triangle?
-
-To solve this problem, the predefined shadings like |ball| or |axis| fill a
-large rectangle completely in a sensible way. Then, when the shading is used to
-``shade'' a path, what actually happens is that the path is temporarily used
-for clipping and then the rectangular shading is drawn, scaled and shifted such
-that all parts of the path are filled.
-
-The default shading is a smooth transition from gray to white and from top to
-bottom. However, other shadings are also possible, for example a shading that
-will sweep a color from the center to the corners outward. To choose the
-shading, you can use the |shading=| option, which will also automatically
-invoke the |shade| option. Note that this does \emph{not} change the shading
-color, only the way the colors sweep. For changing the colors, other options
-are needed, which are explained below.
-
-\begin{key}{/tikz/shading=\meta{name}}
- This selects a shading named \meta{name}. The following shadings are
- predefined: |axis|, |radial|, and |ball|.
- %
-\begin{codeexample}[]
-\tikz \shadedraw [shading=axis] (0,0) rectangle (1,1);
-\tikz \shadedraw [shading=radial] (0,0) rectangle (1,1);
-\tikz \shadedraw [shading=ball] (0,0) circle (.5cm);
-\end{codeexample}
-
- The shadings as well as additional shadings are described in more detail in
- Section~\ref{section-library-shadings}.
-
- To change the color of a shading, special options are needed like
- |left color|, which sets the color of an axis shading from left to right.
- These options implicitly also select the correct shading type, see the
- following example
- %
-\begin{codeexample}[]
-\tikz \shadedraw [left color=red,right color=blue]
- (0,0) rectangle (1,1);
-\end{codeexample}
-
- For a complete list of the possible options see
- Section~\ref{section-library-shadings} once more.
-
- \begin{key}{/tikz/shading angle=\meta{degrees} (initially 0)}
- This option rotates the shading (not the path!) by the given angle. For
- example, we can turn a top-to-bottom axis shading into a left-to-right
- shading by rotating it by $90^\circ$.
- %
-\begin{codeexample}[]
-\tikz \shadedraw [shading=axis,shading angle=90] (0,0) rectangle (1,1);
-\end{codeexample}
- \end{key}
-\end{key}
-
-You can also define new shading types yourself. However, for this, you need to
-use the basic layer directly, which is, well, more basic and harder to use.
-Details on how to create a shading appropriate for filling paths are given in
-Section~\ref{section-shading-a-path}.
-
-
-\subsection{Establishing a Bounding Box}
-
-\pgfname\ is reasonably good at keeping track of the size of your picture and
-reserving just the right amount of space for it in the main document. However,
-in some cases you may want to say things like ``do not count this for the
-picture size'' or ``the picture is actually a little large''. For this you can
-use the option |use as bounding box| or the command |\useasboundingbox|, which
-is just a shorthand for |\path[use as bounding box]|.
-
-\begin{key}{/tikz/use as bounding box}
- Normally, when this option is given on a path, the bounding box of the
- present path is used to determine the size of the picture and the size of
- all \emph{subsequent} paths are ignored. However, if there were previous
- path operations that have already established a larger bounding box, it
- will not be made smaller by this operation (consider the
- |\pgfresetboundingbox| command to reset the previous bounding box).
-
- In a sense, |use as bounding box| has the same effect as clipping all
- subsequent drawing against the current path -- without actually doing the
- clipping, only making \pgfname\ treat everything as if it were clipped.
-
- The first application of this option is to have a |{tikzpicture}| overlap
- with the main text:
- %
-\begin{codeexample}[]
-Left of picture\begin{tikzpicture}
- \draw[use as bounding box] (2,0) rectangle (3,1);
- \draw (1,0) -- (4,.75);
-\end{tikzpicture}right of picture.
-\end{codeexample}
-
- In a second application this option can be used to get better control over
- the white space around the picture:
- %
-\begin{codeexample}[]
-Left of picture
-\begin{tikzpicture}
- \useasboundingbox (0,0) rectangle (3,1);
- \fill (.75,.25) circle (.5cm);
-\end{tikzpicture}
-right of picture.
-\end{codeexample}
-
- Note: If this option is used on a path inside a \TeX\ group (scope), the
- effect ``lasts'' only until the end of the scope. Again, this behavior is
- the same as for clipping.
-
- Consider using |\useasboundingbox| together with |\pgfresetboundingbox| in
- order to replace the bounding box with a new one.
-\end{key}
-
-There is a node that allows you to get the size of the current bounding box.
-The |current bounding box| node has the |rectangle| shape and its size is
-always the size of the current bounding box.
-
-Similarly, the |current path bounding box| node has the |rectangle| shape and
-the size of the bounding box of the current path.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[red] (0,0) circle (2pt);
- \draw[red] (2,1) circle (3pt);
-
- \draw (current bounding box.south west) rectangle
- (current bounding box.north east);
-
- \draw[red] (3,-1) circle (4pt);
-
- \draw[thick] (current bounding box.south west) rectangle
- (current bounding box.north east);
-\end{tikzpicture}
-\end{codeexample}
-
-Occasionally, you may want to align multiple |tikzpicture| environments
-horizontally and/or vertically at some prescribed position. The vertical
-alignment can be realized by means of the |baseline| option since \TeX\
-supports the concept of box depth natively. For horizontal alignment, things
-are slightly more involved. The following approach is realized by means of
-negative |\hspace|s before and/or after the picture, thereby removing parts of
-the picture. However, the actual amount of negative horizontal space is
-provided by means of image coordinates using the |trim left| and |trim right|
-keys:
-
-\begin{key}{/tikz/trim left=\meta{dimension or coordinate or \texttt{default}} (default 0pt)}
- The |trim left| key tells \pgfname\space to discard everything which is
- left of the provided \meta{dimension or coordinate}. Here, \meta{dimension}
- is a single $x$ coordinate of the picture and \meta{coordinate} is a point
- with $x$ and $y$ coordinates (but only its $x$ coordinate will be used).
- The effect is the same as if you issue |\hspace{-s}| where |s| is the
- difference of the picture's bounding box lower left $x$ coordinate and the
- $x$ coordinate specified as \meta{dimension or coordinate}:
- %
-\begin{codeexample}[]
-Text before image.%
- \begin{tikzpicture}[trim left]
- \draw (-1,-1) grid (3,2);
- \fill (0,0) circle (5pt);
- \end{tikzpicture}%
-Text after image.
-\end{codeexample}
- %
- Since |trim left| uses the default |trim left=0pt|, everything left of
- $x=0$ is removed from the bounding box.
-
- The following example has once the relative long label $-1$ and once the
- shorter label $1$. Horizontal alignment is established with |trim left|:
- %
-\begin{codeexample}[pre={\vbox\bgroup\hsize=5cm},post=\egroup,width=8cm]
-\begin{tikzpicture}
- \draw (0,1) -- (0,0) -- (1,1) -- cycle;
- \fill (0,0) circle (2pt);
- \node[left] at (0,0) {$-1$};
-\end{tikzpicture}
-\par
-\begin{tikzpicture}
- \draw (0,1) -- (0,0) -- (1,1) -- cycle;
- \fill (0,0) circle (2pt);
- \node[left] at (0,0) {$1$};
-\end{tikzpicture}
-\par
-\begin{tikzpicture}[trim left]
- \draw (0,1) -- (0,0) -- (1,1) -- cycle;
- \fill (0,0) circle (2pt);
- \node[left] at (0,0) {$-1$};
-\end{tikzpicture}
-\par
-\begin{tikzpicture}[trim left]
- \draw (0,1) -- (0,0) -- (1,1) -- cycle;
- \fill (0,0) circle (2pt);
- \node[left] at (0,0) {$1$};
-\end{tikzpicture}
-\end{codeexample}
-
- Use |trim left=default| to reset the value.
-\end{key}
-
-\begin{key}{/tikz/trim right=\meta{dimension or coordinate or \texttt{default}}}
- This key is similar to |trim left|: it discards everything which is right
- of the provided \meta{dimension or coordinate}. As for |trim left|,
- \meta{dimension} denotes a single $x$ coordinate of the picture and
- \meta{coordinate} a coordinate with $x$ and $y$ value (although only its
- $x$ component will be used).
-
- We use the same example from above and add |trim right|:
- %
-\begin{codeexample}[]
-Text before image.%
- \begin{tikzpicture}[trim left, trim right=2cm, baseline]
- \draw (-1,-1) grid (3,2);
- \fill (0,0) circle (5pt);
- \end{tikzpicture}%
-Text after image.
-\end{codeexample}
- %
- In addition to |trim left=0pt|, we also discard everything which is right
- of $x$|=2cm|. Furthermore, the |baseline| key supports vertical alignment
- as well (using the $y$|=0cm| baseline).
-
- Use |trim right=default| to reset the value.
-\end{key}
-
-Note that |baseline|, |trim left| and |trim right| are currently the
-\emph{only} supported way of truncated bounding boxes which are compatible with
-image externalization (see the |external| library for details).
-
-\begin{key}{/pgf/trim lowlevel=\mchoice{true,false} (initially false)}
- This affects only the basic level image externalization: the initial
- configuration |trim lowlevel=false| stores the normal image, without
- trimming, and the trimming into a separate file. This allows reduced
- bounding boxes without clipping the rest away. The |trim lowlevel=true|
- information causes the image externalization to store the trimmed image,
- possibly resulting in clipping.
-\end{key}
-
-
-\subsection{Clipping and Fading (Soft Clipping)}
-
-\emph{Clipping path} means that all painting on the page is restricted to a
-certain area. This area need not be rectangular, rather an arbitrary path can
-be used to specify this area. The |clip| option, explained below, is used to
-specify the region that is to be used for clipping.
-
-A \emph{fading} (a term that I propose, fadings are commonly known as soft
-masks, transparency masks, opacity masks or soft clips) is similar to clipping,
-but a fading allows parts of the picture to be only ``half clipped''. This
-means that a fading can specify that newly painted pixels should be partly
-transparent. The specification and handling of fadings is a bit complex and it
-is detailed in Section~\ref{section-tikz-transparency}, which is devoted to
-transparency in general.
-
-\begin{key}{/tikz/clip}
- This option causes all subsequent drawings to be clipped against the
- current path and the size of subsequent paths will not be important for the
- picture size. If you clip against a self-intersecting path, the even-odd
- rule or the nonzero winding number rule is used to determine whether a
- point is inside or outside the clipping region.
-
- The clipping path is a graphic state parameter, so it will be reset at the
- end of the current scope. Multiple clippings accumulate, that is, clipping
- is always done against the intersection of all clipping areas that have
- been specified inside the current scopes. The only way of enlarging the
- clipping area is to end a |{scope}|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[clip] (0,0) circle (1cm);
- \fill[red] (1,0) circle (1cm);
-\end{tikzpicture}
-\end{codeexample}
-
- It is usually a \emph{very} good idea to apply the |clip| option only to
- the first path command in a scope.
-
- If you ``only wish to clip'' and do not wish to draw anything, you can use
- the |\clip| command, which is a shorthand for |\path[clip]|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \clip (0,0) circle (1cm);
- \fill[red] (1,0) circle (1cm);
-\end{tikzpicture}
-\end{codeexample}
-
- To keep clipping local, use |{scope}| environments as in the following
- example:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) -- ( 0:1cm);
- \draw (0,0) -- (10:1cm);
- \draw (0,0) -- (20:1cm);
- \draw (0,0) -- (30:1cm);
- \begin{scope}[fill=red]
- \fill[clip] (0.2,0.2) rectangle (0.5,0.5);
-
- \draw (0,0) -- (40:1cm);
- \draw (0,0) -- (50:1cm);
- \draw (0,0) -- (60:1cm);
- \end{scope}
- \draw (0,0) -- (70:1cm);
- \draw (0,0) -- (80:1cm);
- \draw (0,0) -- (90:1cm);
-\end{tikzpicture}
-\end{codeexample}
-
- There is a slightly annoying catch: You cannot specify certain graphic
- options for the command used for clipping. For example, in the above code
- we could not have moved the |fill=red| to the |\fill| command. The reasons
- for this have to do with the internals of the \pdf\ specification. You do
- not want to know the details. It is best simply not to specify any options
- for these commands.
-\end{key}
-
-
-\subsection{Doing Multiple Actions on a Path}
-
-If more than one of the basic actions like drawing, clipping and filling are
-requested, they are automatically applied in a sensible order: First, a path is
-filled, then drawn, and then clipped (although it took Apple two major
-revisions of their operating system to get this right\dots). Sometimes,
-however, you need finer control over what is done with a path. For instance,
-you might wish to first fill a path with a color, then repaint the path with a
-pattern and then repaint it with yet another pattern. In such cases you can use
-the following two options:
-
-\begin{key}{/tikz/preaction=\meta{options}}
- This option can be given to a |\path| command (or to derived commands like
- |\draw| which internally call |\path|). Similarly to options like |draw|,
- this option only has an effect when given to a |\path| or as part of the
- options of a |node|; as an option to a |{scope}| it has no effect.
-
- When this option is used on a |\path|, the effect is the following: When
- the path has been completely constructed and is about to be used, a scope
- is created. Inside this scope, the path is used but not with the original
- path options, but with \meta{options} instead. Then, the path is used in
- the usual manner. In other words, the path is used twice: Once with
- \meta{options} in force and then again with the normal path options in
- force.
-
- Here is an example in which the path consists of a rectangle. The main
- action is to draw this path in red (which is why we see a red rectangle).
- However, the preaction is to draw the path in blue, which is why we see a
- blue rectangle behind the red rectangle.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \draw
- [preaction={draw,line width=4mm,blue}]
- [line width=2mm,red] (0,0) rectangle (2,2);
-\end{tikzpicture}
-\end{codeexample}
-
- Note that when the preactions are preformed, then the path is already
- ``finished''. In particular, applying a coordinate transformation to the
- path has no effect. By comparison, applying a canvas transformation does
- have an effect. Let us use this to add a ``shadow'' to a path. For this, we
- use the preaction to fill the path in gray, shifted a bit to the right and
- down:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw
- [preaction={fill=black,opacity=.5,
- transform canvas={xshift=1mm,yshift=-1mm}}]
- [fill=red] (0,0) rectangle (1,2)
- (1,2) circle (5mm);
-\end{tikzpicture}
-\end{codeexample}
-
- Naturally, you would normally create a style |shadow| that contains the
- above code. The |shadows| library, see Section~\ref{section-libs-shadows},
- contains predefined shadows of this kind.
-
- It is possible to use the |preaction| option multiple times. In this case,
- for each use of the |preaction| option, the path is used again (thus, the
- \meta{options} do not accumulate in a single usage of the path). The path
- is used in the order of |preaction| options given.
-
- In the following example, we use one |preaction| to add a shadow and
- another to provide a shading, while the main action is to use a pattern.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw [pattern=fivepointed stars]
- [preaction={fill=black,opacity=.5,
- transform canvas={xshift=1mm,yshift=-1mm}}]
- [preaction={top color=blue,bottom color=white}]
- (0,0) rectangle (1,2)
- (1,2) circle (5mm);
-\end{tikzpicture}
-\end{codeexample}
-
- A complicated application is shown in the following example, where the path
- is used several times with different fadings and shadings to create a
- special visual effect:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
-\begin{tikzpicture}
- [
- % Define an interesting style
- button/.style={
- % First preaction: Fuzzy shadow
- preaction={fill=black,path fading=circle with fuzzy edge 20 percent,
- opacity=.5,transform canvas={xshift=1mm,yshift=-1mm}},
- % Second preaction: Background pattern
- preaction={pattern=#1,
- path fading=circle with fuzzy edge 15 percent},
- % Third preaction: Make background shiny
- preaction={top color=white,
- bottom color=black!50,
- shading angle=45,
- path fading=circle with fuzzy edge 15 percent,
- opacity=0.2},
- % Fourth preaction: Make edge especially shiny
- preaction={path fading=fuzzy ring 15 percent,
- top color=black!5,
- bottom color=black!80,
- shading angle=45},
- inner sep=2ex
- },
- button/.default=horizontal lines light blue,
- circle
- ]
-
- \draw [help lines] (0,0) grid (4,3);
-
- \node [button] at (2.2,1) {\Huge Big};
- \node [button=crosshatch dots light steel blue,
- text=white] at (1,1.5) {Small};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/postaction=\meta{options}}
- The postactions work in the same way as the preactions, only they are
- applied \emph{after} the main action has been taken. Like preactions,
- multiple |postaction| options may be given to a |\path| command, in which
- case the path is reused several times, each time with a different set of
- options in force.
-
- If both pre- and postactions are specified, then the preactions are taken
- first, then the main action, and then the post actions.
-
- In the first example, we use a postaction to draw the path, after it has
- already been drawn:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \draw
- [postaction={draw,line width=2mm,blue}]
- [line width=4mm,red,fill=white] (0,0) rectangle (2,2);
-\end{tikzpicture}
-\end{codeexample}
-
- In another example, we use a postaction to ``colorize'' a path:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fadings}}]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw
- [postaction={path fading=south,fill=white}]
- [postaction={path fading=south,fading angle=45,fill=blue,opacity=.5}]
- [left color=black,right color=red,draw=white,line width=2mm]
- (0,0) rectangle (1,2)
- (1,2) circle (5mm);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Decorating and Morphing a Path}
-
-Before a path is used, it is possible to first ``decorate'' and/or ``morph''
-it. Morphing means that the path is replaced by another path that is slightly
-varied. Such morphings are a special case of the more general ``decorations''
-described in detail in Section~\ref{section-tikz-decorations}. For instance, in
-the following example the path is drawn twice: Once normally and then in a
-morphed (=decorated) manner.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- \draw (0,0) rectangle (3,2);
- \draw [red, decorate, decoration=zigzag]
- (0,0) rectangle (3,2);
-\end{tikzpicture}
-\end{codeexample}
-
-Naturally, we could have combined this into a single command using pre- or
-postaction. It is also possible to deform shapes:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing,shadows}}]
-\begin{tikzpicture}
- \node [circular drop shadow={shadow scale=1.05},minimum size=3.13cm,
- decorate, decoration=zigzag,
- fill=blue!20,draw,thick,circle] {Hello!};
-\end{tikzpicture}
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-animations.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-animations.tex
deleted file mode 100644
index 3ce6b452dc..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-animations.tex
+++ /dev/null
@@ -1,2805 +0,0 @@
-% 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{Animations}
-\label{section-tikz-animations}
-
-\begin{tikzlibrary}{animations}
- This library must be loaded in order to use animations with \tikzname.
-\end{tikzlibrary}
-
-
-\subsection{Introduction}
-
-An \emph{animation} changes the appearance of some part of a graphic over time.
-The archetypical animation is, of course, a \emph{movement} of some part of a
-picture, but a change of, say, the opacity of a path is also an animation.
-\tikzname\ allows you to specify such animations using special keys and
-notations.
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- width=8cm,
- animation list={0.7,1.4,2.1,2.8},
- animation scale=.25,
-]
-\begin{tikzpicture}[
- animate/orbit/.style 2 args = {
- myself:shift = {
- along = {
- (0,0) circle [radius=#1]
- } sloped in #2s/10,
- repeats }} ]
-
- \node :color = {0s = "orange",
- 2s = "red",
- 4s = "orange",
- repeats}
- {Sun};
-
- \begin{scope}[animate={orbit={2.5cm}{365}}]
- \node {Earth};
- \node [animate={orbit={1cm}{28}}] {Moon};
- \end{scope}
-
- \useasboundingbox (-3.8,-3.8) (3.8,3.8);
-\end{tikzpicture}
-\end{codeexample}
-
-Adding an animation to a \tikzname\ picture is done as follows:
-%
-\begin{enumerate}
- \item \emph{Before} or \emph{in the options of} the to-be-animated object
- you specify the object together with an \emph{attribute} that you wish
- to animate. Attributes are things like the fill color or the line width
- or the position of the object.
- \item You specify \emph{when} this attribute should have \emph{which}
- values using a so-called \emph{timeline}. This is just a curve that
- specifies for each point in time which value the attribute should have.
- \item You can additionally use further options to configure the animation,
- for instance you can specify that the animation should repeat or that
- it should only start when a certain object is clicked.
-\end{enumerate}
-
-As a simple example, let us move a circle within thirty seconds by three
-centimeters to the left:
-%
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \draw :xshift = {0s = "0cm", 30s = "-3cm", repeats} (0,0) circle (5mm);
-\end{codeexample}
-
-As can be seen, a special syntax is used in several places: Entries with a
-colon such as |:xshift| specify an attribute, values are specified in quotation
-marks. This syntax will be explained in more detail later on.
-
-
-\subsubsection{Animations Change Attributes}
-
-Before we plunge into the details of how animations are specified, it is
-important to understand what \tikzname\ actually does when creating an
-animation: It does \emph{not} (as all other animation packages do) precompute a
-sequence of pictures that are later somehow displayed in rapid succession.
-Neither does it insert an external video into the document. Rather, a
-\tikzname\ animation is just an ``annotation'' in the output that a certain
-attribute of a certain object should change over time in some specific way when
-the object is displayed. It is the job of the document viewer application to
-actually compute and display the animation. The big advantage of this approach
-is that animations neither increase the output file sizes noticeably nor do
-they really slow down \TeX: The hard and complicated calculations are done by
-the viewer application. The disadvantage is, of course, that a document viewer
-application must understand the annotations and actually compute and display
-the animations. The \textsc{svg} format is a format for which this is possible,
-the popular \textsc{pdf} format is not. For the \textsc{svg} format, there are
-actually different possible ways of ``formulating'' the animations (using
-\textsc{smil} or \textsc{css} or JavaScript) and they have different advantages
-and disadvantages.
-
-To make a long story short: \tikzname\ animations currently work only with
-\textsc{svg} output (and use the \textsc{smil} ``flavor'' of describing
-animations). In future, it may well happen that other ``flavor'' of describing
-animations will be added, but it is very unlikely that \textsc{pdf} will ever
-support animations in a useful way.
-
-It is, however, possible to create ``snapshots'' of an animation and insert
-these into \textsc{pdf} files (or any other kind of file including \textsc{svg}
-files), see Section~\ref{section-anim-snap} for details. Snapshots are also
-useful for creating ``printed versions'' of animations and all of the small
-sequences of pictures in the manual that are used for showing what an animation
-key does have been creating using snapshots.
-
-
-\subsubsection{Limitations of the Animation System}
-
-There are a certain limitations of the animation system that you should keep in
-mind when considering how and when to use it:
-%
-\begin{enumerate}
- \item As pointed out earlier, animations require a specific output format
- (currently only \textsc{svg} is supported).
- \item It is extremely difficult to animate ``lines between moving nodes''
- correctly. Consider code like |\draw(a)--(b);| where |a| and |b| are
- nodes. Now, when you animate the position of~|(a)|, the line connecting
- |(a)| and |(b)| will, unfortunately, not ``move along'' automatically
- (but it is easy to move the whole group of |(a)|, |(b)|, and the
- connecting line as whole). You must ``cheat'' and introduce some
- ``virtual'' nodes, which leads to rather complex and bloated code.
- \item Animations are taken into consideration for bounding box computations,
- but only for shifts, not for rotations, scaling, or skewing and also
- possibly not when multiple shifts are active at the same time for the
- same object.
-\end{enumerate}
-
-
-\subsubsection{Concepts: (Graphic) Objects}
-
-During an animation an attribute of a certain ``object'' changes over time. The
-term ``object'' is deliberately a bit vague since there are numerous different
-``things'' whose attributes can change. In detail, the following objects have
-attributes that can be animated:
-%
-\begin{enumerate}
- \item Nodes, which are created by the |\node| command (and, also,
- internally by commands such as |\graph|). For nodes, different parts of
- the node can be animated separately; for instance, you can animate the
- color of the background path, but also the color of the text, and also
- the color of the foreground path (though most nodes do not have a
- foreground path) and also the color of different text parts (though
- only few nodes have multiple text parts).
- \item Graphic scopes, which are created by numerous command, including the
- |{scope}| environment, the |\scopes| command, but also |\tikz| itself
- creates a graphic scope and so does each node and even each path.
- \item View boxes, which can only be created using the |views| library.
- \item Paths, which you create using the |\path| command or commands like
- |\draw| that call |\path| internally. However, the (usually background)
- path of a node can also be animated. Note that ``animating the path''
- really means that the path itself should change over time; in essence,
- you can ``warp'' a path over time.
-\end{enumerate}
-
-In all of these cases, you must either specify the animation inside the
-object's options using |animate| or use the |name| key to name the object and,
-then, refer to it in an |animate|. For nodes you can, of course, use the
-|(|\meta{node name}|)| syntax to name the node. Recall that you must
-\emph{always} specify the animation \emph{before} the object is created; it is
-not possible to animate an already created object.
-
-There is a special syntax for choosing the object of an animation, see
-Section~\ref{section-anim-syntax-obj}, but you can also use the |object| key to
-choose them directly, see Section~\ref{section-anim-def-obj}.
-
-
-\subsubsection{Concepts: Attributes}
-
-In addition to the to-be-animated object, you must also choose an
-\emph{attribute} that you wish to animate. Attributes are things like the color
-of an object, the position, but also things like the line width. The syntax for
-choosing attributes and the list of attributes will be explained in detail
-later on.
-
-Most attributes correspond directly to attributes that are directly supported
-by the backend driver (\textsc{svg}), but this is not always the case. For
-instance, for a node, \tikzname\ differentiates between the fill color, the
-draw (stroke) color, and the text color, while \textsc{svg} treats the text
-color are a special case of the fill color. \tikzname\ will do some internal
-mappings to ensure that you can animate the ``\tikzname\ attributes'' even when
-they are not directly supported.
-
-The same syntax that is used for specifying object is also used to specify
-attributes, see Section~\ref{section-anim-syntax-obj}, but you could also set
-them directly using the |attribute| key see
-Section~\ref{section-anim-def-attr}.
-
-
-\subsubsection{Concepts: Timelines}
-
-Once an object and an attribute have been chosen, a \emph{timeline} needs to be
-established. This is, essentially, a curve that specifies for each ``moment in
-time'' which value the attribute should have.
-
-A timeline has a \emph{start} and an \emph{end}, but the start need not be the
-``moment zero'' (we will come to that) and may even be negative, while the end
-may be at infinity. You specify the timeline by specifying for certain points
-in time what the value is at that moment; for all other moments the value is
-then interpolated. For instance, if you specify that the attribute |:xshift|
-(the ``horizontal position'' of the object) is 0\,mm at time 5\,s and 10\,mm at
-time 10\,s, then at 7.5\,s it will be 5\,mm and at 9\,s it will be 8\,mm
-(assuming a linear interpolation). The resulting optical effect will be that
-the object \emph{smoothly moves} by one centimeter to the right over a period
-of five seconds, starting five seconds after ``moment zero''.
-
-Now, what is the ``moment zero'', the ``beginning of an animation''? If nothing
-else is specified, an animation starts immediately when the graphic is shown
-and this is the moment zero relative to which the timeline is measured.
-However, it is also possible to change this. In particular, you can specify
-that the moment zero is when a particular \emph{event} occurs such as the user
-clicking on another object or another animation ending or starting.
-
-The interpolation of values is not always a straightforward affair. Firstly,
-for certain kinds of values is not clear how an interpolation should be
-computed. How does one interpolate between two paths? Between the colors red
-and green? Between the values |"true"| and |"false"|? In these cases, one must
-define carefully what the interpolation should be. Secondly, you may wish to
-use a non-linear interpolation, which is useful for ``easing'' motions: The
-visual effect of the movement specified above is that the object sits still
-from moment $0$ for five seconds, then there is an ``infinite acceleration''
-causing the object to suddenly move at the speed of 2\,mm per second, then
-there is no acceleration at all for five seconds, causing the object to move
-for one centimeter, followed by an ``infinite negative acceleration'' that
-makes the object come to a full stop. As a viewer you experience these infinite
-accelerations as ``unrealistic'', spoiling the effect of watching a (virtual)
-physical process. Non-linear interpolations allow you to avoid this effect.
-
-Just as for specifying objects and attributes, there is also a special syntax
-for specifying times and values.
-
-
-\subsection{Creating an Animation}
-
-\subsubsection{The Animate Key}
-
-In order to animate a picture, you create timelines for all objects and
-attributes that change during the animation. The key |animate| is used for
-creating these timelines.
-
-\begin{key}{/tikz/animate=\meta{animation specification}}
- You must place all specifications of animations inside uses of |animate|.
- You can, and usually should, place the specification of all timelines of a
- single picture inside a single use of this key since it will reset the time
- and the fork time (explained in Section~\ref{section-anim-def-times}). You
- can, however, use this key several times, in principle. Note that if you
- animate the same attribute of the same object in two different uses of
- |animate|, two separate timelines will result (and complicated rules are
- used to determine which one ``wins'' in case they specify conflicting
- values for the attribute at different times).
-
- The key can be used at all places where a \tikzname\ key is used; typically
- you will use it with a |{scope}| environment, inside the options of a node,
- or directly with the |\tikz| command:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list = {0.5,1,1.5,2},
-]
-\tikz \node [fill, text = white, animate = {
- myself:fill = {0s = "red", 2s = "blue", begin on = click }}] {Click me};
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list = {0.5,1,1.5,2},
-]
-\tikz [animate = {a node:fill = {0s = "red", 2s = "blue",
- begin on = click}}]
- \node (a node) [fill, text = white] {Click me};
-\end{codeexample}
-
- The details of what, exactly, happens in the \meta{animation specification}
- will be described in the rest of this section. However, basically, an
- \meta{animation specification} is just a sequence of normal \tikzname\
- key--value pairs that get executed with the path prefix |/tikz/animate| and
- with some special syntax handlers installed. In particular, you can define
- styles for this key path and use them. For instance, we can define a
- |shake| animation like this:
- %
-\begin{codeexample}[width=4cm,preamble={\usetikzlibrary{animations}}]
-\tikzset{
- animate/shake/.style = {myself:xshift = { begin on=click,
- 0s = "0mm", 50ms = "#1", 150ms = "-#1", 250ms = "#1", 300ms = "0mm" }}}
-\tikz \node [fill = blue!20, draw=blue, very thick, circle,
- animate = {shake = 1mm}] {Shake};
-\tikz \node [fill = blue!20, draw=blue, very thick, circle,
- animate = {shake = 2mm}] {SHAKE};
-\end{codeexample}
-
- Note that, as stressed earlier, you can only use the |animate| key to
- specify animations for objects that do not yet exist. The node and object
- names mentioned in a specification always refer to ``upcoming'' objects;
- already existing objects of the same name are not influenced.
-
- You can use the |name| key inside |animate| to ``name'' the animation. Once
- named, you can later reference the animation in other animations; for
- instance, you can say that another animation should start when the present
- animation has ended.
-\end{key}
-
-
-\subsubsection{Timeline Entries}
-
-The ``job'' of the options passed to the |animate| key is to specify the
-timelines of the animation of (a part of) a picture. For each object and each
-attribute there may or may not be a timeline and, if present, the timeline
-consist of sequences of pairs of times and values. Thus, the most basic entity
-of an animation specification is a tuple consisting of five parts, which are
-selected by five different keys:
-%
-\begin{itemize}
- \item |object| for selecting the object,
- \item |attribute| for selecting the attribute,
- \item |id| for selecting the timeline id (explained in
- Section~\ref{section-anim-def-id}),
- \item |time| for selecting a time, and
- \item |value| for selecting a value.
-\end{itemize}
-%
-When all of these parts have been set up (using the above keys, which will be
-explained in more detail in a moment), you can use the following key to create
-an entry:
-
-\begin{key}{/tikz/animate/entry}
- Each time this key is used in the options of |animate|, \tikzname\ checks
- whether the five keys |object|, |attribute|, |id|, |time|, and |value| are
- set. If one of them is not set, nothing happens. (The |id| key is set to
- the value |default| by default, all other keys must be set explicitly.)
-
- If all of these keys are set, a \emph{time--value} pair is created and
- added to the timeline of attribute of the object. Additionally, all options
- starting with |/tikz/animate/options/|, which also influence the timeline
- like |begin on|, are also added to the timeline of the object--attribute
- pair.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [animate = {
- object = node, attribute = fill, time = 0s, value = red, entry,
- object = node, attribute = fill, time = 2s, value = blue, entry,
- object = node, attribute = fill, begin on = click, entry}]
- \node (node) [fill, text=white] { Click me };
-\end{codeexample}
- %
- In the above example, it would not have been necessary the specify the
- object and the attribute in each line, they retain their values unless they
- are overwritten. Thus, we could also have written:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [animate = {
- object = node, attribute = fill, time = 0s, value = red, entry,
- time = 2s, value = blue, entry,
- begin on = click, entry}]
- \node (node) [fill, text=white] { Click me };
-\end{codeexample}
- %
- Note, however, that in both examples we actually add the time--value pair
- $(2\mathrm{s}, \mathrm{blue})$ twice since the |time| and |value| keys also
- retain their settings and, thus, for the third |entry| they have the same
- values as before and a new pair is added. While this superfluous pair is
- not a problem in the example (it has no visual effect), we will see later
- on how such pairs can be avoided by using the |scope| key.
-
- A sequence of calls of |entry| can freely switch between objects and
- attributes (that is, between timelines), but the times for any given
- timeline must be given in non-decreasing order:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [animate = {
- object = node, attribute = fill, time = 0s, value = red, entry,
- object = node2, attribute = draw, entry,
- object = node, attribute = fill, time = 2s, value = blue, entry,
- object = node2, attribute = draw, entry,
- object = node, attribute = fill, begin on = click, entry,
- object = node2, attribute = draw, begin on = click, entry}] {
- \node (node) [fill, text=white] { Node 1 };
- \node (node2) [draw, ultra thick] at (0,-1) { Node 2 };
-}
-\end{codeexample}
- %
- In the above example, we could not have exchanged the first two lines of
- the |animate| options with the third and fourth line since the values for
- time |0s| must come before the values for time |2s|.
-\end{key}
-
-In the following, we have a closer look at the five keys the influence the
-|entry| key and then have a look at ways of grouping keys more easily.
-
-
-\subsubsection{Specifying Objects}
-\label{section-anim-def-obj}
-
-You use the |object| key to select the object(s) to which the next use of
-|entry| applies. There is also a special syntax for this, which is explained in
-Section~\ref{section-anim-syntax-obj}.
-
-\begin{key}{/tikz/animate/object=\meta{list of objects}}
- The \meta{list of objects} is a comma-separated list of strings of the form
- \meta{object}\opt{|.|\meta{type}}. All of the objects in the list are
- selected as to-be-animate object for the next use of the |entry| key. The
- objects referred to by \meta{object} will be the \emph{next} objects with
- the |name| key set to \meta{object}. You can apply the |name| key to nodes
- (where you can also use the special parentheses-syntax and put the name in
- parentheses, it has the same effect), but also to scopes and paths. (The
- |name path| key is not the same as |name|; it is an older key from the
- intersections package and not related.)
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue",
- begin on = click }}] {
- \node (a) [fill, text = white, minimum width=1.5cm] at (0,1cm) {a};
- \node (b) [fill, text = white, minimum width=1.5cm] at (0,5mm) {b};
- \node (c) [fill, text = white, minimum width=1.5cm] at (0,0mm) {c}; }
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [animate = { object = b, :fill = {0s = "red", 2s = "blue",
- begin on = click },
- object = c, :fill = {0s = "green", 2s = "blue",
- begin on = click } }] {
- \scoped [name = a, yshift=1cm] \fill (0,0) rectangle (1.5cm,2mm);
- \scoped [name = b, yshift=5mm] \fill (0,0) rectangle (1.5cm,2mm);
- \scoped [name = c, yshift=0mm] \fill (0,0) rectangle (1.5cm,2mm); }
-\end{codeexample}
-
- If the \meta{object} name is never used later in the file, no animation is
- created.
-
- The \meta{object} may also be the special text |myself|. In this case, the
- referenced object is the scope or object to which the |animate| key is
- given. If an object is named |myself| (as in |\node (myself) ...|), you
- cannot reference this node using the |object| key, |myself| \emph{always}
- refers to the object where the |animate| key is given (of course, you can
- animate the node named |myself| by placing the |animate| key inside the
- options of this node; you only cannot ``remotely'' add an animation to it).
-
- The \meta{object} may be followed by a dot and a \emph{type}. This is need
- in rare cases where you want to animate only a special ``part'' of an
- object that is not accessible in other ways. Normally, \tikzname\ takes
- care of choosing these types automatically, you only need to set these ``if
- you know what you are doing''.
-\end{key}
-
-
-\subsubsection{Specifying Attributes}
-\label{section-anim-def-attr}
-
-\begin{key}{/tikz/animate/attribute=\meta{list of attributes}}
- The list of attributes must be a comma-separated list of attribute names.
- The timelines specified later will apply to all of these attributes (and to
- all objects previously selected using |object|). Possible attributes
- include colors, positions, line width, but even the paths themselves. The
- exact list of possible attributes is documented in
- Section~\ref{section-anim-attrs}.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [animate = {attribute = fill, n: = { 0s = "red", 2s = "blue",
- begin on = click } }]
- \node (n) [fill, text = white] {The node};
-\end{codeexample}
-\end{key}
-
-
-\subsubsection{Specifying IDs}
-\label{section-anim-def-id}
-
-\begin{key}{/tikz/animate/id=\meta{id} (initially default)}
- Timelines are use to defined how the values of an attribute of an object
- change over time. In many cases, you will have at most one timeline for
- each object--attribute pair, but, sometimes, you may wish to have more than
- one timeline for the same object and the same attribute. For instance, you
- might have a timeline that specifies a changing |shift| of a node in some
- direction and, at the same time, another timeline that specifies an
- additional |shift| in some other direction(s). The problem is that there is
- only one |shift| attribute and it would be difficult to compute the joint
- effect of the two timelines.
-
- For this purpose, timelines are actually identified not only by the
- object--attribute pair but, in reality, by the triple consisting of the
- object, the attribute, and the value of this key. We can now specify two
- separate timelines:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [animate = {
- id = 1, n:shift = { 0s = "{(0,0)}", 2s = "{(0,5mm)}", begin on = click },
- id = 2, n:shift = { 0s = "{(0,0)}", 2s = "{(5mm,0)}", begin on = click }
-}]
- \node (n) [fill = blue!20, draw=blue, very thick] {The node};
-\end{codeexample}
-
- The default value of |id| is |default|.
-\end{key}
-
-Because of the possibility of creating multiple timelines for the same
-attribute, it may happen that there is more than one timeline active that is
-``trying to modify'' a given attribute. In this case, the following rules are
-used to determine, which timeline ``wins'':
-%
-\begin{enumerate}
- \item If no animation is active at the current time (all animation either
- have not yet started or they have already ended), then the |base| value
- given in the animation encountered last in the code is used. (If there
- are no base values, the attribute is taken from the surrounding scope
- and the animations have ``no effect''.)
- \item If there are several active animations, the one that has started last
- is used and its value is used.
- \item If there are several active animations that have started at the same
- time, the one that comes last in the code is used.
-\end{enumerate}
-
-Note that these rules do not apply to transformations of the canvas since these
-are always additive (or, phrased differently, they are always all active and
-the effects accumulate).
-
-
-\subsubsection{Specifying Times}
-\label{section-anim-def-times}
-
-\begin{key}{/tikz/animate/time=\meta{time}\opt{|later|}}
- Sets the time for the next time--value pair in a call of |entry| to
- \meta{time} plus the current fork time. The text |later| is optional. Both
- ``fork times'' and the optional |later| will be explained in a moment.
-
- \medskip\textbf{Time Parsing.}
- The \meta{time} is parsed using the command |\pgfparsetime|, which is
- essentially the same as the usual math parser of \tikzname, and the result
- is interpreted as a time in seconds. Thus, a \meta{time} of |2+3| means ``5
- seconds'' and a \meta{time} of |2*(2.1)| means ``4.2 seconds''. (You could
- even specify silly times like |1in|, which results in the time ``72.27
- seconds''. Please do not do that.) The ``essentially'' refers to the fact
- that some extras are installed when the time parser is running:
- %
- \begin{itemize}
- \item The postfix operator |s| is added, which has no effect. Thus,
- when you write |5s| you get the same results as |5|, which is
- exactly 5 seconds as desired.
- \item The postfix operator |ms| is added, which divides a number by
- 1000, so |2ms| equals 0.002s.
- \item The postfix operator |min| is added, which multiplies a number by
- 60.
- \item The postfix operator |h| is added, which multiplies a number by
- 3600.
- \item The infix operator |:| is redefined, so that it multiplies its
- first argument by 60 and adds the second. This implies that |1:20|
- equals 80s and |01:00:00| equals 3600s.
- \item The parsing of octal numbers is switched off to allow things like
- |01:08| for 68s.
- \end{itemize}
-
- Note that you cannot use the colon syntax for times in things like
- |01:20 = "0"| would (falsely) be interpreted as: ``For the object named |01|
- and its attribute named |20|, do something.'' You can, however, use |01:20|
- in arguments to the |time| key, meaning that you would have to write
- instead: |time = 1:20, "0"|, possibly surround by a |scope|.
-
- \medskip\textbf{Relative Times.}
- You can suffix a |time| key with ``|later|''. In this case, the \meta{time}
- is interpreted as an offset to the time in the previous use of the time
- key:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :fill = { begin on = click,
- 0s = "white",
- 500ms later = "red",
- 500ms later = "green", % same as 1s = "-5mm"
- 500ms later = "blue"} % same as 1.5s = "-2.5mm"
- [fill=blue!20, draw=blue, very thick, circle] {Click me};
-\end{codeexample}
-
- In reality, the offset is not taken to just any previous use of the |time|
- key, but to the most recent use of this key or of the |resume| key in the
- current local \TeX\ scope. Here is an example:
- %
-\begin{codeexample}[code only]
-time = 2s,
-time = 1s later, % same as time = 3s
-time = 500ms later, % same as time = 3.5s
-time = 4s,
-time = 1s later, % same as time = 5s
-scope = { % opens a local scope
- time = 1s later, % same as time = 6s
- time = 10s
- time = 1s later % same as time = 11s
-}, % closes the scope, most recent time is 5s once more
-time = 2s later % same as time = 7s
-\end{codeexample}
-
- \medskip\textbf{Fork Times.}
- The time meant by the value \meta{time} passed to the |time| key is not
- used directly. Rather, \tikzname\ adds the current \emph{fork time} to it,
- which is |0s| by default. You can change the fork time using the following
- key:
- %
- \begin{key}{/tikz/animate/fork=\meta{t} (default 0s later)}
- Sets the fork time for the local scope to \meta{t} and sets the current
- time to |0s|. In this scope, when you use ``absolute'' times like |0s|
- or |2s|, you actually refer to later times that have started as
- \meta{t}.
-
- One application of forks is in the definition of keys that add a
- certain part to a longer animation. Consider for instance the
- definition of a |highlight| key:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={1.05,1.1,1.15,1.2,2.05,2.1,2.15,2.2},
-]
-\tikz [animate/highlight/.style = {
- scope = { fork = #1,
- :fill = { 0s = "black", 0.1s = "white", 0.2s = "black"} }
- }]
- \node [animate = { myself: = {
- :fill = { 0s = "black", begin on = click },
- highlight = 1s, highlight = 2s } },
- fill = blue, text=white, very thick, circle] { Click me };
-\end{codeexample}
- %
- In the above example, we could also have written |0.1s later| instead
- of |0.2s| and, indeed, the whole style could have been defined using
- only times with |later|, eliminating the need for the |fork| key.
- However, using forks you can specify absolute times for things
- happening in a conceptual ``subprocess'' and also relative times. The
- name |fork| for the key is also borrowed from operating system theory,
- where a ``fork'' is the spawning of an independent process.
- \end{key}
-
- \medskip\textbf{Remembering and Resuming Times.}
- When you have a complicated animation with a long timeline, you will
- sometimes wish to start some animation when some other animation has
- reached a certain moment; but this moment is only reached through heavy use
- of |later| times and/or forks. In such situations, the following keys are
- useful:
- %
- \begin{key}{/tikz/animate/remember=\meta{macroname}}
- This key stores the current time (the time of the last use of the
- |time| key) globally in the macro \meta{macroname}. This time will
- include the offset of the fork time:
- %
-\begin{codeexample}[code only]
-time = 2s,
-fork = 2s later, % fork time is now 4s
-time = 1s, % local time is 1s, absolute time is 5s (1s + fork time)
-time = 1s later, % local time is 2s, absolute time is 6s (2s + fork time)
-remember = \mytime % \mytime is now 6s
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/animate/resume=\meta{absolute time}}
- The \meta{absolute time} is evaluated using |\pgfparsetime| and, then,
- the current time is set to the resulting time minus the fork time. When
- the \meta{absolute time} is a macro previously set using |remember|,
- the net effect of this is that we return to the exact ``moment'' in the
- global time line when |remember| was used.
- %
-\begin{codeexample}[code only]
-fork = 4s,
-time = 1s,
-remember = \mytime % \mytime is now 5s
-fork = 2s, % fork time is now 2s, local time is 0s
-resume = \mytime % fork time is still 2s, local time is 3s
-\end{codeexample}
- %
- Using resume you can easily implement a ``join'' operation for forked
- times. You simply remember the times at the ends of the forks and then
- resume the maximum time of these remembered times:
- %
-\begin{codeexample}[code only]
-scope = {
- fork,
- time = 1s later,
- ...
- remember = \forka
-},
-scope = {
- fork,
- time = 5s later,
- ...
- remember = \forkb
-},
-scope = {
- fork,
- time = 2s later,
- ...
- remember = \forkc
-},
-resume = {max(\forka,\forkb,\forkc)} % "join" the three forks
-\end{codeexample}
- \end{key}
-\end{key}
-
-
-\subsubsection{Values}
-\label{section-anim-def-values}
-
-\begin{key}{/tikz/animate/value=\meta{value}}
- This key sets the value of the next time--value pair created by |entry| to
- \meta{value}. The syntax of the \meta{value} is not fixed, it depends on
- the type of the attribute. For instance, for an attribute like |opacity|
- the \meta{value} must be an expression that can be evaluated to a number
- between 0 and 1; for the attribute |color| the \meta{value} must, instead,
- be a color; and so on. Take care that when a value contains a comma, you
- must surround it by braces as in |"{(1,1)}"|.
-
- The allowed texts for the \meta{value} is always the same as the one you
- would pass to the \tikzname\ option of the same name. For instance, since
- the \tikzname\ option |shift| expects a coordinate, you use coordinates as
- \meta{value} with the usual \tikzname\ syntax (including all sorts of
- extensions, the animation system calls the standard \tikzname\ parsing
- routines). The same is true of dimensions, scalar values, colors, and so
- on.
-
- In addition to the values normally use for setting the attribute, you can
- also (sometimes) use the special text |current value| as \meta{value}. This
- means that the value of the point in the timeline should be whatever the
- value the attribute has at the beginning of the timeline. For instance,
- when you write
- %
-\begin{codeexample}[code only]
-animate = { obj:color = { 0s = "current value", 2s = "white" } }
-\end{codeexample}
- %
- the color of |obj| will change from whatever color it currently has to
- white in two seconds. This is especially useful when several animations are
- triggered by user events and the current color of |obj| cannot be
- determined beforehand.
-
- There are several limitations on the use of the text |current value|, which
- had to be imposed partly because of the limited support of this feature in
- \textsc{svg}:
- %
- \begin{itemize}
- \item You can use |current value| only with the first time in a
- timeline.
- \item You can only have two times in a timeline that starts with
- |current value|.
- \item You cannot use |current value| for timelines of which you wish to
- take a snapshot.
- \end{itemize}
-\end{key}
-
-
-\subsubsection{Scopes}
-\label{section-anim-scopes}
-
-When you specify multiple timelines at the same time, it is often useful and
-sometimes even necessary to have keys be set only locally. The following key
-makes this easy:
-
-\begin{key}{/tikz/animate/scope=\meta{options}}
- Executed the \meta{options} inside a \TeX\ scope. In particular, all
- settings made inside the scope have no effect after the end of the |scope|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node [animate = { myself: = { begin on = click,
- scope = { attribute = fill, repeats = 3, 0s = "red", 2s = "red!50" },
- scope = { attribute = draw, 0s = "red", 2s = "red!50" }
- }},
- fill=blue!20, draw=blue, very thick, circle] {Click me};
-\end{codeexample}
-
- Without the use of the |scope| key, the |repeats| key would also affect the
- draw attribute.
-\end{key}
-
-While the |scope| key is useful for structuring timeline code, it also keeps
-the current time local to the scope, that is, if you use something like
-|1s later| after the scope, this will refer to one second after the last use of
-|time| \emph{before} the scope. The times set inside the |scope| do not matter.
-While this is desirable effect for forks, you may also sometimes wish to
-synchronize the local time after the scope with the last time reached in the
-scope. The following key makes this easy:
-
-\begin{key}{/tikz/animate/sync=\meta{options}}
- A shorthand for |scope={| \meta{options} |, remember=\temp},resume=\temp|
- where |\temp| is actually an internal name. The effect is that after a
- |sync| the local time just continues as if the scope where not present --
- but regarding everything else the effects are local to the |sync| scope.
-\end{key}
-
-
-\subsection{Syntactic Simplifications}
-\label{section-anim-syntax-animate}
-
-In the previous subsection we saw how timelines can be created by specifying
-the individual entries of the timelines sequentially. However, most of the time
-you will wish to use a simpler syntax that makes it easier to specify
-animations. This syntax is only available inside the |animate| key (it is
-switched on at the beginning) and consists of three ``parts'': The colon
-syntax, the time syntax, and the quote syntax.
-
-
-\subsubsection{The Colon Syntax I: Specifying Objects and Attributes}
-\label{section-anim-syntax-obj}
-
-Inside the \meta{animation specification} passed to the |animate| key, you can
-specify an object and an attribute of this object using the following syntax,
-whose use is detected by the presence of a colon inside a key:
-%
-\begin{quote}
- \normalfont
- \opt{\meta{object name(s)}}|:|\opt{\meta{attribute(s)}}
- |={|\meta{options}|}|
-
- or
-
- \opt{\meta{object
- name(s)}}|:|\opt{\meta{attribute(s)}}|_|\opt{\meta{id}}
- |={|\meta{options}|}|
-\end{quote}
-%
-In the place to the left of an equal sign, where you would normally use a key,
-you can instead place an object name and an attribute separated by a colon.
-Additionally, the attribute may be followed by an underscore and an \meta{id},
-which identifies the timeline (see Section~\ref{section-anim-def-id}).
-
-Each of these values may be missing, in which case it is not changed from its
-previous value.
-
-The effect of the above code is the same as:
-%
-\begin{quote}
- \normalfont
- |sync = { object = |\meta{objects}|, attribute = |\meta{attribute}|, id = |\meta{id}|, |\meta{options}|, entry }|
-\end{quote}
-%
-although when the object, the attribute, or the id is left empty in the colon
-syntax, the corresponding setting will be missing in the above call of |sync|.
-Note that because of the |sync| the last time used inside the \meta{options}
-will be available afterwards as the last time. Also note that an |entry| is
-added at the end, so any settings of keys like |begin| or |repeats| inside the
-\meta{options} will get added to the timeline.
-
-Let us now have a look at some examples. First, we set the \meta{object name}
-to |mynode| and |othernode| and the \meta{attribute} to |opacity| and to
-|color|:
-%
-\begin{codeexample}[code only]
-animate = {
- mynode:opacity = { 0s = "1", 5s = "0" },
- mynode:color = { 0s = "red", 5s = "blue" },
- othernode:opacity = { 0s = "1", 5s = "0" },
-}
-\end{codeexample}
-
-Next, we do the same, but ``in two steps'': First, we set the object to
-|mynode|, but leave the attribute open and, then, set the attribute, but leave
-the object:
-%
-\begin{codeexample}[code only]
-animate = {
- mynode: = {
- :opacity = { 0s = "1", 5s = "0" },
- :color = { 0s = "red", 5s = "blue" }
- },
- othernode:opacity = { 0s = "1", 5s = "0" },
-}
-\end{codeexample}
-%
-Note how both in |mynode:| and in |:opacity| and |:color| you must provide the
-colon. Its presence signals that an object--attribute pair is being specified;
-only now either the object or the attribute is missing.
-
-We can also do it the other way round:
-%
-\begin{codeexample}[code only]
-animate = {
- :opacity = {
- mynode: = { 0s = "1", 5s = "0" },
- othernode: = { 0s = "1", 5s = "0" }
- },
- mynode:color = { 0s = "red", 5s = "blue" }
-}
-\end{codeexample}
-%
-Finally, if several objects should get the exact same values, we can also group
-them:
-%
-\begin{codeexample}[code only]
-animate = {
- {mynode,othernode}:opacity = { 0s = "1", 5s = "0" },
- mynode:color = { 0s = "red", 5s = "blue" }
-}
-\end{codeexample}
-
-As mentioned earlier, all references to objects will be interpreted to future
-objects, never to objects already created. Furthermore, also as mentioned
-earlier, \tikzname\ allows you to specify |myself| as \meta{object}, which is
-interpreted as the scope or node where the |animate| is given (you cannot
-animate a node or scope named |myself|, this special name always refers to the
-current node). In order to have all attributes refer to the current object, you
-write:
-%
-\begin{codeexample}[code only]
-\begin{scope} [animate = {
- myself: = { % Animate the attribute of the scope
- :opacity = { ... },
- :xshift = { ... }
- }
- }]
- ...
-\end{scope}
-\end{codeexample}
-
-The list of permissible attributes is given in
-Section~\ref{section-anim-attrs}.
-
-
-\subsubsection{The Colon Syntax II: Animating Myself}
-
-A frequent use of the |animate| key is for animating attributes of the current
-object |myself|. In these cases, it is a bit length to write
-%
-\begin{codeexample}[code only]
-[animate = { myself: = { :some attribute = {...} } } ]
-\end{codeexample}
-%
-\noindent in the options of a node or a scope. For this reason, \tikzname\
-allows you to use a special syntax with nodes and scopes:
-%
-\begin{enumerate}
- \item In a \meta{node specification}, which is everything following a
- |node| command up to the content of the node (which is surrounded by
- curly braces), you can write
- %
- \begin{quote}
- |:some attribute = {|\meta{options}|}|
- \end{quote}
- %
- and this will have the same effect as if you had written
- %
- \begin{quote}
- |[animate = { myself: = { :some attribute = {|\meta{options}|}}}]|
- \end{quote}
- %
- Note that you can use this syntax repeatedly, but each use creates a
- new use of the |animate| key, resulting in a new timeline. In order to
- create complex timelines for several objects, use the |animate| key.
- \item For the commands |\tikz|, |\scoped| and the environments
- |{tikzpicture}| and |{scope}|, when they are followed immediately by
- %
- \begin{quote}
- |:some attribute = {|\meta{options}|}|
- \end{quote}
- %
- then
- %
- \begin{quote}
- |animate = { myself: = { :some attribute = {|\meta{options}|}}}|
- \end{quote}
- %
- is added to the options of the command or scope. Again, you can use the
- syntax repeatedly. Note that when an opening square bracket is
- encountered, this special parsing stops.
-\end{enumerate}
-
-Let us have a look at some examples. First, we use the syntax to set the fill
-opacity of a node:
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node
- :fill opacity = { 0s="1", 2s="0", begin on=click }
- [fill = blue!20, draw = blue, ultra thick, circle] {Here!};
-\end{codeexample}
-%
-Next, we additionally rotate the node:
-%
-\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] {Here!};
-\end{codeexample}
-%
-Note that there is no comma between consecutive uses of the colon syntax in
-this case. We could have exchanged the order of the options and the uses of the
-colon syntax:
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node
- :fill opacity = { 0s="1", 2s="0", begin on=click }
- [fill = blue!20, draw = blue, ultra thick, circle]
- :rotate = { 0s="0", 2s="90", begin on=click } {Here!};
-\end{codeexample}
-
-We can also use the special syntax with the |\tikz| command itself:
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz :fill opacity = { 0s="1", 2s="0", begin on=click }
- :rotate = { 0s="0", 2s="90", begin on=click }
- [ultra thick]
- \node [fill = blue!20, draw = blue, circle] {Here!};
-\end{codeexample}
-
-Note that we could \emph{not} have moved the |[ultra thick]| options before
-|:rotate| since the options in square brackets end the special parsing.
-
-
-\subsubsection{The Time Syntax: Specifying Times}
-
-For each object--attribute pair you must specify the \emph{timeline} of the
-attribute. This is a curve that specifies for each ``moment in time'' which
-value the attribute should have. In the simplest case, you specify such a
-time--value pair as follows:
-%
-\begin{quote}
- \normalfont
- \meta{time} |="|\meta{value}|"|
-\end{quote}
-
-When you specify time--value pairs, you must specify the times in chronological
-order (so earlier times come first), but you may specify the same time several
-times (this is useful in situations where you have a ``jump'' from one value to
-another at a certain moment in time: you first specify the value ``from which
-the attribute jumps'' and then you specify the value ``to which the attribute
-jumps'' for the same moment).
-
-The above syntax is just a special case of a more general situation. Let us
-start with the times. The general syntax for specifying times is as follows:
-%
-\begin{quote}
- \normalfont
- \meta{time} \opt{|=| \meta{options}}
-\end{quote}
-
-Here, \meta{time} is a text that ``looks like a time'', which means that:
-%
-\begin{enumerate}
- \item It is not a key and does not contain a colon and does not start with
- a quotation mark.
- \item It starts with a digit, a plus or minus sing, a dot, or a
- parenthesis.
-\end{enumerate}
-
-If these two things are the case, the above code is transformed to the
-following call:
-%
-\begin{quote}
- \normalfont
- |sync = {time = |\meta{time}|, |\meta{options}|, entry}|
-\end{quote}
-
-
-\subsubsection{The Quote Syntax: Specifying Values}
-
-We saw already in several examples that values are put in quotation marks
-(similar to the way this is done in \textsc{xml}). This quote syntax is as
-follows:
-%
-\begin{quote}
- \normalfont
- |"|\meta{value}|"| \opt{|base|} \opt{|=| \meta{options}}
-\end{quote}
-
-This syntax is triggered whenever a key starts with a quotation mark%
-\footnote{Of catcode 12 for those knowledgeable of such things.} (and note that
-when the \meta{value} contains a comma, you have to surround it by curly braces
-\emph{inside} the quotation marks as in |"{(1,1)}"|). Then, the following code
-is executed:
-%
-\begin{quote}
- \normalfont
- |sync = {value = |\meta{value}|, |\meta{options}|, entry}|
-\end{quote}
-
-This means that when you write |1s = "red"|, what actually happens is that
-\tikzname\ executes the following:
-%
-\begin{codeexample}[code only]
-sync = { time = 1s, sync = { value = red, entry }, entry }
-\end{codeexample}
-%
-Note that the second entry has no effect since no value is specified and the
-|entry| key only ``takes action'' when both a time and a value have been
-specified. Thus, only the innermost |entry| does, indeed, create a time--value
-pair as desired.
-
-In addition to the above, if you have added |base| after the closing quote, the
-following gets executed before the above |sync|:
-%
-\begin{quote}
- \normalfont
- |base = {value = |\meta{value}|}|
-\end{quote}
-
-This makes it easy to specify base values for timelines.
-
-Interestingly, instead of |1s="red"| you can also write |"red"=1s|. Let us now
-have a look at situations where this can be useful.
-
-
-\subsubsection{Timesheets}
-
-Using the |sync| key or using the three different syntactic constructs
-introduced earlier (the color syntax, the time syntax, the value syntax), you
-can organize the specification of an animation in different ways. Basically,
-the two most useful ways are the following:
-%
-\begin{enumerate}
- \item You first select an object and an attribute for which you wish to
- establish a timeline and then provide the time--value pairs in a
- sequence:
- %
-\begin{codeexample}[code only]
-animate = {
- obj:color = {
- 0s = "red",
- 2s = "blue",
- 1s later = "green",
- 1s later = "green!50!black",
- 10s = "black"
- }
-}
-\end{codeexample}
- %
- When you specify timelines for several attributes of the same object,
- you can group these together:
- %
-\begin{codeexample}[code only]
-animate = {
- obj: = {
- :color = { 0s = "red", 2s = "green" },
- :opacity = { 0s = "1", 2s = "0" }
- }
-}
-\end{codeexample}
- %
- In this way of specifying animations the ``object comes first''.
- \item Alternatively, you can also group the animation by time and, for each
- ``moment'' (known as \emph{keyframes}) you specify which values the
- attributes of the object(s) have:
- %
-\begin{codeexample}[code only]
-animate = {
- 0s = {
- obj:color = "red",
- obj:opacity = "1"
- },
- 2s = {
- obj:color = "green",
- obj:opacity = "0"
- }
-}
-\end{codeexample}
- %
- Naturally, in this case it would have been better to ``move the object
- outside'':
- %
-\begin{codeexample}[code only]
-animate = {
- obj: = {
- 0s = {
- :color = "red",
- :opacity = "1"
- },
- 2s = {
- :color = "green",
- :opacity = "0"
- }
- }
-}
-\end{codeexample}
- %
- When there are several objects involved, we can mix all of these
- approaches:
- %
-\begin{codeexample}[code only]
-animate = {
- 0s = {
- obj: = {
- :color = "red",
- :opacity = "1"
- },
- main node: = {
- :color = "black"
- }
- },
- 2s = {
- obj: = {
- :color = "green",
- :opacity = "0"
- },
- main node: = {
- :color = "white"
- }
- }
-}
-\end{codeexample}
- %
-\end{enumerate}
-
-
-\subsection{The Attributes That Can Be Animated}
-\label{section-anim-attrs}
-
-The following \meta{attributes} are permissible (actually, the attribute names
-do not include a colon, but since they will almost always be used with the
-colon syntax, it makes it easier to identify them):
-%
-\begin{itemize}
- \itemsep0pt
- \item |:dash phase|
- \item |:dash pattern|
- \item |:dash|
- \item |:draw opacity|
- \item |:draw|
- \item |:fill opacity|
- \item |:fill|
- \item |:line width|
- \item |:opacity|
- \item |:position|
- \item |:path|
- \item |:rotate|
- \item |:scale|
- \item |:stage|
- \item |:text opacity|
- \item |:text|
- \item |:translate|
- \item |:view|
- \item |:visible|
- \item |:xscale|
- \item |:xshift|
- \item |:xskew|
- \item |:xslant|
- \item |:yscale|
- \item |:yshift|
- \item |:yskew|
- \item |:yslant|
-\end{itemize}
-
-These attributes are detailed in the following sections, but here is a quick
-overview of those that do not have a \tikzname\ key of the same name (and which
-thus do not just animate the attribute set using this key):
-%
-\begin{itemize}
- \item |:shift| allows you to add an animated shifting of the canvas, just
- like \tikzname's |shift| key. However, in conjunction with the |along|
- key, you can also specify the shifting along a path rather than via a
- timeline of coordinates.
- \item |:position| works similar to |:shift|, only the coordinates are not
- relative movements (no ``shifts''), but refer to ``absolute positions''
- in the picture.
- \item |:path| allows you to animate a path (it will morph). The ``values''
- are now paths themselves.
- \item |:view| allows you to animate the view box of a view.
- \item |:visible| decides whether an object is visible at all.
- \item |:stage| is identical to |:visible|, but when the object is not
- animated, it will be hidden by default.
-\end{itemize}
-
-
-\subsubsection{Animating Color, Opacity, and Visibility}
-\label{section-animation-painting}
-
-You can animate the color of the target object of an animation using the
-attributes |fill|, |draw|, and |text|. When the target of a color animation is
-a scope, you animate the color ``used in this scope'' for filling or stroking.
-However, when an object inside the scope has its color set explicitly, this
-color overrules the color of the scope.
-
-\begin{tikzanimateattribute}{fill, draw}
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz :fill = {0s = "red", 2s = "blue", begin on = click}
- [text = white, fill = orange ] {
- \node [fill] at (0mm,0) {A};
- \node [fill] at (5mm,0) {B};
- \node [fill = green!50!black ] at (1cm,0) {C};
-}
-\end{codeexample}
-\end{tikzanimateattribute}
-
-\begin{tikzanimateattribute}{text}
- The |text| attribute only applies to nodes and you need to directly animate
- the |text| attribute of each node individually.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [my anim/.style={ animate = {
- myself:text = {0s = "red", 2s = "blue", begin on = click}}},
- text = white, fill = orange ] {
- \node [fill, my anim] at (0,0) {A};
- \node [fill, my anim] at (1,0) {B};
-}
-\end{codeexample}
- %
- Unlike the |fill| and |draw| colors, you cannot animate the |text| color
- for scopes:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz [animate = {myself:text = {0s = "red", 2s = "blue",
- begin on = click}},
- text = white, fill = orange ] {
- \node [fill] at (0,0) {A};
- \node [fill] at (1,0) {B};
-}
-\end{codeexample}
- %
-\end{tikzanimateattribute}
-
-\begin{tikzanimateattribute}{color}
- The |color| attribute is not really an attribute. Rather, it is a shorthand
- for |{draw,fill,text}|. This means that |color| does not start a separate
- timeline, but continues the |draw| timeline, the |fill| timeline, and the
- |text| timeline.
-\end{tikzanimateattribute}
-
-\begin{tikzanimateattribute}{opacity, fill opacity, stroke opacity}
- Similarly to the color, you can also set the opacity used for filling and
- for drawing using the attributes |fill opacity| and |draw opacity|, which
- are exactly the same as the usual \tikzname\ keys of the same names.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :fill opacity = { 0s="1", 2s="0", begin on=click }
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
- Unlike colors, where there is no joint attribute for filling and stroking,
- there is a single |opacity| attribute in addition to the above two
- attributes. If supported by the driver, it treats the graphic object to
- which it is applied as a transparency group. In essence, ``this attribute
- does what you want'' at least in most situations.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :opacity = { 0s="1", 2s="0", begin on=click }
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
-\end{tikzanimateattribute}
-
-\begin{tikzanimateattribute}{visible, stage}
- The difference between the |visible| attribute and an opacity of |0| is
- that an invisible object cannot be clicked and does not need to be
- rendered. The (only) two possible values for this attribute are |false| and
- |true|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4},
-]
-\tikz :visible = {begin on=click, 0s="false", 2s="false"}
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-\end{codeexample}
-
- This |stage| attribute is the same as the |visible| attribute, only
- |base="false"| is set by default. This means that the object is \emph{only}
- visible when you explicitly during the time the entries are set to |true|.
- The idea behind the name ``stage'' is that the object is normally ``off
- stage'' and when you explicitly set the ``stage attribute'' to |true| the
- object ``enters'' the stage and ``leaves'' once more when it is no longer
- ``on stage''.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={-1,0,1,2,3},
- animation bb={(1.3,-0.7) rectangle (2.7,0.7)},
-]
-\tikz [animate = {example:stage = {
- begin on = {click, of next=node},
- 0s="true", 2s="true" }}] {
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
- \node at (2,0) (example) [fill = blue!20, circle] {Effect};
-}
-\end{codeexample}
-\end{tikzanimateattribute}
-
-
-\subsubsection{Animating Paths and their Rendering}
-\label{section-animation-paths}
-
-The attributes of the appearance of a path that you can animate include the
-line width and the dash pattern, the path itself, as well as the arrow tips
-attached to the paths. Animating the line width and the dash pattern is easy
-since the animation attributes simply have that same names as the properties
-that they animate and the syntax for setting is also the same:
-
-\begin{tikzanimateattribute}{line width}
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :line width = { 0s="1pt", 2s="5mm", begin on=click}
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
- Note that you must specify number (or expressions that evaluate to numbers)
- as values, you cannot say |thin| or |thick| (these are styles, internally,
- and you also cannot say |line width=thick|).
-\end{tikzanimateattribute}
-
-\begin{tikzanimateattribute}{dash, dash phase, dash phase}
- The values for an animation of the dashing are specifications (see the
- |dash| key for details) consisting of a sequence of |on| and |off| numbers.
- In each value of the animation the length of these sequences \emph{must} be
- identical. The interpolation of the values is done for each position of the
- sequences individually, and also on the phase.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :dash = { 0s="on 10pt off 1pt phase 0pt",
- 2s="on 1pt off 10pt phase 0pt", begin on=click}
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :dash = { 0s="on 1cm off 1pt phase 0pt",
- 2s="on 1cm off 1pt phase 1cm", begin on=click}
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
-
- This |dash pattern| key allows you to animate the dash phase only. However,
- due to the way dashing is handled by certain drivers, the dash pattern is
- also set, namely to the current dash pattern that is in force when the
- animation is created.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :dash phase = { 0s="0pt", 2s="1cm", begin on=click}
- [fill = blue!20, draw = blue, ultra thick, circle, dashed] {Click me!};
-\end{codeexample}
- %
-\end{tikzanimateattribute}
-
-The above attributes ``only'' influence how the path is rendered. You can,
-however, also animate the path itself:
-
-\begin{tikzanimateattribute}{path}
- When you animate a path, the values are, of course, paths themselves:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :path = {
- 0s = "{(0,-1) .. controls (0,0) and (0,0) .. (0,1) -- (1,1)}",
- 2s = "{(0,-1) .. controls (-1,0) and (-1,0) .. (-1,1) -- (.5,-1)}",
- begin on=click }
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
- There a number of things to keep in mind when you animate a path:
- %
- \begin{itemize}
- \item The path ``values'' are parsed and executed in an especially
- protected scope to ensure that they have only little side effects,
- but you should not do ``fancy things'' on these paths.
- \item As for the dash pattern, you must ensure that all paths in the
- timeline have the same structure (same sequence of path
- construction commands); only the coordinates may differ. In
- particular, you cannot say that the path at |1s| is a rectangle
- using |rectangle| and at |2s| is a circle using |circle|. Instead,
- you would have to ensure that at both times the path consists of
- appropriate Bézier curves (which is cumbersome as the following
- example shows, where we used the fact that a circle consists of
- four Bézier curves):
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :path = {
- 0s = "{(0,0) circle [radius=1cm]}",
- 2s = "{(0,0)
- (1,0) .. controls +(0,0) and +(0,0) .. (0,1)
- .. controls +(0,0) and +(0,0) .. (-1,0)
- .. controls +(0,0) and +(0,0) .. (0,-1)
- .. controls +(0,0) and +(0,0) .. (1,0)
- -- cycle (0,0)}",
- begin on=click}
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
- \item You must specify arrow tips for an animated path in a special
- way, namely using the |arrows| key for \emph{animations}, not the
- normal |arrows| key (see below).
- \end{itemize}
-\end{tikzanimateattribute}
-
-\begin{key}{/tikz/animate/arrows=\meta{arrow spec}}
- This key only has an effect on |:path| animations. It causes the arrow tips
- specified in \meta{arrow spec} to be added to the path during the animation
- (the syntax is the same as for the normal |arrows| key). If you have
- several different animations for a paths, these may contain different arrow
- tips, but each animation must stick to one kind of arrow tips.
-
- What happens internally when this key is used is the following: The
- specified arrow tips are rendered internally as so-called \emph{markers,}
- which are small graphics that can be placed at the beginning and ends of
- paths and which ``rotate along'' as a path changes. Note that these markers
- are used \emph{only} in the context of animated paths, the arrow tips of
- normal, ``static'' paths are drawn without the use of markers. Normally,
- there is no visual difference between an arrow tip drawn using markers or
- those drawn for static paths, but in rare cases there may be differences.
- You should only add arrows to open path consisting of a single segment with
- sufficiently long first and last segments (so that \tikzname\ can shorten
- these segments correctly when necessary).
-
- As pointed out earlier, the only way to add arrow tips to a path that is
- animated is using this key, you can \emph{not} say something like
- %
-\begin{codeexample}[code only]
-\draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}" }
- [->] (0,0) -- (1,0);
-\end{codeexample}
- %
- This will raise an error since you try to animate a path (|:path = ...|)
- that has normal arrow tips attached (|[->]|).
-
- Instead, you must specify the arrow tips inside the animation command:
- %
-\begin{codeexample}[code only]
-\draw :path = { 1s = "{(0,0) -- (1,0)}", 2s = "{(0,1) -- (1,0)}", arrows = -> }
- (0,0) -- (1,0);
-\end{codeexample}
-
- However, the above code now has a big shortcoming: While the animation is
- \emph{not} running, \emph{no} arrow tip is shown (the |arrows| key only
- applies to the animation.
-
- The trick is to use the |base| key. It allows you to install a path as the
- ``base'' path that is used when no animation is running and the arrows
- specified for the animation will also be used for the base. All told, the
- ``correct'' way to specify the animation is the following (note that no
- static path is specified, any specified path would be overruled by the
- |base| path anyway):
- %
-\begin{codeexample}[code only]
-\draw :path = { 1s = "{(0,0) -- (1,0)}" base, 2s = "{(0,1) -- (1,0)}", arrows = -> };
-\end{codeexample}
-
- Here is an example:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
- animation bb={(-0.1,-0.1) rectangle (1.1,1.1)},
-]
-\tikz [very thick] {
- \node (node) at (-2,0)
- [fill = blue!20, draw = blue, very thick, circle] {Click me!};
- \draw :path = {
- 0s = "{(0,0) to[out=90, in=180] (.5,1) to[out=0, in=90] (.5,.5)}" base,
- 2s = "{(1,0) to[out=180, in=180] (.25,.5) to[out=0, in=180] (1,.5)}",
- arrows = <.<->, begin on = {click, of=node} }; }
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/animate/shorten < = \meta{dimension}}
-\end{key}
-
-\begin{key}{/tikz/animate/shorten > = \meta{dimension}}
- For animated paths, just as the key |arrows| has to be passed to the
- animation (to |:path|) instead of to the static path, the keys |shorten >|
- and |shorten <| also have to be passed to the |:path| key.
-\end{key}
-
-
-\subsubsection{Animating Transformations: Relative Transformations}
-
-In order to animate the canvas transformation matrix, you do not animate an
-attribute called ``|:transform|''. Rather, there are several attributes that
-all manipulate the canvas transformation matrix in different ways. These keys,
-taken in appropriate combination, allow you to achieve any particular canvas
-transformation matrix. All keys that animate the transformation matrix always
-accumulate.
-
-Let us start with the ``standard'' attributes that are also available as keys
-in \tikzname:
-
-\begin{tikzanimateattribute}{scale, xscale, yscale}
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :scale = { 0s="1", 2s="0.2", begin on=click}
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
-\end{tikzanimateattribute}
-
-\begin{tikzanimateattribute}{rotate}
- The |rotate| key adds an animation of the rotation:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :rotate = { 0s="45", 2s="90", begin on=click}
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
- Note that there is no |rotate around| attribute, but you can use the
- |origin| key to change the origin of the rotation.
-\end{tikzanimateattribute}
-
-\begin{tikzanimateattribute}{xskew, yskew, xslant, yslant}
- The keys add an animation of the skew (given in degrees) or slant (given as
- in the |xslant| and |yslant| key):
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :xskew = { 0s="0", 2s="45", begin on=click}
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :xslant = { 0s="-1", 2s="1", begin on=click}
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
-\end{tikzanimateattribute}
-
-\begin{tikzanimateattribute}{xshift, yshift}
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :shift = { 0s="{(0,0)}", 2s="{(5mm,-5mm)}",
- begin on=click}
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
-
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :xshift = { 0s="0pt", 2s="5mm", begin on=click}
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
-\end{tikzanimateattribute}
-
-\begin{tikzanimateattribute}{shift}
- This |:shift| attribute can be animated in two ways. First, you can simply
- specify a sequence of coordinates in the same way as you would use the
- |shift| key in \tikzname:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz \node :shift = { 0s = "{(0,0)}", 2s = "{(5mm,-5mm)}",
- begin on = click }
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
-
- However, you can also specify the sequence of positions along which the
- shift should occur in a different way, namely by \emph{specifying a path
- along which the object should be moved.} This is often not only more
- natural to do, but also allows you to specify movements along curves.
-
- \begin{key}{/tikz/animate/options/along=\marg{path}\meta{|sloped| or
- |upright|}\opt{| in|\meta{time}}%
- }
- Use this key with a |:shift| (or a |:position|) to make \tikzname\
- shift the object by the coordinates along the \meta{path}. When this
- key is used, the values may no longer be coordinates, but must be
- fractions of the distance along the path. A value of |"0"| refers to
- the beginning of the path and |"1"| refers to the end:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
- \draw (1,.5) circle [radius=1mm];
- \node :shift = {
- along = {(0,0) circle[radius=5mm]} upright,
- 0s="0", 2s=".25", begin on=click }
- at (1,.5) [fill = blue, opacity=.5, circle] {Click};
-}
-\end{codeexample}
- \end{key}
-
- Following the \meta{path}, which must be put in braces, you must either
- specify |upright| or |sloped|. In the first case, the to-be-animated object
- is moved along the path normally (and stays ``upright''), whereas when you
- use |sloped|, the object will be continuously rotated so that it always
- points along the path.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
- \draw (1,.5) circle [radius=1mm];
- \node :shift = {
- along = {(0,0) circle[radius=5mm]} sloped,
- 0s="0", 2s=".25", begin on=click }
- at (1,.5) [fill = blue, opacity=.5, circle] {Click};
-}
-\end{codeexample}
-
- In most motion animations that use |along|, you will set the value for |0s|
- to |"0"| and the value for some specific \meta{time} to |"1"|. Because of
- this, you can add |in| \meta{time} after the path, to achieve exactly this
- effect.
-\end{tikzanimateattribute}
-
-For the above attributes, it is not immediately clear which coordinate system
-should be used for the animation. That is, when you move an object 1cm ``to the
-right'', where is ``the right''? By default, movements and transformations like
-|:shift| or |:scale| are relative to the \emph{animation coordinate system,}
-which defaults to the local coordinate system of the to-be-animated object.
-Consider the following example:
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
- \node :rotate = { 0s="0", 2s="45", begin on=click}
- at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
-}
-\end{codeexample}
-%
-Note how the node rotates around its center even though this center is at
-position |(1,1)| in the picture's coordinate system. This is because |at (1,1)|
-actually only does a shift of the coordinate system and the node is then drawn
-at the origin of this shifted coordinate system. Since this shifted coordinate
-system becomes the animation coordinate system, the rotation ``around the
-origin'' is actually a rotation around the origin of the animation coordinate
-system, which is at |(1,1)| in the picture's coordinate system.
-
-Let us, by comparison, do a rotation of a scope surrounding the node where the
-origin is not (yet) shifted:
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
- \scoped :rotate = { 0s="0", 2s="45", begin on={click, of next=n} }
- \node (n) at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
-}
-\end{codeexample}
-%
-Now the rotation is really around the origin of the picture.
-
-Most of the time the animation coordinate system will be setup in the way ``you
-expect'', but you can modify it using the following keys:
-
-\begin{key}{/tikz/animate/options/origin=\meta{coordinate}}
- Shifts the animation coordinate system by \meta{coordinate}. This has the
- effect that the ``origin'' for scalings and rotations gets shifted by this
- amount. In the following example, the point around which the rotation is
- done is the right border at |(2,1)| since the origin of the animation is at
- |(1,1)| relative to the picture's origin and the |origin| key shifts it one
- centimeter to the right.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
- \node :rotate = { 0s="0", 2s="45", begin on=click,
- origin = {(1,0)}}
- at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
-}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/animate/options/transform=\meta{transformation keys}}
- While the |origin| key does only a shift, the |transform| key allows you to
- add an arbitrary transformation to the animation coordinate system using
- keys like |shift|, |rotate| or even |reset cm| and |cm|. In particular,
- |origin=|\meta{c} has the same effect as |transform| |=|
- |{shift=|\meta{c}|}|. Note that the transformation only influences the
- animation, not the object itself.
-
- As an example, when you say |transform={scale=2}|, an |:xshift| with a
- value of |"1cm"| will actually shift the object by 2cm. Similarly, after
- you say |transform={rotate=90,scale=2}|, the same |:xshift| of |"1cm"| will
- actually shift the object by 2cm upwards.
-
- Note that, internally, \tikzname\ has to invert the transformation matrix
- resulting from the \meta{transformation keys} (plus the original animation
- transformation matrix), which can by numerically instable when you use
- ill-conditioned transformations.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
- \node :xshift = { 0s="0cm", 2s="5mm", begin on=click,
- transform = {rotate=-90} }
- at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
-}
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \draw [help lines] (-0.2,-0.2) grid (2.2,2.2);
- \node :xshift = { 0s="0cm", 2s="5mm", begin on=click,
- transform = {rotate=-45, scale=2} }
- at (1,1) [fill = blue!20, draw = blue, ultra thick] {Click me};
-}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Animating Transformations: Positioning}
-
-The attributes for specifying transformations and, in particular, the |:shift|
-attribute are always expressed in the local animation coordinate system. This
-makes it easy to ``shift around a node a little bit'', but makes it hard to
-move a node ``from one position to another'' since coordinates need to be
-expressed relative to the node's coordinate system, which leads to all sorts of
-problems: Suppose you wish to have a node move from $(1,1)$ to $(2,1)$ and then
-to $(2,0)$. Now, if the node has already been placed at $(1,1)$ in the usual
-manner using |at|, then from the ``node's point of view'' you need to move the
-node to $(0,0)$, $(1,0)$, and $(1,-1)$. To make matters worse, when you use
-named coordinates as in
-%
-\begin{codeexample}[code only]
-\coordinate(A) at (1,1);
-\coordinate(B) at (2,1);
-\coordinate(C) at (2,0);
-\end{codeexample}
-%
-and then say that the movement should be from |(A)| to |(B)| to |(C)|, what
-should you expect? On the one hand, |(A)| and |(1,1)| should normally be
-interchangeable; on the other hand, |(A)| is a specific point in the plane, no
-matter from which coordinate system we look at it. It turns out that \tikzname\
-will stick to the second interpretation and actually turn |(A)| into |(0,0)|
-when it is parsed in the local coordinate system of a node starting at |(A)| --
-while |(1,1)| will stay the same.
-
-Because of all these confusing effects, there is another attribute |:position|,
-which is similar to a |:shift|, but the coordinates are not interpreted in the
-local coordinate system of the node, but in the coordinate system that is in
-force when the |animate| key is used. For a node, this is \emph{prior} to the
-setup of the node's coordinate system and, thus, usually the picture's
-coordinate system.
-
-\begin{tikzanimateattribute}{position}
- Compare the two animations, one with |:position|, one with |:shift|.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
- \draw (1,.5) circle [radius=1mm] (1.5,0) circle [radius=1mm];
- \node :position = { 0s="{(1,.5)}", 2s="{(1.5,0)}", begin on=click }
- at (1,.5) [fill = blue, opacity=.5, circle] {Click};
-}
-\end{codeexample}
- %
- Compare this to a shift:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
- \draw (1,.5) circle [radius=1mm] (1.5,0) circle [radius=1mm];
- \node :shift = { 0s="{(1,.5)}", 2s="{(1.5,0)}", begin on=click }
- at (1,.5) [fill = blue, opacity=.5, circle] {Click};
-}
-\end{codeexample}
- %
- You can use the |along| key with |:position| in the same way as with
- |:shift|, which is especially useful for specifying that a node ``travels''
- between positions of the canvas:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
-]
-\tikz {
- \draw [help lines] (-0.2,-0.2) grid (2.2,1.2);
- \draw (1,1) circle [radius=1mm] (1.5,0) circle [radius=1mm];
- \node :position = {
- along = {(1,1) to[bend left] (1.5,0)} sloped in 2s,
- begin on = click }
- at (1,1) [fill = blue, opacity=.5, circle] {Click};
-}
-\end{codeexample}
- %
-\end{tikzanimateattribute}
-
-
-\subsubsection{Animating Transformations: Views}
-\label{section-animation-views}
-
-The final method of changing the transformation matrix is to animate a
-\emph{view}.
-
-\begin{tikzanimateattribute}{view}
- A view is a canvas transformation that shifts and scales the canvas in such
- a way that a certain rectangle ``matches'' another rectangle: The idea is
- that you ``look through'' a ``window'' (the view) and ``see'' a certain
- area of the canvas. View animation do not allow you to do anything that
- cannot also be done using the |shift| and |scale| keys in combination, but
- it often much more natural to animate which area of a graphic you wish to
- see than to compute and animate a scaling and shift explicitly.
-
- In order to use a view, you first need to create a view, which is done
- using the |meet| or |slice| keys from the |views| library, see
- Section~\ref{section-library-views}. You can then animate the view using
- the |view| attribute. The values passed to the |entry| key follow the same
- syntax as the views in the |views| library (though you only animate the
- to-be-viewed rectangle).
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations,views}},
- animation list={0.5,1,1.5,2},
- animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
-]
-\tikz [very thick] {
- \node (node) [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-
- \draw [green!50!black] (1.2,-0.8) rectangle (2.7,0.8);
- \begin{scope}[view = {(0,0) (2,2) at (1.2,-0.8) (2.7,0.8)},
- animate = {myself:view = {
- begin on = {click, of=node},
- 0s = "{(0,0) (2,2)}",
- 2s = "{(1,1) (1.5,1.5)}" }}]
- \draw [red] (10mm,10mm) rectangle (15mm,15mm);
- \node at (10mm,10mm) [circle, fill=red, text=white, font=\tiny] {red};
- \end{scope}
-}
-\end{codeexample}
- %
-\end{tikzanimateattribute}
-
-
-\subsection{Controlling the Timeline}
-\label{section-anim-timeline}
-
-We can already specify timelines by giving a sequence of times in
-non-decreasing order along with corresponding values. In this section we have a
-look at further options that allow us to extend or control the timeline.
-
-
-\subsubsection{Before and After the Timeline: Value Filling}
-
-When you specify the timeline, you specify it for a certain interval
-$[t_1,t_2]$. By default, outside this interval the animation has no effect on
-the to-be-animated attribute. The following keys allows you to change this:
-
-\begin{key}{/tikz/animate/base=\meta{options}}
- A ``base'' value is a value that is used for the attribute whenever the
- timeline is \emph{not} active:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list = {0.5,1,1.5,2,2.5},
-]
-\tikz \node [fill = green, text = white] :fill =
- { 1s = "red", 2s = "blue", base = "orange", begin on = click }
- {Click me};
-\end{codeexample}
-
- Syntactically, the |base| key works much like special time syntax: It sets
- up a local |sync| scope and executes the \meta{options} in it and creates
- an |entry|. However, instead of setting the |time| attribute to a time, it
- sets it to a special value that tells \tikzname\ that when the entry is
- created, the current \meta{value} should be used as the |base| value.
-
- This means that you can write |base = "orange"| as in the above example to
- set the base. However, you can also use the |base| key in other ways; most
- noticeably, you can use it \emph{after} some value:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list = {0.5,1,1.5,2,2.5},
-]
-\tikz \node [fill = green, text = white] :fill =
- { 1s = {"red" = base}, 2s = "blue", begin on = click }
- {Click me};
-\end{codeexample}
-
- Instead of using |base| as a key, you can also add |base| directly after
- the quotes of a value. This is particularly useful for setting up a base
- value that is also used in a timeline:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list = {0.5,1,1.5,2,2.5},
-]
-\tikz \node [fill = green, text = white] :fill =
- { 1s = "red" base, 2s = "blue", begin on = click }
- {Click me};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/animate/options/forever}
- This key causes the timeline to continue ``forever'' after the last time
- with the last value. You can also think of this as having the animation
- ``freeze'' at the end.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list = {0.5,1,1.5,2,2.5},
-]
-\tikz \node :fill = { 1s="red", 2s="blue", forever, begin on=click}
- [fill = green!50!black, text = white] {Click me};
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list = {0.5,1,1.5,2,2.5},
-]
-\tikz \node [fill = green!50!black, text = white]
- :fill = { 1s = "red", 2s = "blue", begin on = click }
- {Click me};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/animate/options/freeze}
- An alias for |forever|.
-\end{key}
-
-
-\subsubsection{Beginning and Ending Timelines}
-\label{section-anim-begin-end}
-
-The \meta{time} used with the first use of the |entry| key in a timeline is the
-start time and the \meta{time} in the last |entry| key is the stop time.
-However, this leaves open then question of when the whole timeline is to be
-started: The moment the document is opened? When the page is displayed? When
-the user scrolls to the to-be-animated object? When some other object is
-clicked? The key |begin|, and also the key |end|, allow you to specify answers
-to these questions.
-
-\begin{key}{/tikz/animate/options/begin=\meta{time}}
- This key specifies when the ``moment |0s|'' should be relative to the
- moment when the current graphic is first displayed. You can use this key
- multiple times, in this case the timeline is restarted for each of the
- times specified (if it is already running, it will be reset). If no |begin|
- key is given at all, the effect is the same as if |begin=0s| had been
- specified.
-
- It is permissible to set \meta{time} to a negative value.
-
- Note that this key has no effect for snapshots.
-\end{key}
-
-\begin{key}{/tikz/animate/options/end=\meta{time}}
- This key will truncate the timeline so that it ends \meta{time} after the
- display of the graphic, provided the timeline begins before the specified
- end time. For instance, if you specify a timeline starting at 2\,s and
- ending at 5\,s and you set |begin| to 1\,s and |end| to 4\,s, the timeline
- will run, relative to the moment when the graphic is displayed from 3\,s to
- 4\,s.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
-\tikz \node [fill = green!50!black, text = white]
- :rotate = { 1s = "0", 5s = "90", begin = 2s, end = 4s }
- {Click me};
-\end{codeexample}
- %
-\end{key}
-
-Instead of specifying the beginning of the timeline relative to the moment to
-to-be-animated graphic is displayed, you can also set the ``moment |0s|'' to
-the moment a specific \emph{event} happens using the following key:
-
-\begin{key}{/tikz/animate/options/begin on=\meta{options}}
- The \meta{options} will be executed with the path |/pgf/animation/events|
- and will cause a new beginning to be added to the list of possible
- beginnings for the timeline (so the uses of this key accumulate). Each
- ``beginning'' is just another possible ``moment |0s|'' for the timeline.
- For instance, when the \meta{options} are set to |click|, then each time
- the graph is clicked a moment |0s| starts for the timeline.
-
- Most events are ``caused'' or ``happen to'' some object. For instance, the
- |click| event happens when you click on a certain object. In order to
- specify this object, use the following two keys inside the \meta{options}:
- |of| and |of next|. If neither of these keys are given, the to-be-animated
- object is used.
-
- \begin{key}{/pgf/animation/events/of=\meta{id}\opt{|.|\meta{type}}}
- This specifies a graphic object id in the same way as the |whom| key,
- also with an optional \meta{type}. This is the object that ``causes''
- the event to happen.
-
- Unlike the |whom| key, which always refers to a not-yet-existing
- object, this key always refers to an already existing object, namely to
- the most recent use of the \meta{id}. In the following example, the
- referenced object is the node with the label |2| since it is the most
- recently referenced node with \meta{id} |X|.
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{animations}}]
-\tikz [very thick] {
- \node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1};
- \node (X) at (1,0.4) [fill = orange!20, draw = orange, circle] {2};
- \node (node) :rotate = {0s="0", 2s="90", begin on = {click, of = X}}
- [fill = red!20, draw = red, rectangle] {Anim};
- \node (X) at (1,-0.4) [fill = blue!20, draw = blue, circle] {3};
- \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; }
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/animation/events/of next=\meta{id}\opt{|.|\meta{type}}}
- This key works like the |of| key, only it refers to a future (actually,
- the next) object with the given \meta{id}, not to a previous one. This,
- in the next example, the referenced node is the one with label |3|.
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{animations}}]
-\tikz [very thick] {
- \node (X) at (1,1.2) [fill = blue!20, draw = blue, circle] {1};
- \node (X) at (1,0.4) [fill = blue!20, draw = blue, circle] {2};
- \node (node) :rotate = {
- 0s="0", 2s="90", begin on = {click, of next = X}}
- [fill = red!20, draw = red, rectangle] {Anim};
- \node (X) at (1,-0.4) [fill = orange!20, draw = orange, circle] {3};
- \node (X) at (1,-1.2) [fill = blue!20, draw = blue, circle] {4}; }
-\end{codeexample}
- \end{key}
-
- The following key allows you to specify the event that should cause the
- animation to start:
- %
- \begin{key}{/pgf/animation/events/event=\meta{event name}}
- Specifies the name of the event whose occurrence should start the
- timeline. Which events are supported depends on the device on which the
- animation is displayed, the output format (\textsc{svg} or some other
- format), and the setup of scripts, but here is a list of events
- supported by ``plain \textsc{svg}'': |click|, |focusin|, |focusout|,
- |mousedown|, |mouseup|, |mouseover|, |mousemove|, |mouseout|, |begin|,
- |end|. However, the following keys make using these events simpler:
- %
- \begin{key}{/pgf/animate/events/click}
- This is a shorthand for |event=click|. This event gets triggered
- when the user clicks on the triggering object with a mouse (or
- something equivalent).
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \node :rotate = { 0s="0", 2s="90", begin on = {click}}
- [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/animation/events/mouse down}
- Shorthand for |event=mousedown|. The event gets triggered when the
- user presses a mouse button down on the object.
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse down}}
- [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/animation/events/mouse up}
- Shorthand for |event=mouseup| and gets triggered, of course, when a
- pressed button is released on the object.
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse up} }
- [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/animation/events/mouse over}
- Shorthand for |event=mouseover|. The event gets triggered the
- moment the mouse cursor moves over the object.
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse over} }
- [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/animation/events/mouse move}
- Shorthand for |event=mousemove|. The event gets triggered lots of
- times, namely each time the mouse moves while being ``over'' the
- object.
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse move} }
- [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/animation/events/mouse out}
- Shorthand for |event=mouseout|. The opposite of |mouse over|:
- triggered when the mouse leaves the object.
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \node :rotate = { 0s="0", 2s="90", begin on = {mouse out} }
- [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/animation/events/begin}
- Shorthand for |event=begin|. The ``begin'' refers to the beginning
- of another animation, namely the one referenced by |of| or
- |of whom|. This means that the current animation will begin when
- some other animation begins.
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \node [animate = {
- myself:rotate = { 0s="0", 2s="90", begin on = {begin, of next=anim}},
- myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim}
- },
- fill = blue!20, draw = blue, circle, ultra thick] {Here!};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/animation/events/end}
- Shorthand for |event=end|. Again, the ``end'' refers to the end of
- another animation, namely the one referenced by |of| or |of whom|.
- This means that the current animation will \emph{begin} when some
- other animation \emph{ends}.
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \node [animate = {
- myself:rotate = { 0s="0", 2s="90", begin on = {end, of next=anim}},
- myself:xshift = { 0s="0mm", 2s="5mm", begin on = {click}, name=anim }
- },
- fill = blue!20, draw = blue, circle, ultra thick] {Here!};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/pgf/animation/events/focus in}
- This is a shorthand for |event=focusin|. This event gets triggered
- when the graphic object gets the focus (this usually makes sense
- only for text input fields).
- \end{key}
- %
- \begin{key}{/pgf/animation/events/focus out}
- This is a shorthand for |event=focusout|.
- \end{key}
- \end{key}
-
- In addition to the events specified using the generic |event| key, there
- are two further events that take a parameter:
- %
- \begin{key}{/pgf/animation/events/repeat=\meta{number}}
- The event is triggered when a repeating animation has been repeated
- \meta{number} times.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={
- 0.333/\frac{1}{3},0.666/\frac{2}{3},1,
- 1.333/1\frac{1}{3},1.666/1\frac{2}{3},2,
- 2.333/2\frac{1}{3},2.666/2\frac{2}{3},3,
- 3.333/2\frac{1}{3},3.666/2\frac{2}{3},4%
- },
-]
-\tikz
- \node [animate = { myself: = {
- :rotate = { 0s="0", 2s="90", begin on = {repeat = 2, of next = anim },
- begin snapshot = 2 },
- :xshift = { 0s="0mm", 2s="5mm", begin on=click, name=anim, repeats=4 }}},
- fill = blue!20, draw = blue, circle, ultra thick] {Here!};
-\end{codeexample}
- \end{key}
-
- \begin{key}{/pgf/animation/events/key=\meta{key}}
- The event is triggered when the keyboard key \meta{key} has been
- pressed. For security reasons, a viewer may suppress this.
- \end{key}
-
- Having specified the event, you can also specify a delay relative to this
- event:
-
- \begin{key}{/pgf/animation/events/delay=\meta{time}}
- Specifies that the timeline should not start with the event, but,
- rather, be delayed by \meta{time}.
- \end{key}
-\end{key}
-
-When you use |begin on| to start an animation when a certain event is
-triggered, it is not clear what should happen when the event is triggered
-\emph{again}. Should this be ignored completely? Should it only be ignored
-while the animation is running? The following key allows you to specify when
-should happen:
-
-\begin{key}{/tikz/animate/options/restart=\meta{choice} (default true)}
- You can set \meta{choice} to one of the following:
- %
- \begin{itemize}
- \item |true| means that the animation will restart each time the event
- is triggered. If the animation is already running, it will be reset
- to its beginning.
- \item |false| means that once the animation has started once, it will
- never be restarted.
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \node :rotate = { 0s="0", 2s="90",
- restart = false, begin on = {click}}
- [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
-\end{codeexample}
- %
- \item |never| means the same as |false|.
- \item |when not active| means that the animation will restart when the
- event is triggered, but \emph{not} while the animation is running.
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \node :rotate = { 0s="0", 2s="90",
- restart = when not active, begin on = {click}}
- [fill = blue!20, draw = blue, circle, ultra thick] {Here!};
-\end{codeexample}
- \end{itemize}
-\end{key}
-
-Just like |begin on| specifies when a timeline begins relative to some event,
-the |end on| allows you to stop is early when some event happens:
-
-\begin{key}{/tikz/animate/options/end on=\meta{options}}
- Works exactly like |begin on|, one possible end of the timeline is
- specified using the \meta{options}.
-\end{key}
-
-
-\subsubsection{Repeating Timelines and Accumulation}
-
-\begin{key}{/tikz/animate/options/repeats=\meta{specification}}
- Use this key to specify that the timeline animation should repeat at the
- end. The \meta{specification} must consist of two parts, each of which may
- be empty. The first part is one of the following:
- %
- \begin{itemize}
- \item Empty, in which case the timeline repeats forever.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5},
-]
-\tikz \node :rotate = { 0s = "0", 2s = "90",
- repeats, begin on = click }
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
- \item A \meta{number} (like |2| or |3.25|), in which case the timeline
- repeats \meta{number} times.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5},
-]
-\tikz \node :rotate = { 0s = "0", 2s = "90",
- repeats = 1.75, begin on = click }
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
- \item The text ``|for| \meta{time}'' (like |for 2s| or |for 300ms|), in
- which case the timeline repeats however often necessary so that it
- stops exactly after \meta{time}.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5},
-]
-\tikz \node :rotate = { 0s = "0", 2s = "90",
- repeats = for 3.5s, begin on = click }
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- \end{itemize}
- %
- The second part of the specification must be one of the following:
- %
- \begin{itemize}
- \item Empty, in which case each time the timeline is restarted, the
- attribute's value undergoes the same series of values it did
- previously.
- \item The text |accumulating|. This has the effect that each time the
- timeline is restarted, the last values specified by the timeline is
- \emph{added} to the value from the previous iteration(s). A typical
- example is an animation that shifts a scope by, say, 1\,cm over a
- time of 1\,s. Now, if you repeat this five times, normally the
- scope will shift 1\,cm for 1\,s then ``jump back'', shift again,
- jump back, and so on for five times. In contrast, when the repeats
- are accumulating, the scope will move by 5\,cm over 5\,s in total.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5},
-]
-\tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click,
- repeats = accumulating }
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={1,2,3,4,5},
-]
-\tikz \node :rotate = { 0s = "0", 2s = "90", begin on = click,
- repeats = for 4s accumulating }
- [fill = blue!20, draw = blue, ultra thick, circle] {Click me!};
-\end{codeexample}
- \end{itemize}
-\end{key}
-
-\begin{key}{/tikz/animate/options/repeat=\meta{specification}}
- An alias for |repeats|.
-\end{key}
-
-
-\subsubsection{Smoothing and Jumping Timelines}
-\label{section-anim-smooth}
-
-Your specification of the timeline will consist of a sequence of times along
-with values that the attribute should have at these ``key times''. Between
-these key times, the attribute's value needs to be interpolated.
-
-Suppose that an animation is supposed to interpolate a attribute's value
-between the two values |50| and |100| over a time of 10\,s. The simplest way of
-doing so is to do a linear interpolation, where the value as, say, 1\,s is 55,
-at 2\,s it is 60, and so on. Unfortunately, the linear interpolation does not
-``look'' nice in many cases since the acceleration of a linear interpolation is
-zero during the animation, but infinite at the beginning and at the end; which
-looks ``jerky''.
-
-To avoid this, you can specify that the time--attribute curve should not be a
-straight line, but rather a curve. You specify this curve using a spline. The
-most logical ``coordinate rectangle'' used for this spline in our example would
-be |(0s,50)| and |(10s,100)| and we would like to specify something like
-%
-\begin{codeexample}[code only]
- (0s,50) .. controls (5s,50) and (9s,100) .. (10s,100)
-\end{codeexample}
-%
-This would result in a time--attribute curve where the attribute at |50|
-changes slowly at 0\,s and also arrives slowly at |100| at 10\,s, but speeds up
-between these values.
-
-We call the first control point |(5s,50)| the ``exit control'' and call
-|(9s,100)| the ``entry control'': The first control dictates how quickly or
-slowly a time point is left, the second dictates how quickly or slowly we enter
-the next one.
-
-The control points are, however, not specified in the coordinate system
-indicated above. Rather, the rectangle |(0s,50)| to |(10s, 100)| gets
-normalized to |(0,0)| to |(1,1)|. The control point |(5s,50)| would thus become
-|(0.5,0)| and |(9s,100)| becomes |(0.9,1)|.
-
-\begin{key}{/tikz/animate/options/exit control=\marg{time fraction}\marg{value fraction}}
- Specifies an exit control using two values as above. The spline from above
- would be specified as follows:
- %
-\begin{codeexample}[code only]
-exit control={0.5}{0},
-entry control={0.9}{1},
-0s = "50",
-10s = "100"
-\end{codeexample}
-
- Note that the curve specified using exit and entry controls must be
- ``well-behaved'' in the sense that exactly one value must be specified for
- each point in time in the time interval.
-
- In the next three example, we first specify a ``smooth'' exit from the
- start position, then a smooth arrival at the end position, and, finally
- both.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}},
-]
-\tikz {
- \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
- \node :yshift = { begin on = click,
- 0s = { exit control = {1}{0}, "0cm" },
- 1s = "-5mm",
- 2s = "-10mm" }
- [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
-
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}},
-]
-\tikz {
- \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
- \node :yshift = { begin on = click,
- 0s = "0cm",
- 1s = "-5mm",
- 2s = { entry control = {0}{1}, "-10mm" } }
- [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
-
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}},
-]
-\tikz {
- \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
- \node :yshift = { begin on = click,
- 0s = { exit control = {1}{0}, "0cm" },
- 1s = "-5mm",
- 2s = { entry control = {0}{1}, "-10mm" } }
- [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/animate/options/entry control=\marg{time fraction}\marg{value fraction}}
- Works like |exit control|.
-\end{key}
-
-\begin{key}{/tikz/animate/options/ease in=\marg{fraction} (default 0.5)}
- A shorthand for |entry control={1-|\meta{fraction}|}{1}|.
-\end{key}
-
-\begin{key}{/tikz/animate/options/ease out=\marg{fraction} (default 0.5)}
- A shorthand for |exit control={|\meta{fraction}|}{1}|.
-\end{key}
-
-\begin{key}{/tikz/animate/options/ease=\marg{fraction} (default 0.5)}
- A shorthand for |ease in=|\meta{fraction}|, ease out=|\meta{fraction}.
-
- Note that since for the first time the entry control is ignored and,
- similarly, for the last time the exit control is ignored, using the |ease|
- key with an animation having only two times is particularly easy, since we
- only need to set |ease| once:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.333/\frac{1}{3},0.666/\frac{2}{3},1,1.333/1\frac{1}{3},1.666/1\frac{2}{3}},
-]
-\tikz {
- \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
- \node :yshift = { begin on = click, ease, 0s = "0cm", 2s = "-10mm" }
- [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- %
-\end{key}
-
-The opposite of having a smooth curve between two values, is to have a ``jump''
-from one value to the next. There are two keys for this:
-
-\begin{key}{/tikz/animate/options/stay}
- Specifies that inside the time interval the value ``stays put'' at the
- first value till the end of the interval, where it will jump to the second
- value. This is similar to an exit control where the curve is ``infinitely
- flat''.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2,2.5},
-]
-\tikz {
- \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
- \node :yshift = { begin on = click,
- 0s = "0cm",
- 1s = {stay, "-5mm"},
- 2s = "-10mm" }
- [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/animate/options/jump}
- Works like the |stay| key, but will cause the value to ``jump to'' the new
- value right at the beginning of the time interval. It is similar to an
- entry control specifying a ``flat'' curve.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2,2.5},
-]
-\tikz {
- \foreach \i in {0,0.1,...,1} \draw (-0.9,.9-\i) -- ++(1.8,0);
- \node :yshift = { begin on = click,
- 0s = "0cm",
- 1s = {jump, "-5mm"},
- 2s = "-10mm" }
- [fill = blue!20, draw = blue, very thick, circle] {Click me!};
-}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Snapshots}
-\label{section-anim-snap}
-
-Snapshots are a way of taking a ``photographic snapshot'' of an animation at a
-certain time and then insert these into \textsc{pdf} files (or, for that
-matter, Postscript files or files in any other format, including \textsc{svg}):
-You specify a time like |2s| and then \tikzname\ will compute what the
-animation ``would look like after 2s'' and insert the necessary graphics
-command for rendering the graphic objects in the correct way. Since this
-computation is done by \tikzname\ and since only ``normal'' graphics command
-are inserted into the output, snapshots work with all output formats.
-
-Apart from providing a fallback for \textsc{pdf}, snapshots are very useful by
-themselves: They make it easy to ``show'' how an animation unfolds on paper.
-For this, you simply typeset the same picture with the same animation several
-times (using a simple |\foreach| loop), but each time you set a different
-snapshot time. This will result in a sequence of pictures that depict the
-animation at different points in time and which can then be inserted alongside
-each other into the printed document. This approach has been used with the
-examples of animations in this manual.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
-\foreach \t in {0.5, 1, 1.5, 2}
- \tikz [make snapshot of = \t]
- \fill :fill = {0s="black", 2s="red"} (0,0) circle [radius = 5mm];
-\end{codeexample}
-
-Creating snapshots is done using the following key:
-
-\begin{key}{/tikz/make snapshot of=\meta{time}}
- When this key is used in a \TeX\ scope, animation commands given in the
- scope do not add animation code to the output. Instead, \tikzname\ computes
- the values the attributes of the animation would have at the specified
- \meta{time} and inserts the necessary system layer command to set the
- attribute to the computed values (some care has been taken to make this
- computation match the computations done by viewer applications as best as
- possible).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
-\tikz [make snapshot of = 1s] {
- \fill :fill = { 0s = "black", 2s = "white" } (0,0) rectangle ++(1,1);
- \fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1);
-}
-\end{codeexample}
-
- The moment \meta{time} is best thought of as \meta{time} seconds after the
- ``moment zero'' where all timelines start by default. Now, ``real''
- animation may start at different time through user interaction, which
- clearly makes no sense for snapshots. Nevertheless, you will sometimes wish
- to have more control over when a timeline starts for the purposes of taking
- snapshots. You can use the following key for this:
-
- \begin{key}{/tikz/animate/options/begin snapshot=\meta{start time}}
- Use this key on a timeline to specify that, only for purposes of taking
- snapshots, the timeline starts at \meta{start time} rather than at
- ``moment zero''. (Think of this as saying that the animation starts
- when a virtual user clicks on the animation and this click occurs
- \meta{start time} seconds after the general ``moment zero'', causing
- the animation to ``lag behind'' by this amount of time.)
- Computationally, for the timeline the \meta{start time} is subtracted
- from the snapshot's \meta{time} when the value needs to be determined:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
-\tikz [make snapshot of = 1s] {
- \fill :fill = { 0s = "black", 2s = "white",
- begin snapshot = 1s } (0,0) rectangle ++(1,1);
- \fill :fill = { 1s = "black", 3s = "white" } (2,0) rectangle ++(1,1);
-}
-\end{codeexample}
- \end{key}
-
- The computations of the values the animation ``would have'' are done
- entirely by \tikzname, which has the big advantage is that no support from
- the viewer application or the output format is needed -- snapshots work
- with all output formats, not just with \textsc{svg}. However, computations
- done by \tikzname\ are not always very precise and can be slow because of
- \TeX's limitations. In addition, there are some further limitations when it
- comes to \tikzname's computation of snapshot values:
- %
- \begin{itemize}
- \item As mentioned above, except for |begin snapshot|, other commands
- for specifying the beginning or end of a timeline based on user
- interaction make no sense for timelines: The keys |begin|,
- |begin on|, |end|, and |end on| are silently ignored.
- \item The value |current value| for a value is forbidden since this
- value is almost impossible to compute by \tikzname.
- \item Accumulating repeats of a motion are (currently) not supported,
- but should not rely on this.
- \end{itemize}
-
- When \meta{time} is empty, ``snapshot taking'' is switched off and
- animation commands are inserted once more.
-\end{key}
-
-\begin{key}{/tikz/make snapshot after=\meta{time}}
- Works exactly like |make snapshot of|, only the \meta{time} is interpreted
- as $\meta{time} + \epsilon$. This only makes a difference at the end of a
- timeline and when there are two or more values specified for the same time:
- When there are several values specified for time~$t$, a normal snapshot for
- time~$t$ uses the first value given for the attribute. In contrast, this
- command would use the last one given. Similarly, when an animation timeline
- ends at time $t$, a normal snapshot of time $t$ would use the last value of
- the timeline, while this key would not apply the animation at all (it has
- already ended at time $t + \epsilon$).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
-\tikz [make snapshot of = 2s]
- \fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1);
-\tikz [make snapshot after = 2s]
- \fill :fill = { 0s = "green", 2s = "red" } (0,0) rectangle ++(1,1);
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/make snapshot if necessary=\meta{time} (default 0s)}
- This key makes a snapshot of \meta{time} only when the output format does
- not provide support for animations; if the output format supports
- animations (like \textsc{svg}), then the command has no effect and
- animations are created normally.
-
- This manual is typeset with the following being set once are for all in
- preamble:
- %
-\begin{codeexample}[code only]
-\tikzset{make snapshot if necessary}
-\end{codeexample}
-
- Because of this setting, in the \textsc{pdf} version of this document, all
- animations are shown at the value they would have at moment~$0s$. In
- contrast, in the \textsc{svg} version, the animations are created normally.
-
- In both versions, the smaller pictures showing how the animation proceeds
- over time are created using |make snapshot of| for the indicated times.
-\end{key}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-arrows.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-arrows.tex
deleted file mode 100644
index 91bf2477da..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-arrows.tex
+++ /dev/null
@@ -1,2559 +0,0 @@
-% 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{Arrows}
-\label{section-tikz-arrows}
-
-\subsection{Overview}
-
-\tikzname\ allows you to add (multiple) arrow tips to the end of lines as in
-\tikz [baseline] \draw [->>] (0,.5ex) -- (3ex,.5ex); or in \tikz [baseline]
-\draw [-{Latex[]}] (0,.5ex) -- (3ex,.5ex);. It is possible to change which
-arrow tips are used ``on-the-fly'', you can have several arrow tips in a row,
-and you can change the appearance of each of them individually using a special
-syntax. The following example is a perhaps slightly ``excessive'' demonstration
-of what you can do (you need to load the |arrows.meta| library for it to work):
-%
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending,positioning}}]
-\tikz {
- \node [circle,draw] (A) {A};
- \node [circle,draw] (B) [right=of A] {B};
-
- \draw [draw = blue, thick,
- arrows={
- Computer Modern Rightarrow [sep]
- - Latex[blue!50,length=8pt,bend,line width=0pt]
- Stealth[length=8pt,open,bend,sep]}]
- (A) edge [bend left=45] (B)
- (B) edge [in=-110, out=-70,looseness=8] (B);
-}
-\end{codeexample}
-
-There are a number of predefined generic arrow tip kinds whose appearance you
-can modify in many ways using various options. It is also possible to define
-completely new arrow tip kinds, see Section~\ref{section-arrows}, but doing
-this is somewhat harder than configuring an existing kind (it is like the
-difference between using a font at different sizes or faces like italics,
-compared to designing a new font yourself).
-
-In the present section, we go over the various ways in which you can configure
-which particular arrow tips are \emph{used}. The glorious details of how new
-arrow tips can be defined are explained in Section~\ref{section-arrows}.
-
-At the end of the present section, Section~\ref{section-arrows-meta}, you will
-find a description of the different predefined arrow tips from the
-|arrows.meta| library.
-
-\emph{Remark:} Almost all of the features described in the following were
-introduced in version 3.0 of \tikzname. For compatibility reasons, the old
-arrow tips are still available. To differentiate between the old and new arrow
-tips, the following rule is used: The new, more powerful arrow tips start with
-an uppercase letter as in |Latex|, compared to the old arrow tip |latex|.
-
-\emph{Remark:} The libraries |arrows| and |arrows.spaced| are deprecated. Use
-|arrows.meta| instead/additionally, which allows you to do all that the old
-libraries offered, plus much more. However, the old libraries still work and
-you can even mix old and new arrow tips (only, the old arrow tips cannot be
-configured in the ways described in the rest of this section; saying |scale=2|
-for a |latex| arrow has no effect for instance, while for |Latex| arrows it
-doubles their size as one would expect.)
-
-
-\subsection{Where and When Arrow Tips Are Placed}
-\label{section-arrow-tips-where}
-
-In order to add arrow tips to the lines you draw, the following conditions must
-be met:
-%
-\begin{enumerate}
- \item You have specified that arrow tips should be added to lines, using
- the |arrows| key or its short form.
- \item You set the |tips| key to some value that causes tips to be drawn
- (to be explained later).
- \item You do not use the |clip| key (directly or indirectly) with the
- current path.
- \item The path actually has two ``end points'' (it is not ``closed'').
-\end{enumerate}
-
-Let us start with an introduction to the basics of the |arrows| key:
-
-\begin{key}{/tikz/arrows=\meta{start arrow specification}|-|\meta{end arrow specification}}
- This option sets the arrow tip(s) to be used at the start and end of lines.
- An empty value as in |->| for the start indicates that no arrow tip should
- be drawn at the start.%
- \indexoption{arrows}
-
- \emph{Note: Since the arrow option is so often used, you can leave out the
- text |arrows=|.} What happens is that every (otherwise unknown) option that
- contains a |-| is interpreted as an arrow specification.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\begin{tikzpicture}
- \draw[->] (0,0) -- (1,0);
- \draw[>-Stealth] (0,0.3) -- (1,0.3);
-\end{tikzpicture}
-\end{codeexample}
-
- In the above example, the first start specification is empty and the second
- is |>|. The end specifications are |>| for the first line and |Stealth| for
- the second line. Note that it makes a difference whether |>| is used in a
- start specification or in an end specification: In an end specification it
- creates, as one would expect, a pointed tip at the end of the line. In the
- start specification, however, it creates a ``reversed'' version if this
- arrow -- which happens to be what one would expect here.
-
- The above specifications are very simple and only select a single arrow tip
- without any special configuration options, resulting in the ``natural''
- versions of these arrow tips. It is also possible to ``configure'' arrow
- tips in many different ways, as explained in detail in
- Section~\ref{section-arrow-config} below by adding options in square
- brackets following the arrow tip kind:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\begin{tikzpicture}
- \draw[-{Stealth[red]}] (0,0) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
-
- Note that in the example I had to surround the end specification by braces.
- This is necessary so that \tikzname\ does not mistake the closing square
- bracket of the |Stealth| arrow tip's options for the end of the options of
- the |\draw| command. In general, you often need to add braces when
- specifying arrow tips except for simple case like |->| or |<<->|, which are
- pretty frequent, though. When in doubt, say
- |arrows={|\meta{start spec}|-|\meta{end spec}|}|, that will always work.
-
- It is also possible to specify multiple (different) arrow tips in a row
- inside a specification, see Section~\ref{section-arrow-spec} below for
- details.
-\end{key}
-
-As was pointed out earlier, to add arrow tips to a path, the path must have
-``end points'' and not be ``closed'' -- otherwise adding arrow tips makes
-little sense, after all. However, a path can actually consist of several
-subpath, which may be open or not and may even consist of only a single point
-(a single move-to). In this case, it is not immediately obvious, where arrow
-heads should be placed. The actual rules that \tikzname\ uses are governed by
-the setting of the key |tips|:
-
-\begin{key}{/pgf/tips=\meta{value} (default true, initially on draw)}
- \keyalias{tikz}
- This key governs in what situations arrow tips are added to a path. The
- following \meta{values} are permissible:
- %
- \begin{itemize}
- \item |true| (the value used when no \meta{value} is specified)
- \item |proper|
- \item |on draw| (the initial value, if the key has not yet been used
- at all)
- \item |on proper draw|
- \item |never| or |false| (same effect)
- \end{itemize}
-
- Firstly, there are a whole bunch of situations where the setting of
- these (or other) options causes no arrow tips to be shown:
- %
- \begin{itemize}
- \item If no arrow tips have been specified (for instance, by having
- said |arrows=-|), no arrow tips are drawn.
- \item If the |clip| option is set, no arrow tips are drawn.
- \item If |tips| has been set to |never| or |false|, no arrow tips are
- drawn.
- \item If |tips| has been set to |on draw| or |on proper draw|, but
- the |draw| option is not set, no arrow tips are drawn.
- \item If the path is empty (as in |\path ;|), no arrow tips are
- drawn.
- \item If at least one of the subpaths of a path is closed (|cycle| is
- used somewhere or something like |circle| or |rectangle|), arrow
- tips are never drawn anywhere -- even if there are open subpaths.
- \end{itemize}
-
- Now, if we pass all of the above tests, we must have a closer look at the
- path. All its subpaths must now be open and there must be at least one
- subpath. We consider the last one. Arrow tips will only be added to this
- last subpath.
-
- \begin{enumerate}
- \item If this last subpath not degenerate (all coordinates on the
- subpath are the same as in a single ``move-to'' |\path (0,0);| or
- in a ``move-to'' followed by a ``line-to'' to the same position
- as in |\path (1,2) -- (1,2)|), arrow tips are added to this last
- subpath now.
- \item If the last subpath is degenerate, we add arrow tips pointing
- upward at the single coordinate mentioned in the path, but only
- for |tips| begin set to |true| or to |on draw| -- and not for
- |proper| nor for |on proper draw|. In other words, ``proper''
- suppresses arrow tips on degenerate paths.
- \end{enumerate}
-
-\begin{codeexample}[]
-% No path, no arrow tips:
-\tikz [<->] \draw;
-\end{codeexample}
-\begin{codeexample}[]
-% Degenerate path, draw arrow tips (but no path, it is degenerate...)
-\tikz [<->] \draw (0,0);
-\end{codeexample}
-\begin{codeexample}[]
-% Degenerate path, tips=proper suppresses arrows
-\tikz [<->] \draw [tips=proper] (0,0);
-\end{codeexample}
-\begin{codeexample}[]
-% Normal case:
-\tikz [<->] \draw (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[]
-% Two subpaths, only second gets tips
-\tikz [<->] \draw (0,0) -- (1,0) (2,0) -- (3,0);
-\end{codeexample}
-\begin{codeexample}[]
-% Two subpaths, second degenerate, but still gets tips
-\tikz [<->] \draw (0,0) -- (1,0) (2,0);
-\end{codeexample}
-\begin{codeexample}[]
-% Two subpaths, second degenerate, proper suppresses them
-\tikz [<->] \draw [tips=on proper draw] (0,0) -- (1,0) (2,0);
-\end{codeexample}
-\begin{codeexample}[]
-% Two subpaths, but one is closed: No tips, even though last subpath is open
-\tikz [<->] \draw (0,0) circle[radius=2pt] (2,0) -- (3,0);
-\end{codeexample}
- %
-\end{key}
-
-One common pitfall when arrow tips are added to a path should be addressed
-right here at the beginning: When \tikzname\ positions an arrow tip at the
-start, for all its computations it only takes into account the first segment of
-the subpath to which the arrow tip is added. This ``first segment'' is the
-first line-to or curve-to operation (or arc or parabola or a similar operation)
-of the path; but note that decorations like |snake| will add many small line
-segments to paths. The important point is that if this first segment is very
-small, namely smaller that the arrow tip itself, strange things may result. As
-will be explained in Section~\ref{section-arrow-flex}, \tikzname\ will modify
-the path by shortening the first segment and shortening a segment below its
-length may result in strange effects. Similarly, for tips at the end of a
-subpath, only the last segment is considered.
-
-The bottom line is that wherever an arrow tip is added to a path, the line
-segment where it is added should be ``long enough''.
-
-
-\subsection{Arrow Keys: Configuring the Appearance of a Single Arrow Tip}
-\label{section-arrow-config}
-
-For standard arrow tip kinds, like |Stealth| or |Latex| or |Bar|, you can
-easily change their size, aspect ratio, color, and other parameters. This is
-similar to selecting a font face from a font family: \emph{``This text''} is
-not just typeset in the font ``Computer Modern'', but rather in ``Computer
-Modern, italic face, 11pt size, medium weight, black color, no underline,
-\dots'' Similarly, an arrow tip is not just a ``Stealth'' arrow tip, but rather
-a ``Stealth arrow tip at its natural size, flexing, but not bending along the
-path, miter line caps, draw and fill colors identical to the path draw color,
-\dots''
-
-Just as most programs make it easy to ``configure'' which font should be used
-at a certain point in a text, \tikzname\ tries to make it easy to specify which
-configuration of an arrow tip should be used. You use \emph{arrow keys}, where
-a certain parameter like the |length| of an arrow is set to a given value using
-the standard key--value syntax. You can provide several arrow keys following an
-arrow tip kind in an arrow tip specification as in
-|Stealth[length=4pt,width=2pt]|.
-
-While selecting a font may be easy, \emph{designing} a new font is a highly
-creative and difficult process and more often than not, not all faces of a font
-are available on any given system. The difficulties involved in designing a new
-arrow tip are somewhat similar to designing a new letter for a font and, thus,
-it may also happen that not all configuration options are actually implemented
-for a given arrow tip. Naturally, for the standard arrow tips, all
-configuration options are available -- but for special-purpose arrow tips it
-may well happen that an arrow tip kind simply ``ignores'' some of the
-configurations given by you.
-
-Some of the keys explained in the following are defined in the library
-|arrows.meta|, others are always available. This has to do with the question of
-whether the arrow key needs to be supported directly in the \pgfname\ core or
-not. In general, the following explanations assume that |arrows.meta| has been
-loaded.
-
-
-\subsubsection{Size}
-
-The most important configuration parameter of an arrow tip is undoubtedly its
-size. The following two keys are the main keys that are important in this
-context:
-
-\begin{key}{/pgf/arrow keys/length=\meta{dimension}| |\opt{\meta{line width factor}}%
- | |\opt{\meta{outer factor}}}
- \label{length-arrow-key}%
- This parameter is usually the most important parameter that governs the
- size of an arrow tip: The \meta{dimension} that you provide dictates the
- distance from the ``very tip'' of the arrow to its ``back end'' along the
- line:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz{
- \draw [-{Stealth[length=5mm]}] (0,0) -- (2,0);
- \draw [|<->|] (1.5,.4) -- node[above=1mm] {5mm} (2,.4);
-}
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz{
- \draw [-{Latex[length=5mm]}] (0,0) -- (2,0);
- \draw [|<->|] (1.5,.4) -- node[above=1mm] {5mm} (2,.4);
-}
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz{
- \draw [-{Classical TikZ Rightarrow[length=5mm]}] (0,0) -- (2,0);
- \draw [|<->|] (1.5,.6) -- node[above=1mm] {5mm} (2,.6);
-}
-\end{codeexample}
-
- \medskip
- \noindent \textbf{The Line Width Factors.}
- Following the \meta{dimension}, you may put a space followed by a
- \meta{line width factor}, which must be a plain number (no |pt| or |cm|
- following). When you provide such a number, the size of the arrow tip is
- not just \meta{dimension}, but rather $\meta{dimension} + \meta{line width
- factor}\cdot w$ where $w$ is the width of the to-be-drawn path. This makes
- it easy to vary the size of an arrow tip in accordance with the line width
- -- usually a very good idea since thicker lines will need thicker arrow
- tips.
-
- As an example, when you write |length=0pt 5|, the length of the arrow will
- be exactly five times the current line width. As another example, the
- default length of a |Latex| arrow is |length=3pt 4.5 0.8|. Let us ignore
- the 0.8 for a moment; the |3pt 4.5| then means that for the standard line
- width of |0.4pt|, the length of a |Latex| arrow will be exactly 4.8pt (3pt
- plus 4.5 times |0.4pt|).
-
- Following the line width factor, you can additionally provide an
- \meta{outer factor}, again preceded by a space (the |0.8| in the above
- example). This factor is taken into consideration only when the |double|
- option is used, that is, when a so-called ``inner line width''. For a
- double line, we can identify three different ``line widths'', namely the
- inner line width $w_i$, the line width $w_o$ of the two outer lines, and
- the ``total line width'' $w_t = w_i + 2w_o$. In the below examples, we have
- $w_i = 3\mathrm{pt}$, $w_o=1\mathrm{pt}$, and $w_t = 5\mathrm{pt}$. It is
- not immediately clear which of these line widths should be considered as
- $w$ in the above formula $\meta{dimension} + \meta{line width factor}\cdot
- w$ for the computation of the length. One can argue both for $w_t$ and also
- for $w_o$. Because of this, you use the \meta{outer factor} to decide on
- one of them or even mix them: \tikzname\ sets $w = \meta{outer factor} w_o
- + (1-\meta{outer factor})w_t$. Thus, when the outer factor is $0$, as in
- the first of the following examples and as is the default when it is not
- specified, the computed $w$ will be the total line width $w_t =
- 5\mathrm{pt}$. Since $w=5\mathrm{pt}$, we get a total length of $15pt$ in
- the first example (because of the factor |3|). In contrast, in the last
- example, the outer factor is 1 and, thus, $w = w_o = \mathrm{1pt}$ and the
- resulting length is 3pt. Finally, for the middle case, the ``middle''
- between 5pt and 1pt is 3pt, so the length is 9pt.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [line width=1pt, double distance=3pt,
- arrows = {-Latex[length=0pt 3 0]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [line width=1pt, double distance=3pt,
- arrows = {-Latex[length=0pt 3 .5]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [line width=1pt, double distance=3pt,
- arrows = {-Latex[length=0pt 3 1]} ] (0,0) -- (1,0);
-\end{codeexample}
-
- \medskip
- \noindent \textbf{The Exact Length.}
- For an arrow tip kind that is just an outline that is filled with a color,
- the specified length should \emph{exactly} equal the distance from the tip
- to the back end. However, when the arrow tip is drawn by stroking a line,
- it is no longer obvious whether the |length| should refer to the extend of
- the stroked lines' path or of the resulting pixels (which will be wider
- because of the thickness of the stroking pen). The rules are as follows:
- %
- \begin{enumerate}
- \item If the arrow tip consists of a closed path (like |Stealth| or
- |Latex|), imagine the arrow tip drawn from left to right using a
- miter line cap. Then the |length| should be the horizontal
- distance from the first drawn ``pixel'' to the last drawn
- ``pixel''. Thus, the thickness of the stroked line and also the
- miter ends should be taken into account:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz{
- \draw [line width=1mm, -{Stealth[length=10mm, open]}]
- (0,0) -- (2,0);
- \draw [|<->|] (2,.6) -- node[above=1mm] {10mm} ++(-10mm,0);
-}
-\end{codeexample}
- %
- \item If, in the above case, the arrow is drawn using a round line
- join (see Section~\ref{section-arrow-key-caps} for details on how
- to select this), the size of the arrow should still be the same
- as in the first case (that is, as if a miter join were used).
- This creates some ``visual consistency'' if the two modes are
- mixed or if you later want to change the mode.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz{
- \draw [line width=1mm, -{Stealth[length=10mm, open, round]}]
- (0,0) -- (2,0);
- \draw [|<->|] (2,.6) -- node[above=1mm] {10mm} ++(-10mm,0);
-}
-\end{codeexample}
- %
- As the above example shows, however, a rounded arrow will still
- exactly ``tip'' the point where the line should end (the point
- |(2,0)| in the above case). It is only the scaling of the arrow
- that is not affected.
- \end{enumerate}
-\end{key}
-
-\begin{key}{/pgf/arrow keys/width=\meta{dimension}| |\opt{\meta{line width factor}}%
- | |\opt{\meta{outer factor}}}
- This key works like the |length| key, only it specifies the ``width'' of
- the arrow tip; so if width and length are identical, the arrow will just
- touch the borders of a square. (An exception to this rule are ``halved''
- arrow tips, see Section~\ref{section-arrow-key-harpoon}.) The meaning of
- the two optional factor numbers following the \meta{dimension} is the same
- as for the |length| key.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Latex[width=10pt, length=10pt]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Latex[width=0pt 10, length=10pt]}] (0,0) -- (1,0);
-\end{codeexample}
-\end{key}
-
-\begin{key}{/pgf/arrow keys/width'=\meta{dimension}| |\opt{\meta{length
- factor}| |\opt{\meta{line width factor}}}}
- The key (note the prime) has a similar effect as the |width| key. The
- difference is that the second, still optional parameter \meta{length
- factor} specifies the width of the key not as a multiple of the line width,
- but as a multiple of the arrow length.
-
- The idea is that if you write, say, |width'=0pt 0.5|, the width of the
- arrow will be half its length. Indeed, for standard arrow tips like
- |Stealth| the default width is specified in this way so that if you change
- the length of an arrow tip, you also change the width in such a way that
- the aspect ratio of the arrow tip is kept. The other way round, if you
- modify the factor in |width'| without changing the length, you change the
- aspect ratio of the arrow tip.
-
- Note that later changes of the length are taken into account for the
- computation. For instance, if you write
- %
-\begin{codeexample}[code only]
-length = 10pt, width'=5pt 2, length=7pt
-\end{codeexample}
- %
- the resulting width will be $19\mathrm{pt} = 5\mathrm{pt} + 2\cdot
- 7\mathrm{pt}$.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Latex[width'=0pt .5, length=10pt]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Latex[width'=0pt .5, length=15pt]}] (0,0) -- (1,0);
-\end{codeexample}
- %
- The third, also optional, parameter allows you to add a multiple of the
- line width to the value computed in terms of the length.
-\end{key}
-
-
-\begin{key}{/pgf/arrow keys/inset=\meta{dimension}| |\opt{\meta{line width factor}}%
- | |\opt{\meta{outer factor}}}
- The key is relevant only for some arrow tips such as the |Stealth| arrow
- tip. It specifies a distance by which something inside the arrow tip is set
- inwards; for the |Stealth| arrow tip it is the distance by which the back
- angle is moved inwards.
-
- The computation of the distance works in the same way as for |length| and
- |width|: To the \meta{dimension} we add \meta{line width factor} times that
- line width, where the line width is computed based on the \meta{outer
- factor} as described for the |length| key.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Stealth[length=10pt, inset=5pt]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Stealth[length=10pt, inset=2pt]}] (0,0) -- (1,0);
-\end{codeexample}
-
- For most arrows for which there is no ``natural inset'' like, say, |Latex|,
- this key has no effect.
-\end{key}
-
-\begin{key}{/pgf/arrow keys/inset'=\meta{dimension}| |\opt{\meta{length factor}}| |\opt{\meta{line width factor}}}
- This key works like |inset|, only like |width'| the second parameter is a
- factor of the arrow length rather than of the line width. For instance, the
- |Stealth| arrow sets |inset'| to |0pt 0.325| to ensure that the inset is
- always at $13/40$th of the arrow length if nothing else is specified.
-\end{key}
-
-\begin{key}{/pgf/arrow keys/angle=\meta{angle}|:|\meta{dimension}%
- | |\opt{\meta{line width factor}}%
- | |\opt{\meta{outer factor}}}
- This key sets the |length| and the |width| of an arrow tip at the same
- time. The length will be the cosine of \meta{angle}, while the width will
- be twice the sine of half the \meta{angle} (this slightly awkward rule
- ensures that a |Stealth| arrow will have an opening angle of \meta{angle}
- at its tip if this option is used). As for the |length| key, if the
- optional factors are given, they add a certain multiple of the line width
- to the \meta{dimension} before the sine and cosines are computed.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Stealth[inset=0pt, angle=90:10pt]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Stealth[inset=0pt, angle=30:10pt]}] (0,0) -- (1,0);
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/arrow keys/angle'=\meta{angle}}
- Sets the width of the arrow to twice the tangent of $\meta{angle}/2$ times
- the arrow length. This results in an arrow tip with an opening angle of
- \meta{angle} at its tip and with the specified |length| unchanged.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Stealth[inset=0pt, length=10pt, angle'=90]}]
- (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Stealth[inset=0pt, length=10pt, angle'=30]}]
- (0,0) -- (1,0);
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Scaling}
-
-In the previous section we saw that there are many options for getting ``fine
-control'' overt the length and width of arrow tips. However, in some cases, you
-do not really care whether the arrow tip is 4pt long or 4.2pt long, you ``just
-want it to be a little bit larger than usual''. In such cases, the following
-keys are useful:
-
-\begin{key}{/pgf/arrows keys/scale=\meta{factor} (initially 1)}
- After all the other options listed in the previous (and also the following
- sections) have been processed, \tikzname\ applies a \emph{scaling} to the
- computed length, inset, and width of the arrow tip (and, possibly, to other
- size parameters defined by special-purpose arrow tip kinds). Everything is
- simply scaled by the given \meta{factor}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz {
- \draw [arrows = {-Stealth[]}] (0,1) -- (1,1);
- \draw [arrows = {-Stealth[scale=1.5]}] (0,0.5) -- (1,0.5);
- \draw [arrows = {-Stealth[scale=2]}] (0,0) -- (1,0);
-}
-\end{codeexample}
- %
- Note that scaling has \emph{no} effect on the line width (as usual) and
- also not on the arrow padding (the |sep|).
-\end{key}
-
-You can get even more fine-grained control over scaling using the following
-keys (the |scale| key is just a shorthand for setting both of the following
-keys simultaneously):
-
-\begin{key}{/pgf/arrows keys/scale length=\meta{factor} (initially 1)}
- This factor works like |scale|, only it is applied only to dimensions
- ``along the axis of the arrow'', that is, to the length and to the inset,
- but not to the width.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz {
- \draw [arrows = {-Stealth[]}] (0,1) -- (1,1);
- \draw [arrows = {-Stealth[scale length=1.5]}] (0,0.5) -- (1,0.5);
- \draw [arrows = {-Stealth[scale length=2]}] (0,0) -- (1,0);
-}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/arrows keys/scale width=\meta{factor} (initially 1)}
- Like |scale length|, but for dimensions related to the width.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz {
- \draw [arrows = {-Stealth[]}] (0,1) -- (1,1);
- \draw [arrows = {-Stealth[scale width=1.5]}] (0,0.5) -- (1,0.5);
- \draw [arrows = {-Stealth[scale width=2]}] (0,0) -- (1,0);
-}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Arc Angles}
-
-A few arrow tips consist mainly of arcs, whose length can be specified. For
-these arrow tips, you use the following key:
-
-\begin{key}{/pgf/arrow keys/arc=\meta{degrees} (initially 180)}
- Sets the angle of arcs in arrows to \meta{degrees}. Note that this key is
- quite different from the |angle| key, which is ``just a fancy way of
- setting the length and width''. In contrast, the |arc| key is used to set
- the degrees of arcs that are part of an arrow tip:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] {
- \draw [arrows = {-Hooks[]}] (0,1) -- (1,1);
- \draw [arrows = {-Hooks[arc=90]}] (0,0.5) -- (1,0.5);
- \draw [arrows = {-Hooks[arc=270]}] (0,0) -- (1,0);
-}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Slanting}
-
-You can ``slant'' arrow tips using the following key:
-
-\begin{key}{/pgf/arrow keys/slant=\meta{factor} (initially 0)}
- Slanting is used to create an ``italics'' effect for arrow tips: All arrow
- tips get ``slanted'' a little bit relative to the axis of the arrow:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz {
- \draw [arrows = {->[]}] (0,1) -- (1,1);
- \draw [arrows = {->[slant=.5]}] (0,0.5) -- (1,0.5);
- \draw [arrows = {->[slant=1]}] (0,0) -- (1,0);
-}
-\end{codeexample}
- %
- There is one thing to note about slanting: Slanting is done using a
- so-called ``canvas transformation'' and has no effect on positioning of
- the arrow tip. In particular, if an arrow tip gets slanted so strongly that
- it starts to protrude over the arrow tip end, this does not change the
- positioning of the arrow tip.
-
- Here is another example where slanting is used to match italic text:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,graphs}}]
-\tikz [>={[slant=.3] To[] To[]}]
- \graph [math nodes] { A -> B <-> C };
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Reversing, Halving, Swapping}
-\label{section-arrow-key-harpoon}
-
-\begin{key}{/pgf/arrow keys/reversed}
- Adding this key to an arrow tip will ``reverse its direction'' so that is
- points in the opposite direction (but is still at that end of the line
- where the non-reversed arrow tip would have been drawn; so only the tip is
- reversed). For most arrow tips, this just results in an internal flip of a
- coordinate system, but some arrow tips actually use a slightly different
- version of the tip for reversed arrow tips (namely when the joining of the
- tip with the line would look strange). All of this happens automatically,
- so you do not need to worry about this.
-
- If you apply this key twice, the effect cancels, which is useful for the
- definition of shorthands (which will be discussed later).
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [arrows = {-Stealth[reversed]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [arrows = {-Stealth[reversed, reversed]}] (0,0) -- (1,0);
-\end{codeexample}
-\end{key}
-
-\begin{key}{/pgf/arrow keys/harpoon}
- The key requests that only the ``left half'' of the arrow tip should drawn:
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [arrows = {-Stealth[harpoon]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [arrows = {->[harpoon]}] (0,0) -- (1,0);
-\end{codeexample}
- %
- Unlike the |reversed| key, which all arrows tip kinds support at least in a
- basic way, designers of arrow tips really need to take this key into
- account in their arrow tip code and often a lot of special attention needs
- to do be paid to this key in the implementation. For this reason, only some
- arrow tips will support it.
-\end{key}
-
-\begin{key}{/pgf/arrow keys/swap}
- This key flips that arrow tip along the axis of the line. It makes sense
- only for asymmetric arrow tips like the harpoons created using the
- |harpoon| option.
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [arrows = {-Stealth[harpoon]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [arrows = {-Stealth[harpoon,swap]}] (0,0) -- (1,0);
-\end{codeexample}
- %
- Swapping is always possible, no special code is needed on behalf of an
- arrow tip implementer.
-\end{key}
-
-\begin{key}{/pgf/arrow keys/left}
- A shorthand for |harpoon|.
-\end{key}
-
-\begin{key}{/pgf/arrow keys/right}
- A shorthand for |harpoon, swap|.
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [arrows = {-Stealth[left]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [arrows = {-Stealth[right]}] (0,0) -- (1,0);
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Coloring}
-
-Arrow tips are drawn using the same basic mechanisms as normal paths, so arrow
-tips can be stroked (drawn) and/or filled. However, we usually want the color
-of arrow tips to be identical to the color used to draw the path, even if a
-different color is used for filling the path. On the other hand, we may also
-sometimes wish to use a special color for the arrow tips that is different from
-both the line and fill colors of the main path.
-
-The following options allow you to configure how arrow tips are colored:
-
-\begin{key}{/pgf/arrow keys/color=\meta{color or empty} (initially \normalfont empty)}
- Normally, an arrow tip gets the same color as the path to which it is
- attached. More precisely, it will get the current ``draw color'', also
- known as ``stroke color'', which you can set using |draw=|\meta{some
- color}. By adding the option |color=| to an arrow tip (note that an
- ``empty'' color is specified in this way), you ask that the arrow tip gets
- this default draw color of the path. Since this is the default behavior,
- you usually do not need to specify anything:
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [red, arrows = {-Stealth}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [blue, arrows = {-Stealth}] (0,0) -- (1,0);
-\end{codeexample}
-
- Now, when you provide a \meta{color} with this option, you request that the
- arrow tip should get this color \emph{instead} of the color of the main
- path:
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [red, arrows = {-Stealth[color=blue]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [red, arrows = {-Stealth[color=black]}] (0,0) -- (1,0);
-\end{codeexample}
-
- Similar to the |color| option used in normal \tikzname\ options, you may
- omit the |color=| part of the option. Whenever an \meta{arrow key} is
- encountered that \tikzname\ does not recognize, it will test whether the
- key is the name of a color and, if so, execute |color=|\meta{arrow key}.
- So, the first of the above examples can be rewritten as follows:
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [red, arrows = {-Stealth[blue]}] (0,0) -- (1,0);
-\end{codeexample}
-
- The \meta{color} will apply both to any drawing and filling operations used
- to construct the path. For instance, even though the |Stealth| arrow tips
- looks like a filled quadrilateral, it is actually constructed by drawing a
- quadrilateral and then filling it in the same color as the drawing (see the
- |fill| option below to see the difference).
-
- When |color| is set to an empty text, the drawing color is always used to
- fill the arrow tips, even if a different color is specified for filling the
- path:
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [draw=red, fill=red!50, arrows = {-Stealth[length=10pt]}]
- (0,0) -- (1,1) -- (2,0);
-\end{codeexample}
- %
- As you can see in the above example, the filled area is not quite what you
- might have expected. The reason is that the path was actually internally
- shortened a bit so that the end of the ``fat line'' as inside the arrow tip
- and we get a ``clear'' arrow tip.
-
- In general, it is a good idea not to add arrow tips to paths that are
- filled.
-\end{key}
-
-\begin{key}{/pgf/arrow keys/fill=\meta{color or |none|}}
- Use this key to explicitly set the color used for filling the arrow tips.
- This color can be different from the color used to draw (stroke) the arrow
- tip:
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz {
- \draw [help lines] (0,-.5) grid [step=1mm] (1,.5);
- \draw [thick, red, arrows = {-Stealth[fill=white,length=15pt]}] (0,0) -- (1,0);
-}
-\end{codeexample}
- %
- You can also specify the special ``color'' |none|. In this case, the arrow
- tip is not filled at all (not even with white):
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz {
- \draw [help lines] (0,-.5) grid [step=1mm] (1,.5);
- \draw [thick, red, arrows = {-Stealth[fill=none,length=15pt]}] (0,0) -- (1,0);
-}
-\end{codeexample}
- %
- Note that such ``open'' arrow tips are a bit difficult to draw in some
- case: The problem is that the line must be shortened by just the right
- amount so that it ends exactly on the back end of the arrow tip. In some
- cases, especially when double lines are used, this will not be possible.
-
- \begin{key}{/pgf/arrow keys/open}
- A shorthand for |fill=none|.
- \end{key}
-
- When you use both the |color| and |fill| option, the |color| option must
- come first since it will reset the filling to the color specified for
- drawing.
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz {
- \draw [help lines] (0,-.5) grid [step=1mm] (1,.5);
- \draw [thick, red, arrows = {-Stealth[color=blue, fill=white, length=15pt]}]
- (0,0) -- (1,0);
-}
-\end{codeexample}
-
- Note that by setting |fill| to the special color |pgffillcolor|, you can
- cause the arrow tips to be filled using the color used to fill the main
- path. (This special color is always available and always set to the current
- filling color of the graphic state.):
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [ultra thick] \draw [draw=red, fill=red!50,
- arrows = {-Stealth[length=15pt, fill=pgffillcolor]}]
- (0,0) -- (1,1) -- (2,0);
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Line Styling}
-\label{section-arrow-key-caps}
-
-Arrow tips are created by drawing and possibly filling a path that makes up the
-arrow tip. When \tikzname\ draws a path, there are different ways in which such
-a path can be drawn (such as dashing). Three particularly important parameters
-are the line join, the line cap, see Section~\ref{section-line-cap} for an
-introduction, and the line width (thickness).
-
-\tikzname\ resets the line cap and line join each time it draws an arrow tip
-since you usually do not want their settings to ``spill over'' to the way the
-arrow tips are drawn. You can, however, change there values explicitly for an
-arrow tip:
-
-\begin{key}{/pgf/arrow keys/line cap=\meta{|round| or |butt|}}
- Sets the line cap of all lines that are drawn in the arrow to a round cap
- or a butt cap. (Unlike for normal lines, the |rect| cap is not allowed.)
- Naturally, this key has no effect for arrows whose paths are closed.
-
- Each arrow tip has a default value for the line cap, which can be overruled
- using this option.
-
- Changing the cap should have no effect on the size of the arrow. However,
- it will have an effect on where the exact ``tip'' of the arrow is since
- this will always be exactly at the end of the arrow:
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Computer Modern Rightarrow[line cap=butt]}]
- (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Computer Modern Rightarrow[line cap=round]}]
- (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Bracket[reversed,line cap=butt]}]
- (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Bracket[reversed,line cap=round]}]
- (0,0) -- (1,0);
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/arrow keys/line join=\meta{|round| or |miter|}}
- Sets the line join to round or miter (|bevel| is not allowed). This time,
- the key only has an effect on paths that have ``corners'' in them. The same
- rules as for |line cap| apply: the size is not affects, but the tip end is:
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Computer Modern Rightarrow[line join=miter]}]
- (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Computer Modern Rightarrow[line join=round]}]
- (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Bracket[reversed,line join=miter]}]
- (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Bracket[reversed,line join=round]}]
- (0,0) -- (1,0);
-\end{codeexample}
- %
-\end{key}
-
-The following keys set both of the above:
-
-\begin{key}{/pgf/arrow keys/round}
- A shorthand for |line cap=round, line join=round|, resulting in ``rounded''
- arrow heads.
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Computer Modern Rightarrow[round]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Bracket[reversed,round]}] (0,0) -- (1,0);
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/arrow keys/sharp}
- A shorthand for |line cap=butt, line join=miter|, resulting in ``sharp'' or
- ``pointed'' arrow heads.
- %
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Computer Modern Rightarrow[sharp]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=3cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [line width=2mm]
- \draw [arrows = {-Bracket[reversed,sharp]}] (0,0) -- (1,0);
-\end{codeexample}
- %
-\end{key}
-
-You can also set the width of lines used inside arrow tips:
-
-\begin{key}{/pgf/arrow keys/line width=\meta{dimension}| |\opt{\meta{line width factor}}%
- | |\opt{\meta{outer factor}}}
- This key sets the line width inside an arrow tip for drawing (out)lines of
- the arrow tip. When you set this width to |0pt|, which makes sense only for
- closed tips, the arrow tip is only filled. This can result in better
- rendering of some small arrow tips and in case of bend arrow tips (because
- the line joins will also be bend and not ``mitered''.)
-
- The meaning of the factors is as usual the same as for |length| or |width|.
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Latex[line width=0.1pt, fill=white, length=10pt]}] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [arrows = {-Latex[line width=1pt, fill=white, length=10pt]}] (0,0) -- (1,0);
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/arrow keys/line width'=\meta{dimension}| |\opt{\meta{length factor}}}
- Works like |line width| only the factor is with respect to the |length|.
-\end{key}
-
-
-\subsubsection{Bending and Flexing}
-\label{section-arrow-flex}
-
-Up to now, we have only added arrow tip to the end of straight lines, which is
-in some sense ``easy''. Things get far more difficult, if the line to which we
-wish to end an arrow tip is curved. In the following, we have a look at the
-different actions that can be taken and how they can be configured.
-
-To get a feeling for the difficulties involved, consider the following
-situation: We have a ``gray wall'' at the $x$-coordinate of and a red line that
-ends in its middle.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
-\def\wall{ \fill [fill=black!50] (1,-.5) rectangle (2,.5);
- \pattern [pattern=bricks] (1,-.5) rectangle (2,.5);
- \draw [line width=1pt] (1cm+.5pt,-.5) -- ++(0,1); }
-\begin{tikzpicture}
- \wall
- % The "line"
- \draw [red,line width=1mm] (-1,0) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
-
-Now we wish to add a blue open arrow tip the red line like, say,
-|Stealth[length=1cm,open,blue]|:
-%
-\begin{codeexample}[setup code,hidden]
-\usetikzlibrary{patterns}
-\def\wall{ \fill [fill=black!50] (1,-.5) rectangle (2,.5);
- \pattern [pattern=bricks] (1,-.5) rectangle (2,.5);
- \draw [line width=1pt] (1cm+.5pt,-.5) -- ++(0,1); }
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\begin{tikzpicture}
- \wall
- \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue]}]
- (-1,0) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
-
-There are several noteworthy things about the blue arrow tip:
-%
-\begin{enumerate}
- \item Notice that the red line no longer goes all the way to the wall.
- Indeed, the red line ends more or less exactly where it meets the
- blue line, leaving the arrow tip empty. Now, recall that the red line
- was supposed to be the path |(-2,0)--(1,0)|; however, this path has
- obviously become much shorter (by 6.25mm to be precise). This effect
- is called \emph{path shortening} in \tikzname.
- \item The very tip of the arrow just ``touches'' the wall, even we zoom
- out a lot. This point, where the original path ended and where the
- arrow tip should now lie, is called the \emph{tip end} in \tikzname.
- \item Finally, the point where the red line touches the blue line is the
- point where the original path ``visually ends''. Notice that this is
- not the same as the point that lies at a distance of the arrow's
- |length| from the wall -- rather it lies at a distance of |length|
- minus the |inset|. Let us call this point the \emph{visual
- end} of the arrow.
-\end{enumerate}
-
-As pointed out earlier, for straight lines, shortening the path and rotating
-and shifting the arrow tip so that it ends precisely at the tip end and the
-visual end lies on a line from the tip end to the start of the line is
-relatively easy.
-
-For curved lines, things are much more difficult and \tikzname\ copes with the
-difficulties in different ways, depending on which options you add to arrows.
-Here is now a curved red line to which we wish to add our arrow tip (the
-original straight red line is shown in light red):
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm] (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
-
-The first way of dealing with curved lines is dubbed the ``quick and dirty''
-way (although the option for selecting this option is politely just called
-``|quick|'' \dots):
-
-\begin{key}{/pgf/arrow keys/quick}
- Recall that curves in \tikzname\ are actually Bézier curves, which means
- that they start and end at certain points and we specify two vectors, one
- for the start and one for the end, that provide tangents to the curve at
- these points. In particular, for the end of the curve, there is a point
- called the \emph{second support point} of the curve such that a tangent to
- the curve at the end goes through this point. In our above example, the
- second support point is at the middle of the light red line and, indeed, a
- tangent to the red line at the point touching the wall is perfectly
- horizontal.
-
- In order to add our arrow tip to the curved path, our first objective is to
- ``shorten'' the path by 6.25mm. Unfortunately, this is now much more
- difficult than for a straight path. When the |quick| option is added to an
- arrow tip (it is also the default if no special libraries are loaded), we
- cheat somewhat: Instead of really moving along 6.25mm along the path, we
- simply shift the end of the curve by 6.25mm \emph{along the tangent} (which
- is easy to compute). We also have to shift the second support point by the
- same amount to ensure that the line still has the same tangent at the end.
- This will result in the following:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,quick]}]
- (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
-
- They main problem with the above picture is that the red line is no longer
- equal to the original red line (notice much sharper curvature near its
- end). In our example this is not such a bad thing, but it certainly ``not a
- nice thing'' that adding arrow tips to a curve changes the overall shape of
- the curves. This is especially bothersome if there are several similar
- curves that have different arrow heads. In this case, the similar curves
- now suddenly look different.
-
- Another big problem with the above approach is that it works only well if
- there is only a single arrow tip. When there are multiple ones, simply
- shifting them along the tangent as the |quick| option does produces
- less-than-satisfactory results:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{[quick,sep]>>>}]
- (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- Note that the third arrow tip does not really lie on the curve any more.
-\end{key}
-
-Because of the shortcomings of the |quick| key, more powerful mechanisms for
-shortening lines and rotating arrows tips have been implemented. To use them,
-you need to load the following library:
-
-\begin{tikzlibrary}{bending}
- Load this library to use the |flex|, |flex'|, or |bending| arrow keys. When
- this library is loaded, |flex| becomes the default mode that is used with
- all paths, unless |quick| is explicitly selected for the arrow tip.
-\end{tikzlibrary}
-
-\begin{key}{/pgf/arrow keys/flex=\opt{\meta{factor}} (default 1)}
- When the |bending| library is loaded, this key is applied to all arrow tips
- by default. It has the following effect:
- %
- \begin{enumerate}
- \item Instead of simply shifting the visual end of the arrow along
- the tangent of the curve's end, we really move it along the curve
- by the necessary distance. This operation is more expensive than
- the |quick| operation -- but not \emph{that} expensive, only
- expensive enough so that it is not selected by default for all
- arrow tips. Indeed, some compromises are made in the
- implementation where accuracy was traded for speed, so the
- distance by which the line end is shifted is not necessarily
- \emph{exactly} 6.25mm; only something reasonably close.
- \item The supports of the line are updated accordingly so that the
- shortened line will still follow \emph{exactly} the original
- line. This means that the curve deformation effect caused by the
- |quick| command does not happen here.
- \item Next, the arrow tip is rotated and shifted as follows: First,
- we shift it so that its tip is exactly at the tip end, where the
- original line ended. Then, the arrow is rotated so the \emph{the
- visual end lies on the line}:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex]}]
- (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{enumerate}
-
- As can be seen in the example, the |flex| option gives a result that is
- visually pleasing and does not deform the path.
-
- There is, however, one possible problem with the |flex| option: The arrow
- tip no longer points along the tangent of the end of the path. This may or
- may not be a problem, put especially for larger arrow tips readers will use
- the orientation of the arrow head to gauge the direction of the tangent of
- the line. If this tangent is important (for example, if it should be
- horizontal), then it may be necessary to enforce that the arrow tip
- ``really points in the direction of the tangent''.
-
- To achieve this, the |flex| option takes an optional \meta{factor}
- parameter, which defaults to |1|. This factor specifies how much the arrow
- tip should be rotated: If set to |0|, the arrow points exactly along a
- tangent to curve at its tip. If set to |1|, the arrow point exactly along a
- line from the visual end point on the curve to the tip. For values in the
- middle, we interpolate the rotation between these two extremes; so
- |flex=.5| will rotate the arrow's visual end ``halfway away from the
- tangent towards the actual position on the line''.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex=0]}]
- (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex=.5]}]
- (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- Note how in the above examples the red line is visible inside the open
- arrow tip. Open arrow tips do not go well with a flex value other than~|1|.
- Here is a more realistic use of the |flex=0| key:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{Stealth[length=1cm,flex=0]}]
- (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- If there are several arrow tips on a path, the |flex| option positions them
- independently, so that each of them lies optimally on the path:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{bending}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{[flex,sep]>>>}]
- (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/arrow keys/flex'=\opt{\meta{factor}} (default 1)}
- The |flex'| key is almost identical to the |flex| key. The only difference
- is that a factor of |1| corresponds to rotating the arrow tip so that the
- instead of the visual end, the ``ultimate back end'' of the arrow tip lies
- on the red path. In the example instead of having the arrow tip at a
- distance of |6.25mm| from the tip lie on the path, we have the point at a
- distance of |1cm| from the tip lie on the path:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{Stealth[length=1cm,open,blue,flex']}]
- (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- Otherwise, the factor works as for |flex| and, indeed |flex=0| and
- |flex'=0| have the same effect.
-
- The main use of this option is not so much with an arrow tip like |Stealth|
- but rather with tips like the standard |>| in the context of a strongly
- curved line:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{Computer Modern Rightarrow[flex]}]
- (0,-.5) .. controls (1,-.5) and (0.5,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- In the example, the |flex| option does not really flex the arrow since for
- a tip like the Computer Modern arrow, the visual end is the same as the
- arrow tip -- after all, the red line does, indeed, end almost exactly where
- it used to end.
-
- Nevertheless, you may feel that the arrow tip looks ``wrong'' in the sense
- that it should be rotated. This is exactly what the |flex'| option does
- since it allows us to align the ``back end'' of the tip with the red line:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{Computer Modern Rightarrow[flex'=.75]}]
- (0,-.5) .. controls (1,-.5) and (0.5,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- In the example, I used |flex'=.75| so as not to overpronounce the effect.
- Usually, you will have to fiddle with it sometime to get the ``perfectly
- aligned arrow tip'', but a value of |.75| is usually a good start.
-\end{key}
-
-\begin{key}{/pgf/arrow keys/bend}
- \emph{Bending} an arrow tip is a radical solution to the problem of
- positioning arrow tips on a curved line: The arrow tip is no longer
- ``rigid'' but the drawing itself will now bend along the curve. This has
- the advantage that all the problems of flexing with wrong tangents and
- overflexing disappear. The downsides are longer computation times (bending
- an arrow is \emph{much} more expensive that flexing it, let alone than
- quick mode) and also the fact that excessive bending can lead to ugly arrow
- tips. On the other hand, for most arrow tips their bend version are
- visually quite pleasing and create a sophisticated look:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{Stealth[length=20pt,bend]}]
- (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{bending}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{[bend,sep]>>>}]
- (-1,-.5) .. controls (0,-.5) and (0,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
-\begin{tikzpicture}
- \wall
- \draw [red!25,line width=1mm] (-1,0) -- (1,0);
- \draw [red,line width=1mm,-{Stealth[bend,round,length=20pt]}]
- (0,-.5) .. controls (1,-.5) and (0.25,0) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-% TODOsp: codeexamples: `bending` library is needed up to here
-% TODOsp: codeexamples: `\def\wall` + `patterns` library are needed up to here
-% TODOsp: codeexamples: `arrows.meta` library needed up to here
-
-
-\subsection{Arrow Tip Specifications}
-\label{section-arrow-spec}
-
-\subsubsection{Syntax}
-
-When you select the arrow tips for the start and the end of a path, you can
-specify a whole sequence of arrow tips, each having its own local options. At
-the beginning of this section, it was pointed out that the syntax for selecting
-the start and end arrow tips is the following:
-%
-\begin{quote}
- \meta{start specification}|-|\meta{end specification}
-\end{quote}
-
-We now have a closer look at what these specifications may look like. The
-general syntax of the \meta{start specification} is as follows:
-%
-\begin{quote}
- \opt{|[|\meta{options for all tips}|]|} \meta{first arrow tip spec}
- \meta{second arrow tip spec} \meta{third arrow tip spec} \dots
-\end{quote}
-%
-As can be seen, an arrow tip specification may start with some options in
-brackets. If this is the case, the \meta{options for all tips} will, indeed, be
-applied to all arrow tips that follow. (We will see, in a moment, that there
-are even more places where options may be specified and a list of the ordering
-in which the options are applied will be given later.)
-
-The main part of a specification is taken up by a sequence of individual arrow
-tip specifications. Such a specification can be of three kinds:
-%
-\begin{enumerate}
- \item It can be of the form \meta{arrow tip kind
- name}|[|\meta{options}|]|.
- \item It can be of the form \meta{shorthand}|[|\meta{options}|]|.
- \item It can be of the form \meta{single char
- shorthand}\opt{|[|\meta{options}|]|}. Note that only for this form
- the brackets are optional.
-\end{enumerate}
-
-The easiest kind is the first one: This adds an arrow tip of the kind
-\meta{arrow tip kind name} to the sequence of arrow tips with the
-\meta{options} applied to it at the start (for the \meta{start specification})
-or at the end (for the \meta{end specification}). Note that for the \meta{start
-specification} the first arrow tip specified in this way will be at the very
-start of the curve, while for the \meta{end specification} the ordering is
-reversed: The last arrow tip specified will be at the very end of the curve.
-This implies that a specification like
-%
-\begin{quote}
- |Stealth[] Latex[] - Latex[] Stealth[]|
-\end{quote}
-%
-will give perfectly symmetric arrow tips on a line (as one would expect).
-
-It is important that even if there are no \meta{options} for an arrow tip, the
-square brackets still need to be written to indicate the end of the arrow tip's
-name. Indeed, the opening brackets are used to divide the arrow tip
-specification into names.
-
-Instead of a \meta{arrow tip kind name}, you may also provide the name of a
-so-called \emph{shorthand}. Shorthands look like normal arrow tip kind names
-and, indeed, you will often be using shorthands without noticing that you do.
-The idea is that instead of, say, |Computer Modern Rightarrow| you might wish
-to just write |Rightarrow| or perhaps just |To| or even just |>|. For this, you
-can create a shorthand that tells \tikzname\ that whenever this shorthand is
-used, another arrow tip kind is meant. (Actually, shorthands are somewhat more
-powerful, we have a detailed look at them in
-Section~\ref{section-arrow-tip-macro}.) For shorthands, the same rules apply as
-for normal arrow tip kinds: You \emph{need} to provide brackets so that
-\tikzname\ can find the end of the name inside a longer specification.
-
-The third kind of arrow tip specifications consist of just a single letter like
-|>| or |)| or |*| or even |o| or |x| (but you may not use |[|, |]|, or |-|
-since they will confuse the parser). These single letter arrow specifications
-will invariably be shorthands that select some ``real'' arrow tip instead. An
-important feature of single letter arrow tips is that they do \emph{not} need
-to be followed by options (but they may).
-
-Now, since we can use any letter for single letter shorthands, how can
-\tikzname\ tell whether by |foo[]| we mean an arrow tip kind |foo| without any
-options or whether we mean an arrow tip called |f|, followed by two arrow tips
-called |o|? Or perhaps an arrow tip called |f| followed by an arrow tip called
-|oo|? To solve this problem, the following rule is used to determine which of
-the three possible specifications listed above applies: First, we check whether
-everything from the current position up to the next opening bracket (or up to
-the end) is the name of an arrow tip or of a shorthand. In our case, |foo|
-would first be tested under this rule. Only if |foo| is neither the name of an
-arrow tip kind nor of a shorthand does \tikzname\ consider the first letter of
-the specification, |f| in our case. If this is not the name of a shorthand, an
-error is raised. Otherwise the arrow tip corresponding to |f| is added to the
-list of arrow tips and the process restarts with the rest. Thus, we would next
-text whether |oo| is the name of an arrow tip or shorthand and, if not, whether
-|o| is such a name.
-
-All of the above rules mean that you can rather easily specify arrow tip
-sequences if they either mostly consist of single letter names or of longer
-names. Here are some examples:
-%
-\begin{itemize}
- \item |->>>| is interpreted as three times the |>| shorthand since |>>>| is
- not the name of any arrow tip kind (and neither is |>>|).
- \item |->[]>>| has the same effect as the above.
- \item |-[]>>>| also has the same effect.
- \item |->[]>[]>[]| so does this.
- \item |->Stealth| yields an arrow tip |>| followed by a |Stealth| arrow
- at the end.
- \item |-Stealth>| is illegal since there is no arrow tip |Stealth>| and
- since |S| is also not the name of any arrow tip.
- \item |-Stealth[] >| is legal and does what was presumably meant in the
- previous item.
- \item |< Stealth-| is legal and is the counterpart to |-Stealth[] >|.
- \item |-Stealth[length=5pt] Stealth[length=6pt]| selects two stealth
- arrow tips, but at slightly different sizes for the end of lines.
-\end{itemize}
-
-An interesting question concerns how flexing and bending interact with multiple
-arrow tips: After all, flexing and quick mode use different ways of shortening
-the path so we cannot really mix them. The following rule is used: We check,
-independently for the start and the end specifications, whether at least one
-arrow tip in them uses one of the options |flex|, |flex'|, or |bend|. If so,
-all |quick| settings in the other arrow tips are ignored and treated as if
-|flex| had been selected for them, too.
-
-
-\subsubsection{Specifying Paddings}
-
-When you provide several arrow tips in a row, all of them are added to the
-start or end of the line:
-%
-\begin{codeexample}[]
-\tikz \draw [<<<->>>>] (0,0) -- (2,0);
-\end{codeexample}
-%
-The question now is what will be the distance between them? For this, the
-following arrow key is important:
-
-\begin{key}{/pgf/arrow keys/sep=\meta{dimension}| |\opt{\meta{line
- width factor}}| |\opt{\meta{outer factor}} (default 0.88pt .3 1)%
-}
- When a sequence of arrow tips is specified in an arrow tip specification
- for the end of the line, the arrow tips are normally arranged in such a way
- that the tip of each arrow ends exactly at the ``back end'' of the next
- arrow tip (for start specifications, the ordering is inverted, of course).
- Now, when the |sep| option is set, instead of exactly touching the back end
- of the next arrow, the specified \meta{dimension} is added as additional
- space (the distance may also be negative, resulting in an overlap of the
- arrow tips). The optional factors have the same meaning as for the |length|
- key, see that key for details.
-
- Let us now have a look at some examples. First, we use two arrow tips with
- different separations between them:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz {
- \draw [-{>[sep=1pt]>[sep= 2pt]>}] (0,1.0) -- (1,1.0);
- \draw [-{>[sep=1pt]>[sep=-2pt]>}] (0,0.5) -- (1,0.5);
- \draw [-{> >[sep] >}] (0,0.0) -- (1,0.0);
-}
-\end{codeexample}
-
- You can also specify a |sep| for the last arrow tip in the sequence (for
- end specifications, otherwise for the first arrow tip). In this case, this
- first arrow tip will not exactly ``touch'' the point where the path ends,
- but will rather leave the specified amount of space. This is usually quite
- desirable.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,positioning}}]
-\tikz {
- \node [draw] (A) {A};
- \node [draw] (B) [right=of A] {B};
-
- \draw [-{>>[sep=2pt]}] (A) to [bend left=45] (B);
- \draw [- >> ] (A) to [bend right=45] (B);
-}
-\end{codeexample}
- %
- Indeed, adding a |sep| to an arrow tip is \emph{very} desirable, so you
- will usually write something like |>={To[sep]}| somewhere near the start of
- your files.
-
- One arrow tip kind can be quite useful in this context: The arrow tip kind
- |_|. It draws nothing and has zero length, \emph{but} it has |sep| set as a
- default option. Since it is a single letter shorthand, you can write short
- and clean ``code'' in this way:
- %
-\begin{codeexample}[]
-\tikz \draw [->_>] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[]
-\tikz \draw [->__>] (0,0) -- (1,0);
-\end{codeexample}
- %
- However, using the |sep| option will be faster than using the |_| arrow tip
- and it also allows you to specify the desired length directly.
-\end{key}
-
-
-\subsubsection{Specifying the Line End}
-
-In the previous examples of sequences of arrow tips, the line of the path
-always ended at the last of the arrow tips (for end specifications) or at the
-first of the arrow tips (for start specifications). Often, this is what you may
-want, but not always. Fortunately, it is quite easy to specify the desired end
-of the line: The special single char shorthand |.| is reserved to indicate that
-last arrow that is still part of the line; in other words, the line will stop
-at the last arrow before |.| is encountered (for end specifications) are at the
-first arrow following |.| (for start specifications).
-%
-\begin{codeexample}[]
-\tikz [very thick] \draw [<<<->>>] (0,0) -- (2,0);
-\end{codeexample}
-\begin{codeexample}[]
-\tikz [very thick] \draw [<.<<->.>>] (0,0) -- (2,0);
-\end{codeexample}
-\begin{codeexample}[]
-\tikz [very thick] \draw [<<.<-.>>>] (0,0) -- (2,0);
-\end{codeexample}
-\begin{codeexample}[]
-\tikz [very thick] \draw [<<.<->.>>] (0,0) to [bend left] (2,0);
-\end{codeexample}
-
-It is permissible that there are several dots in a specification, in this case
-the first one ``wins'' (for end specifications, otherwise the last one).
-
-Note that |.| is parsed as any other shorthand. In particular, if you wish to
-add a dot after a normal arrow tip kind name, you need to add brackets:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [very thick] \draw [-{Stealth[] . Stealth[] Stealth[]}] (0,0) -- (2,0);
-\end{codeexample}
-%
-Adding options to |.| is permissible, but they have no effect. In particular,
-|sep| has no effect since a dot is not an arrow.
-
-
-\subsubsection{Defining Shorthands}
-\label{section-arrow-tip-macro}
-
-It is often desirable to create ``shorthands'' for the names of arrow tips that
-you are going to use very often. Indeed, in most documents you will only need a
-single arrow tip kind and it would be useful that you could refer to it just as
-|>| in your arrow tip specifications. As another example, you might constantly
-wish to switch between a filled and a non-filled circle as arrow tips and would
-like to use |*| and |o| are shorthands for these case. Finally, you might just
-like to shorten a long name like |Computer Modern Rightarrow| down to just, say
-|To| or something similar.
-
-All of these case can be addressed by defining appropriate shorthands. This is
-done using the following handler:
-
-\begin{handler}{{.tip}{=\meta{end specification}}}
- Defined the \meta{key} as a name that can be used inside arrow tip
- specifications. If the \meta{key} has a path before it, this path is
- ignored (so there is only one ``namespace'' for arrow tips). Whenever it is
- used, it will be replaced by the \meta{end specification}. Note that you
- must \emph{always} provide (only) an end specification; when the \meta{key}
- is used inside a start specification, the ordering and the meaning of the
- keys inside the \meta{end specification} are translated automatically.
- \todosp{remaining instance of bug \#473}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [foo /.tip = {Stealth[sep]. >>}]
- \draw [-foo] (0,0) -- (2,0);
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [foo /.tip = {Stealth[sep] Latex[sep]},
- bar /.tip = {Stealth[length=10pt,open]}]
- \draw [-{foo[red] . bar}] (0,0) -- (2,0);
-\end{codeexample}
-
- In the last of the examples, we used |foo[red]| to make the arrows red. Any
- options given to a shorthand upon use will be passed on to the actual
- arrows tip for which the shorthand stands. Thus, we could also have written
- |Stealth[sep,red]| |Latex[sep,red]| instead of |foo[red]|. In other words,
- the ``replacement'' of a shorthand by its ``meaning'' is a semantic
- replacement rather than a syntactic replacement. In particular, the
- \meta{end specification} will be parsed immediately when the shorthand is
- being defined. However, this applies only to the options inside the
- specification, whose values are evaluated immediately. In contrast, which
- actual arrow tip kind is meant by a given shorthand used inside the
- \meta{end specification} is resolved only up each use of the shorthand.
- This means that when you write
- %
- \begin{quote}
- |dup /.tip = >>|
- \end{quote}
- %
- and then later write
- %
- \begin{quote}
- |> /.tip = whatever|
- \end{quote}
- %
- then |dup| will have the effect as if you had written
- |whatever[]whatever[]|. You will find that this behavior is what one would
- expect.
-
- There is one problem we have not yet addressed: The asymmetry of single
- letter arrow tips like |>| or |)|. When someone writes
- %
-\begin{codeexample}[]
-\tikz \draw [<->] (0,0) -- (1,0);
-\end{codeexample}
- %
- we rightfully expect one arrow tip pointing left at the left end and an
- arrow tip pointing right at the right end. However, compare
- %
-\begin{codeexample}[]
-\tikz \draw [>->] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [Stealth-Stealth] (0,0) -- (1,0);
-\end{codeexample}
- %
- In both cases, we have \emph{identical} text in the start and end
- specifications, but in the first case we rightfully expect the left arrow
- to be flipped.
-
- The solution to this problem is that it is possible to define two names for
- the same arrow tip, namely one that is used inside start specifications and
- one for end specifications. Now, we can decree that the ``name of |>|''
- inside start specifications is simply |<| and the above problems disappear.
-
- To specify different names for a shorthand in start and end specifications,
- use the following syntax: Instead of \meta{key}, you use \meta{name in
- start specifications}|-|\meta{name in end specifications}. Thus, to set the
- |>| key correctly, you actually need to write
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [<-> /.tip = Stealth] \draw [<->>] (0,0) -- (1,0);
-\end{codeexample}
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz [<-> /.tip = Latex] \draw [>-<] (0,0) -- (1,0);
-\end{codeexample}
-
- Note that the above also works even though we have not set |<| as an arrow
- tip name for end specifications! The reason this works is that the
- \tikzname\ (more precisely, \pgfname) actually uses the following
- definition internally:
- %
- \begin{quote}
- |>-< /.tip = >[reversed]|
- \end{quote}
- %
- Translation: ``When |<| is used in an end specification, please replace it
- by |>|, but reversed. Also, when |>| is used in a start specification, we
- also mean this inverted |>|.''
-
- By default, |>| is a shorthand for |To| and |To| is a shorthand for |to|
- (an arrow from the old libraries) when |arrows.meta| is not loaded library.
- When |arrows.meta| is loaded, |To| is redefined to mean the same as
- |Computer Modern Rightarrow|.
-\end{handler}
-
-\begin{key}{/tikz/>=\meta{end arrow specification}}
- This is a short way of saying |<->/.tip=|\meta{end arrow specification}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\begin{tikzpicture}[scale=2,ultra thick]
- \begin{scope}[>=Latex]
- \draw[>->] (0pt,3ex) -- (1cm,3ex);
- \draw[|<->>|] (0pt,2ex) -- (1cm,2ex);
- \end{scope}
- \begin{scope}[>=Stealth]
- \draw[>->] (0pt,1ex) -- (1cm,1ex);
- \draw[|<<.<->|] (0pt,0ex) -- (1cm,0ex);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/shorten <=\meta{length}}
- Shorten the path by \meta{length} in the direction of the starting point.
-\end{key}
-
-\begin{key}{/tikz/shorten >=\meta{length}}
- Shorten the path by \meta{length} in the direction of the end point.
-\end{key}
-
-
-\subsubsection{Scoping of Arrow Keys}
-\label{section-arrow-scopes}
-
-There are numerous places where you can specify keys for an arrow tip. There
-is, however, one final place that we have not yet mentioned:
-
-\begin{key}{/tikz/arrows=|[|\meta{arrow keys}|]|}
- The |arrows| key, which is normally used to set the arrow tips for the
- current scope, can also be used to set some arrow keys for the current
- scope. When the argument to |arrows| starts with an opening bracket and
- only otherwise contains one further closing bracket at the very end, this
- semantic of the |arrow| key is assumed.
-
- The \meta{arrow keys} will be set for the rest of current scope. This is
- useful for generally setting some design parameters or for generally
- switching on, say, bending as in:
- %
-\begin{codeexample}[code only]
-\tikz [arrows={[bend]}] ... % Bend all arrows
-\end{codeexample}
- %
-\end{key}
-
-We can now summarize which arrow keys are applied in what order when an arrow
-tip is used:
-%
-\begin{enumerate}
- \item First, the so-called \emph{defaults} are applied, which are values
- for the different parameters of a key. They are fixed in the
- definition of the key and cannot be changed. Since they are executed
- first, they are only the ultimate fallback.
- \item The \meta{keys} from the use of |arrows=[|\meta{keys}|]| in all
- enclosing scopes.
- \item Recursively, the \meta{keys} provided with the arrow tip inside
- shorthands.
- \item The keys provided at the beginning of an arrow tip specification in
- brackets.
- \item The keys provided directly next to the arrow tip inside the
- specification.
-\end{enumerate}
-
-
-\subsection{Reference: Arrow Tips}
-\label{section-arrows-meta}
-
-\begin{pgflibrary}{arrows.meta}
- This library defines a large number of standard ``meta'' arrow tips.
- ``Meta'' means that you can configure these arrow tips in many different
- ways like changing their size or their line caps and joins and many other
- details.
-
- The only reason this library is not loaded by default is for compatibility
- with older versions of \tikzname. You can, however, safely load and use
- this library alongside the older libraries |arrows| and |arrows.spaced|.
-\end{pgflibrary}
-
-The different arrow tip kinds defined in the |arrows.meta| library can be
-classified in different groups:
-%
-\begin{itemize}
- \item \emph{Barbed} arrow tips consist mainly of lines that ``point
- backward'' from the tip of the arrow and which are not filled. For
- them, filling has no effect. A typical example is \tikz [baseline]
- \draw (0,.5ex) -- (1.5em,.5ex) [-Straight Barb];. Here is the list of
- defined arrow tips:
- %
- \begin{arrowexamples}
- \arrowexample Arc Barb[]
- \arrowexample Bar[]
- \arrowexample Bracket[]
- \arrowexample Hooks[]
- \arrowexample Parenthesis[]
- \arrowexample Straight Barb[]
- \arrowexample Tee Barb[]
- \end{arrowexamples}
-
- All of these arrow tips can be configured and resized in many different
- ways as described in the following. Above, they are shown at their
- ``natural'' sizes, which are chosen in such a way that for a line width
- of 0.4pt their width matches the height of a letter ``x'' in Computer
- Modern at 11pt (with some ``overshooting'' to create visual
- consistency).
- \item \emph{Mathematical} arrow tips are actually a subclass of the
- barbed arrow tips, but we list them separately. They contain arrow
- tips that look exactly like the tips of arrows used in mathematical
- fonts such as the |\to|-symbol $\to$ from standard \TeX.
- %
- \begin{arrowexamples}
- \arrowexample Classical TikZ Rightarrow[]
- \arrowexample Computer Modern Rightarrow[]
- \arrowexampledouble Implies[]
- \arrowexample To[]
- \end{arrowexamples}
- %
- The |To| arrow tip is a shorthand for |Computer Modern Rightarrow| when
- |arrows.meta| is loaded.
- \item \emph{Geometric} arrow tips consist of a filled shape like a kite
- or a circle or a ``stealth-fighter-like'' shape. A typical example is
- \tikz [baseline] \draw (0,.5ex) -- (1.5em,.5ex) [-Stealth];. These
- arrow tips can also be used in an ``open'' variant as in \tikz
- [baseline] \draw (0,.5ex) -- (1.5em,.5ex) [-{Stealth[open]}];.
- %
- \begin{arrowexamples}
- \arrowexample Circle[]
- \arrowexample Diamond[]
- \arrowexample Ellipse[]
- \arrowexample Kite[]
- \arrowexample Latex[]
- \arrowexample Latex[round]
- \arrowexample Rectangle[]
- \arrowexample Square[]
- \arrowexample Stealth[]
- \arrowexample Stealth[round]
- \arrowexample Triangle[]
- \arrowexample Turned Square[]
- \end{arrowexamples}
-
- Here are the ``open'' variants:
- %
- \begin{arrowexamples}
- \arrowexample Circle[open]
- \arrowexample Diamond[open]
- \arrowexample Ellipse[open]
- \arrowexample Kite[open]
- \arrowexample Latex[open]
- \arrowexample Latex[round,open]
- \arrowexample Rectangle[open]
- \arrowexample Square[open]
- \arrowexample Stealth[open]
- \arrowexample Stealth[round,open]
- \arrowexample Triangle[open]
- \arrowexample Turned Square[open]
- \end{arrowexamples}
-
- Note that ``open'' arrow tips are not the same as ``filled with
- white'', which is also available (just say |fill=white|). The
- difference is that the background will ``shine through'' an open
- arrow, while a filled arrow always obscures the background:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz {
- \shade [left color=white, right color=red!50] (0,0) rectangle (4,1);
-
- \draw [ultra thick,-{Triangle[open]}] (0,2/3) -- ++ (3,0);
- \draw [ultra thick,-{Triangle[fill=white]}] (0,1/3) -- ++ (3,0);
-}
-\end{codeexample}
-
- \item \emph{Cap} arrow tips are used to add a ``cap'' to the end of a
- line. The graphic languages underlying \tikzname\ (\textsc{pdf},
- \textsc{postscript} or \textsc{svg}) all support three basic types of
- line caps on a very low level: round, rectangular, and ``butt''.
- Using cap arrow tips, you can add new caps to lines and use different
- caps for the end and the start. An example is the line \tikz
- [baseline] \draw [line width=1ex, {Round Cap[reversed]}-{Triangle
- Cap[] . Fast Triangle[] Fast Triangle[]}] (0,0.5ex) -- (2em,0.5ex);.
- %
- \begin{arrowcapexamples}
- \arrowcapexample Butt Cap[]
- \arrowcapexample Fast Round[]
- \arrowcapexample Fast Triangle[]
- \arrowcapexample Round Cap[]
- \arrowcapexample Triangle Cap[]
- \end{arrowcapexamples}
- \item \emph{Special} arrow tips are used for some specific purpose and do
- not fit into the above categories.
- %
- \begin{arrowexamples}
- \arrowexample Rays[]
- \arrowexample Rays[n=8]
- \end{arrowexamples}
-\end{itemize}
-
-
-\subsubsection{Barbed Arrow Tips}
-
-\begin{arrowtip}{Arc Barb}{
- This arrow tip attaches an arc to the end of the line whose angle is given
- by the |arc| option. The |length| and |width| parameters refer to the size
- of the arrow tip for |arc| set to 180 degrees, which is why in the example
- for |arc=210| the actual length is larger than the specified |length|. The
- line width is taken into account for the computation of the length and
- width. Use the |round| option to add round caps to the end of the arcs.
-}%
-{length=1.5cm,arc=210}%
-{length=1.5cm,width=3cm}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[arc=120]
- \arrowexample[arc=270]
- \arrowexample[length=2pt]
- \arrowexample[length=2pt,width=5pt]
- \arrowexample[line width=2pt]
- \arrowexample[reversed]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[harpoon,reversed]
- \arrowexample[red]
- \end{arrowexamples}
- %
- The following options have no effect: |open|, |fill|.
-
- On |double| lines, the arrow tip will not look correct.
-\end{arrowtip}
-
-\begin{arrowtipsimple}{Bar}
- A simple bar. This is a simple instance of |Tee Barb| for length zero.
-\end{arrowtipsimple}
-
-\begin{arrowtip}{Bracket}{
- This is an instance of the |Tee Barb| \todosp{no space shown here} arrow tip that results in something
- resembling a bracket. Just like the |Parenthesis| arrow tip, a |Bracket| is
- not modelled from a text square bracket, but rather its size has been
- chosen so that it fits with the other arrow tips.
-}%
-{}%
-{}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[reversed]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[harpoon,reversed]
- \arrowexample[red]
- \end{arrowexamples}
- %
- The following options have no effect: |open|, |fill|.
-
- On |double| lines, the arrow tip will not look correct.
-\end{arrowtip}
-
-\begin{arrowtip}{Hooks}{
- This arrow tip attaches two ``hooks'' to the end of the line. The |length|
- and |width| parameters refer to the size of the arrow tip if both arcs are
- 180 degrees; in the example the arc is 210 degrees and, thus, the arrow is
- actually longer that the |length| dictates. The line width is taken into
- account for the computation of the length and width. The |arc| option is
- used to specify the angle of the arcs. Use the |round| option to add round
- caps to the end of the arcs.
-}%
-{length=1cm,width=3.5cm,arc=210}%
-{length=1cm,width=3.5cm}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[arc=120]
- \arrowexample[arc=270]
- \arrowexample[length=2pt]
- \arrowexample[length=2pt,width=5pt]
- \arrowexample[line width=2pt]
- \arrowexample[reversed]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[harpoon,reversed]
- \arrowexample[red]
- \end{arrowexamples}
- %
- The following options have no effect: |open|, |fill|.
-
- On |double| lines, the arrow tip will not look correct.
-\end{arrowtip}
-
-\begin{arrowtip}{Parenthesis}{
- This arrow tip is an instantiation of the |Arc Barb| \todosp{no space shown here} so that it resembles a
- parenthesis. However, the idea is not to recreate a ``real'' parenthesis as
- it is used in text, but rather a ``bow'' at a size that harmonizes with the
- other arrow tips at their default sizes.
-}%
-{}%
-{}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[reversed]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[harpoon,reversed]
- \arrowexample[red]
- \end{arrowexamples}
- %
- The following options have no effect: |open|, |fill|.
-
- On |double| lines, the arrow tip will not look correct.
-\end{arrowtip}
-
-\begin{arrowtip}{Straight Barb}{
- This is the ``archetypal'' arrow head, consisting of just two straight
- lines. The |length| and |width| parameters refer to the horizontal and
- vertical distances between the points on the path making up the arrow tip.
- As can be seen, the line width of the arrow tip's path is not taken into
- account. The |angle| option is particularly useful to set the opening angle
- at the tip of the arrow head. The |round| option gives a ``softer'' or
- ``rounder'' version of the arrow tip.
-}%
-{length=2cm,width=3cm}%
-{length=2cm/-4mm,width=3cm}
-
- \begin{arrowexamples}
- \arrowexample[]
-% \arrowexampledouble[]
- \arrowexampledup[]
- \arrowexampledupdot[]
- \arrowexample[length=5pt]
- \arrowexample[length=5pt,width=5pt]
- \arrowexample[line width=2pt]
- \arrowexample[reversed]
- \arrowexample[angle=60:2pt 3]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[harpoon,reversed]
- \arrowexample[red]
- \end{arrowexamples}
- %
- The following options have no effect: |open|, |fill|.
-
- On |double| lines, the arrow tip will not look correct.
-\end{arrowtip}
-
-\begin{arrowtip}{Tee Barb}{
- This arrow tip attaches a little ``T'' on both sides of the tip. The arrow
- |inset| dictates the distance from the back end to the middle of the stem
- of the T. When the inset is equal to the length, the arrow tip is drawn as
- a single line, not as three lines (this is important for the ``round''
- version since, then, the corners get rounded).
-}%
-{length=1.5cm,width=3cm,inset=1cm}%
-{length=1.5cm,width=3cm,inset=1cm}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[inset=0pt]
- \arrowexample[inset'=0pt 1]
- \arrowexample[line width=2pt]
- \arrowexample[round]
- \arrowexample[round,inset'=0pt 1]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[harpoon,reversed]
- \arrowexample[red]
- \end{arrowexamples}
- %
- The following options have no effect: |open|, |fill|.
-
- On |double| lines, the arrow tip will not look correct.
-\end{arrowtip}
-
-
-\subsubsection{Mathematical Barbed Arrow Tips}
-
-\begin{arrowtip}{Classical TikZ Rightarrow}{
- This arrow tip is the ``old'' or ``classical'' arrow tip that used to be
- the standard in \tikzname\ in earlier versions. It was modelled on an old
- version of the tip of \texttt{\string\rightarrow} ($\rightarrow$) of the
- Computer Modern fonts. However, this ``old version'' was really old, Donald
- Knuth (the designer of both \TeX\ and of the Computer Modern fonts)
- replaced the arrow tip of the mathematical fonts in~1992.
-}%
-{length=1cm,width=2cm}%
-{length=1cm,width=2cm}
-
- The main problem with this arrow tip is that it is ``too small'' at its
- natural size. I recommend using the new \texttt{Computer Modern Rightarrow}
- arrow tip instead, which matches the current $\to$. This new version is
- also the default used as |>| and as |To|, now.
- %
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[length=3pt]
- \arrowexample[sharp]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[harpoon,reversed]
- \arrowexample[red]
- \end{arrowexamples}
- %
- The following options have no effect: |open|, |fill|.
-
- On |double| lines, the arrow tip will not look correct.
-\end{arrowtip}
-
-\begin{arrowtip}{Computer Modern Rightarrow}{
- For a line width of 0.4pt (the default), this arrow tip looks very much
- like \texttt{\string\rightarrow} ($\to$) of the Computer Modern math fonts.
- However, it is not a ``perfect'' match: the line caps and joins of the
- ``real'' $\to$ are rounded differently from this arrow tip; but it takes a
- keen eye to notice the difference. When the |arrows.meta| library is loaded,
- this arrow tip becomes the default of |To| and, thus, is used whenever |>|
- is used (unless, of course, you redefined |>|).
-}%
-{length=1cm,width=2cm}%
-{length=1cm,width=2cm}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[length=3pt]
- \arrowexample[sharp]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[harpoon,reversed]
- \arrowexample[red]
- \end{arrowexamples}
- %
- The following options have no effect: |open|, |fill|.
-
- On |double| lines, the arrow tip will not look correct.
-\end{arrowtip}
-
-\begin{arrowtipsimple}{Implies}
- This arrow tip makes only sense in conjunction with the |double| option.
- The idea is that you attach it to a double line to get something that looks
- like \TeX's \texttt{\string\implies} arrow ($\implies$). A typical use of
- this arrow tip is
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,graphs}}]
-\tikz \graph [clockwise=3, math nodes,
- edges = {double equal sign distance, -Implies}] {
- "\alpha", "\beta", "\gamma";
- "\alpha" -> "\beta" -> "\gamma" -> "\alpha"
-};
-\end{codeexample}
- %
- \begin{arrowexamples}
- \arrowexampledouble[]
- \arrowexampledouble[red]
- \end{arrowexamples}
-\end{arrowtipsimple}
-
-\begin{arrowtipsimple}{To}
- This is a shorthand for |Computer Modern Rightarrow| when the |arrows.meta|
- library is loaded. Otherwise, it is a shorthand for the classical
- \tikzname\ rightarrow.
-\end{arrowtipsimple}
-
-
-\subsubsection{Geometric Arrow Tips}
-
-\begin{arrowtip}{Circle}{
- Although this tip is called ``circle'', you can also use it to draw
- ellipses if you set the length and width to different values. Neither
- |round| nor |reversed| has any effect on this arrow tip.
-}%
-{length=2cm,width=2cm}%
-{length=2cm,width=2cm}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[open]
- \arrowexample[length=3pt]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[red]
- \end{arrowexamples}
-\end{arrowtip}
-
-\begin{arrowtipsimple}{Diamond}
- This is an instance of |Kite| where the length is larger than the width.
- %
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[]
- \arrowexampledupdot[]
- \arrowexample[open]
- \arrowexample[length=10pt]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[red]
- \arrowexample[fill=red!50]
- \end{arrowexamples}
-\end{arrowtipsimple}
-
-\begin{arrowtipsimple}{Ellipse}
- This is a shorthand for a ``circle'' that is twice as wide as high.
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[open]
- \arrowexample[length=10pt]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[red]
- \arrowexample[fill=red!50]
- \end{arrowexamples}
-\end{arrowtipsimple}
-
-\begin{arrowtip}{Kite}{
- This arrow tip consists of four lines that form a ``kite''. The |inset|
- prescribed how far the width-axis of the kite is removed from the back end.
- Note that the inset cannot be negative, use a |Stealth| arrow tip for this.
-}%
-{length=3cm,width=2cm,inset=1cm}%
-{length=3cm,width=2cm,inset=1cm}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[open]
- \arrowexample[length=6pt,width=4pt]
- \arrowexample[length=6pt,width=4pt,inset=1.5pt]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[red]
- \end{arrowexamples}
-\end{arrowtip}
-
-\begin{arrowtip}{Latex}{
- This arrow tip is the same as the arrow tip used in \LaTeX's standard
- pictures (via the \texttt{\string\vec} command), if you set the length to
- 4pt. The default size for this arrow tip was set slightly larger so that it
- fits better with the other geometric arrow tips.
-}%
-{length=3cm,width=2cm}%
-{length=3cm,width=2cm}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[open]
- \arrowexample[length=4pt]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[red]
- \end{arrowexamples}
-\end{arrowtip}
-
-\begin{arrowtipsimple}{LaTeX}
- Another spelling for the |Latex| arrow tip.
-\end{arrowtipsimple}
-
-\begin{arrowtip}{Rectangle}{
- A rectangular arrow tip. By default, it is twice as long as high.
-}%
-{length=3cm,width=2cm}%
-{length=3cm,width=2cm}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[open]
- \arrowexample[length=4pt]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[red]
- \end{arrowexamples}
-\end{arrowtip}
-
-\begin{arrowtipsimple}{Square}
- An instance of the |Rectangle| whose width is identical to the length.
- %
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[open]
- \arrowexample[length=4pt]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[red]
- \end{arrowexamples}
-\end{arrowtipsimple}
-
-\begin{arrowtip}{Stealth}{
- This arrow tip is similar to a |Kite|, only the |inset| now counts
- ``inwards''. Because of that sharp angles, for this arrow tip is makes
- quite a difference, visually, if use the |round| option. Also, using the
- |harpoon| option (or |left| or |right|) will \emph{lengthen} the arrow tip
- because of the even sharper corner at the tip.
-}%
-{length=3cm,width=2cm,inset=1cm}%
-{length=3cm,width=2cm,inset=1cm}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[open]
- \arrowexample[length=6pt,width=4pt]
- \arrowexample[length=6pt,width=4pt,inset=1.5pt]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[red]
- \end{arrowexamples}
-\end{arrowtip}
-
-\begin{arrowtipsimple}{Triangle}
- An instance of a |Kite| with zero inset.
- %
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[open]
- \arrowexample[length=4pt]
- \arrowexample[angle=45:1pt 3]
- \arrowexample[angle=60:1pt 3]
- \arrowexample[angle=90:1pt 3]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[red]
- \end{arrowexamples}
-\end{arrowtipsimple}
-
-\begin{arrowtipsimple}{Turned Square}
- An instance of a |Kite| with identical width and height and mid-inset.
- %
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[open]
- \arrowexample[length=4pt]
- \arrowexample[round]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[red]
- \end{arrowexamples}
-\end{arrowtipsimple}
-
-
-\subsubsection{Caps}
-
-Recall that a \emph{cap} is a way of ending a line. The graphic languages
-underlying \tikzname\ (\textsc{pdf}, \textsc{postscript} or \textsc{svg}) all
-support three basic types of line caps on a very low level: round, rectangular,
-and ``butt''. Using cap arrow tips, you can add new caps to lines and use
-different caps for the end and the start.
-
-\begin{arrowtipsimple}{Butt Cap}
- This arrow tip ends the line ``in the normal way'' with a straight end.
- This arrow tip is only need to ``cover up'' the actual line cap, if this
- happens to differ from the normal cap. In the following example, the line
- cap is ``round'', but, nevertheless, the right end is a ``butt'' cap:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [line width=1ex, line cap=round, -Butt Cap] (0,0) -- (1,0);
-\end{codeexample}
- %
-\end{arrowtipsimple}
-
-\begin{arrowcap}{Fast Round}{
- This arrow tip is not really a cap, you use it in conjunction with
- (typically) the |Round Cap|. The idea is that you end your line using the
- round cap and then add several \texttt{Fast Round}s. As for |Round Cap|,
- the |length| parameter dictates the length is the length of the ``main
- part'', the inset sets the length of a line that comes before this tip.
-}%
-{length=5mm,inset=1cm}%
-{length=5mm,inset=-1cm}%
-{-15mm}
-
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [line width=1ex,
- -{Round Cap []. Fast Round[] Fast Round[]}]
- (0,0) -- (1,0);
-\end{codeexample}
- %
- Note that in conjunction with the |bend| option, this works even quite well
- for curves:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
-\tikz [f/.tip = Fast Round] % shorthand
- \draw [line width=1ex, -{[bend] Round Cap[] . f f f}]
- (0,0) to [bend left] (1,0);
-\end{codeexample}
-
- \begin{arrowcapexamples}
- \arrowcapexample[]
- \arrowcapexample[reversed]
- \arrowcapexample[cap angle=60]
- \arrowcapexample[cap angle=60,inset=5pt]
- \arrowcapexample[length=.5ex]
- \arrowcapexample[slant=.3]
- \end{arrowcapexamples}
-\end{arrowcap}
-
-\begin{arrowcap}{Fast Triangle}{
- This arrow tip works like |Fast Round|, only for triangular caps.
-}%
-{length=5mm,inset=1cm}%
-{length=5mm,inset=-1cm}%
-{-15mm}
-
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\tikz \draw [line width=1ex,
- -{Triangle Cap []. Fast Triangle[] Fast Triangle[]}]
- (0,0) -- (1,0);
-\end{codeexample}
- %
- Again, this tip works well for curves:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,bending}}]
-\tikz [f/.tip = Fast Triangle] % shorthand
- \draw [line width=1ex, -{[bend] Triangle Cap[] . f f f}]
- (0,0) to [bend left] (1,0);
-\end{codeexample}
-
- \begin{arrowcapexamples}
- \arrowcapexample[]
- \arrowcapexample[reversed]
- \arrowcapexample[cap angle=60]
- \arrowcapexample[cap angle=60,inset=5pt]
- \arrowcapexample[length=.5ex]
- \arrowcapexample[slant=.3]
- \end{arrowcapexamples}
-\end{arrowcap}
-
-
-\begin{arrowcap}{Round Cap}{
- This arrow tip ends the line using a half circle or, if the length has been
- modified, a half-ellipse.
- }%
-{length=5mm}%
-{length=5mm}%
-{-5mm}
-
- \begin{arrowcapexamples}
- \arrowcapexample[]
- \arrowcapexample[reversed]
- \arrowcapexample[length=.5ex]
- \arrowcapexample[slant=.3]
- \end{arrowcapexamples}
-\end{arrowcap}
-
-\begin{arrowcap}{Triangle Cap}{
- This arrow tip ends the line using a triangle whose length is given by the
- |length| option.
-}%
-{length=5mm}%
-{length=5mm}%
-{-5mm}
-
- You can get any angle you want at the tip by specifying a length that is an
- appropriate multiple of the line width. The following options does this
- computation for you:
- %
- \begin{key}{/pgf/arrow keys/cap angle=\meta{angle}}
- Sets |length| to an appropriate multiple of the line width so that the
- angle of a |Triangle Cap| is exactly \meta{angle} at the tip.
- \end{key}
-
- \begin{arrowcapexamples}
- \arrowcapexample[]
- \arrowcapexample[reversed]
- \arrowcapexample[cap angle=60]
- \arrowcapexample[cap angle=60,reversed]
- \arrowcapexample[length=.5ex]
- \arrowcapexample[slant=.3]
- \end{arrowcapexamples}
-\end{arrowcap}
-
-
-\subsubsection{Special Arrow Tips}
-
-\begin{arrowtip}{Rays}{
- This arrow tip attaches a ``bundle of rays'' to the tip. The number of
- evenly spaced rays is given by the |n| arrow key (see below). When the
- number is even, the rays will lie to the left and to the right of the
- direction of the arrow; when the number is odd, the rays are rotated in
- such a way that one of them points perpendicular to the direction of the
- arrow (this is to ensure that no ray points in the direction of the line,
- which would look strange). The |length| and |width| describe the length and
- width of an ellipse into which the rays fit.
-}%
-{length=3cm,width=3cm,n=6}%
-{length=3cm,width=3cm}
-
- \begin{arrowexamples}
- \arrowexample[]
- \arrowexampledup[sep]
- \arrowexampledupdot[sep]
- \arrowexample[width'=0pt 2]
- \arrowexample[round]
- \arrowexample[n=2]
- \arrowexample[n=3]
- \arrowexample[n=4]
- \arrowexample[n=5]
- \arrowexample[n=6]
- \arrowexample[n=7]
- \arrowexample[n=8]
- \arrowexample[n=9]
- \arrowexample[slant=.3]
- \arrowexample[left]
- \arrowexample[right]
- \arrowexample[left,n=5]
- \arrowexample[right,n=5]
- \arrowexample[red]
- \end{arrowexamples}
-\end{arrowtip}
-
-\begin{key}{/pgf/arrow keys/n=\meta{number} (initially 4)}
- Sets the number of rays in a |Rays| arrow tip.
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-coordinates.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-coordinates.tex
deleted file mode 100644
index 7257629b80..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-coordinates.tex
+++ /dev/null
@@ -1,1330 +0,0 @@
-% 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{Specifying Coordinates}
-
-\subsection{Overview}
-
-A \emph{coordinate} is a position on the canvas on which your picture is drawn.
-\tikzname\ uses a special syntax for specifying coordinates. Coordinates are
-always put in round brackets. The general syntax is
-\declare{|(|\opt{|[|\meta{options}|]|}\meta{coordinate specification}|)|}.
-
-The \meta{coordinate specification} specifies coordinates using one of many
-different possible \emph{coordinate systems}. Examples are the Cartesian
-coordinate system or polar coordinates or spherical coordinates. No matter
-which coordinate system is used, in the end, a specific point on the canvas is
-represented by the coordinate.
-
-There are two ways of specifying which coordinate system should be used:
-%
-\begin{description}
- \item[Explicitly] You can specify the coordinate system explicitly. To do
- so, you give the name of the coordinate system at the beginning,
- followed by |cs:|, which stands for ``coordinate system'', followed by
- a specification of the coordinate using the key--value syntax. Thus,
- the general syntax for \meta{coordinate specification} in the explicit
- case is |(|\meta{coordinate system}| cs:|\meta{list of key--value pairs
- specific to the coordinate system}|)|.
- \item[Implicitly] The explicit specification is often too verbose when
- numerous coordinates should be given. Because of this, for the
- coordinate systems that you are likely to use often a special syntax
- is provided. \tikzname\ will notice when you use a coordinate
- specified in a special syntax and will choose the correct coordinate
- system automatically.
-\end{description}
-
-Here is an example in which explicit the coordinate systems are specified
-explicitly:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (canvas cs:x=0cm,y=2mm)
- -- (canvas polar cs:radius=2cm,angle=30);
-\end{tikzpicture}
-\end{codeexample}
-%
-In the next example, the coordinate systems are implicit:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0cm,2mm) -- (30:2cm);
-\end{tikzpicture}
-\end{codeexample}
-
-It is possible to give options that apply only to a single coordinate, although
-this makes sense for transformation options only. To give transformation
-options for a single coordinate, give these options at the beginning in
-brackets:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1);
- \draw[red] (0,0) -- ([xshift=3pt] 1,1);
- \draw (1,0) -- +(30:2cm);
- \draw[red] (1,0) -- +([shift=(135:5pt)] 30:2cm);
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Coordinate Systems}
-
-\subsubsection{Canvas, XYZ, and Polar Coordinate Systems}
-
-Let us start with the basic coordinate systems.
-
-\begin{coordinatesystem}{canvas}
- The simplest way of specifying a coordinate is to use the |canvas|
- coordinate system. You provide a dimension $d_x$ using the |x=| option and
- another dimension $d_y$ using the |y=| option. The position on the canvas
- is located at the position that is $d_x$ to the right and $d_y$ above the
- origin.
-
- \begin{key}{/tikz/cs/x=\meta{dimension} (initially 0pt)}
- Distance by which the coordinate is to the right of the origin. You can
- also write things like |1cm+2pt| since the mathematical engine is used
- to evaluate the \meta{dimension}.
- \end{key}
-
- \begin{key}{/tikz/cs/y=\meta{dimension} (initially 0pt)}
- Distance by which the coordinate is above the origin.
- \end{key}
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \fill (canvas cs:x=1cm,y=1.5cm) circle (2pt);
- \fill (canvas cs:x=2cm,y=-5mm+2pt) circle (2pt);
-\end{tikzpicture}
-\end{codeexample}
-
- To specify a coordinate in the coordinate system implicitly, you use two
- dimensions that are separated by a comma as in |(0cm,3pt)| or
- |(2cm,\textheight)|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \fill (1cm,1.5cm) circle (2pt);
- \fill (2cm,-5mm+2pt) circle (2pt);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{coordinatesystem}
-
-\begin{coordinatesystem}{xyz}
- The |xyz| coordinate system allows you to specify a point as a multiple of
- three vectors called the $x$-, $y$-, and $z$-vectors. By default, the
- $x$-vector points 1cm to the right, the $y$-vector points 1cm upwards, but
- this can be changed arbitrarily as explained in Section~\ref{section-xyz}.
- The default $z$-vector points to
- $\bigl(-3.85\textrm{mm},-3.85\textrm{mm}\bigr)$.
-
- To specify the factors by which the vectors should be multiplied before
- being added, you use the following three options:
- %
- \begin{key}{/tikz/cs/x=\meta{factor} (initially 0)}
- Factor by which the $x$-vector is multiplied.
- \end{key}
- %
- \begin{key}{/tikz/cs/y=\meta{factor} (initially 0)}
- Works like |x|.
- \end{key}
- %
- \begin{key}{/tikz/cs/z=\meta{factor} (initially 0)}
- Works like |x|.
- \end{key}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[->]
- \draw (0,0) -- (xyz cs:x=1);
- \draw (0,0) -- (xyz cs:y=1);
- \draw (0,0) -- (xyz cs:z=1);
-\end{tikzpicture}
-\end{codeexample}
-
- This coordinate system can also be selected implicitly. To do so, you just
- provide two or three comma-separated factors (not dimensions).
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[->]
- \draw (0,0) -- (1,0);
- \draw (0,0) -- (0,1,0);
- \draw (0,0) -- (0,0,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{coordinatesystem}
-
-\emph{Note:} It is possible to use coordinates like |(1,2cm)|, which are
-neither |canvas| coordinates nor |xyz| coordinates. The rule is the following:
-If a coordinate is of the implicit form |(|\meta{x}|,|\meta{y}|)|, then
-\meta{x} and \meta{y} are checked, independently, whether they have a dimension
-or whether they are dimensionless. If both have a dimension, the |canvas|
-coordinate system is used. If both lack a dimension, the |xyz| coordinate
-system is used. If \meta{x} has a dimension and \meta{y} has not, then the sum
-of two coordinate |(|\meta{x}|,0pt)| and |(0,|\meta{y}|)| is used. If \meta{y}
-has a dimension and \meta{x} has not, then the sum of two coordinate
-|(|\meta{x}|,0)| and |(0pt,|\meta{y}|)| is used.
-
-\emph{Note furthermore:} An expression like |(2+3cm,0)| does \emph{not} mean
-the same as |(2cm+3cm,0)|. Instead, if \meta{x} or \meta{y} internally uses a
-mixture of dimensions and dimensionless values, then all dimensionless values
-are ``upgraded'' to dimensions by interpreting them as |pt|. So, |2+3cm| is the
-same dimension as |2pt+3cm|.
-
-\begin{coordinatesystem}{canvas polar}
- The |canvas polar| coordinate system allows you to specify polar
- coordinates. You provide an angle using the |angle=| option and a radius
- using the |radius=| option. This yields the point on the canvas that is at
- the given radius distance from the origin at the given degree. An angle of
- zero degrees to the right, a degree of 90 upward.
- %
- \begin{key}{/tikz/cs/angle=\meta{degrees}}
- The angle of the coordinate. The angle must always be given in degrees
- and should be between $-360$ and $720$.
- \end{key}
- %
- \begin{key}{/tikz/cs/radius=\meta{dimension}}
- The distance from the origin.
- \end{key}
- %
- \begin{key}{/tikz/cs/x radius=\meta{dimension}}
- A polar coordinate is, after all, just a point on a circle of the given
- \meta{radius}. When you provide an $x$-radius and also a $y$-radius,
- you specify an ellipse instead of a circle. The |radius| option has the
- same effect as specifying identical |x radius| and |y radius| options.
- \end{key}
- %
- \begin{key}{/tikz/cs/y radius=\meta{dimension}}
- Works like |x radius|.
- \end{key}
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) -- (canvas polar cs:angle=30,radius=1cm);
-\end{codeexample}
-
- The implicit form for canvas polar coordinates is the following: you
- specify the angle and the distance, separated by a colon as in |(30:1cm)|.
- %
-\begin{codeexample}[]
-\tikz \draw (0cm,0cm) -- (30:1cm) -- (60:1cm) -- (90:1cm)
- -- (120:1cm) -- (150:1cm) -- (180:1cm);
-\end{codeexample}
-
- Two different radii are specified by writing |(30:1cm and 2cm)|.
-
- For the implicit form, instead of an angle given as a number you can also
- use certain words. For example, |up| is the same as |90|, so that you can
- write |\tikz \draw (0,0) -- (2ex,0pt) -- +(up:1ex);| and get
- \tikz \draw (0,0) -- (2ex,0pt) -- +(up:1ex);. Apart from |up| you can use
- |down|, |left|, |right|, |north|, |south|, |west|, |east|, |north east|,
- |north west|, |south east|, |south west|, all of which have their natural
- meaning.
-\end{coordinatesystem}
-
-\begin{coordinatesystem}{xyz polar}
- This coordinate system work similarly to the |canvas polar| system.
- However, the radius and the angle are interpreted in the $xy$-coordinate
- system, not in the canvas system. More detailed, consider the circle or
- ellipse whose half axes are given by the current $x$-vector and the current
- $y$-vector. Then, consider the point that lies at a given angle on this
- ellipse, where an angle of zero is the same as the $x$-vector and an angle
- of 90 is the $y$-vector. Finally, multiply the resulting vector by the
- given radius factor. Voil\`a.
- %
- \begin{key}{/tikz/cs/angle=\meta{degrees}}
- The angle of the coordinate interpreted in the ellipse whose axes are
- the $x$-vector and the $y$-vector.
- \end{key}
- %
- \begin{key}{/tikz/cs/radius=\meta{factor}}
- A factor by which the $x$-vector and $y$-vector are multiplied prior to
- forming the ellipse.
- \end{key}
- %
- \begin{key}{/tikz/cs/x radius=\meta{dimension}}
- A specific factor by which only the $x$-vector is multiplied.
- \end{key}
- %
- \begin{key}{/tikz/cs/y radius=\meta{dimension}}
- Works like |x radius|.
- \end{key}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[x=1.5cm,y=1cm]
- \draw[help lines] (0cm,0cm) grid (3cm,2cm);
-
- \draw (0,0) -- (xyz polar cs:angle=0,radius=1);
- \draw (0,0) -- (xyz polar cs:angle=30,radius=1);
- \draw (0,0) -- (xyz polar cs:angle=60,radius=1);
- \draw (0,0) -- (xyz polar cs:angle=90,radius=1);
-
- \draw (xyz polar cs:angle=0,radius=2)
- -- (xyz polar cs:angle=30,radius=2)
- -- (xyz polar cs:angle=60,radius=2)
- -- (xyz polar cs:angle=90,radius=2);
- \end{tikzpicture}
-\end{codeexample}
-
- The implicit version of this option is the same as the implicit version of
- |canvas polar|, only you do not provide a unit.
-
-\begin{codeexample}[]
-\tikz[x={(0cm,1cm)},y={(-1cm,0cm)}]
- \draw (0,0) -- (30:1) -- (60:1) -- (90:1)
- -- (120:1) -- (150:1) -- (180:1);
-\end{codeexample}
- %
-\end{coordinatesystem}
-
-\begin{coordinatesystem}{xy polar}
- This is just an alias for |xyz polar|, which some people might prefer as
- there is no z-coordinate involved in the |xyz polar| coordinates.
-\end{coordinatesystem}
-
-
-\subsubsection{Barycentric Systems}
-\label{section-barycentric-coordinates}
-
-In the barycentric coordinate system a point is expressed as the linear
-combination of multiple vectors. The idea is that you specify vectors $v_1$,
-$v_2$, \dots, $v_n$ and numbers $\alpha_1$, $\alpha_2$, \dots, $\alpha_n$. Then
-the barycentric coordinate specified by these vectors and numbers is
-%
-\begin{align*}
- \frac{\alpha_1 v_1 + \alpha_2 v_2 + \cdots + \alpha_n v_n}{\alpha_1
- + \alpha_2 + \cdots + \alpha_n}
-\end{align*}
-
-The |barycentric cs| allows you to specify such coordinates easily.
-
-\begin{coordinatesystem}{barycentric}
- For this coordinate system, the \meta{coordinate specification} should be a
- comma-separated list of expressions of the form \meta{node
- name}|=|\meta{number}. Note that (currently) the list should not contain
- any spaces before or after the \meta{node name} (unlike normal key--value
- pairs).
-
- The specified coordinate is now computed as follows: Each pair provides one
- vector and a number. The vector is the |center| anchor of the \meta{node
- name}. The number is the \meta{number}. Note that (currently) you cannot
- specify a different anchor, so that in order to use, say, the |north|
- anchor of a node you first have to create a new coordinate at this north
- anchor. (Using for instance \texttt{\string\coordinate (mynorth) at
- (mynode.north);}.)
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \coordinate (content) at (90:3cm);
- \coordinate (structure) at (210:3cm);
- \coordinate (form) at (-30:3cm);
-
- \node [above] at (content) {content oriented};
- \node [below left] at (structure) {structure oriented};
- \node [below right] at (form) {form oriented};
-
- \draw [thick,gray] (content.south) -- (structure.north east) -- (form.north west) -- cycle;
-
- \small
- \node at (barycentric cs:content=0.5,structure=0.1 ,form=1) {PostScript};
- \node at (barycentric cs:content=1 ,structure=0 ,form=0.4) {DVI};
- \node at (barycentric cs:content=0.5,structure=0.5 ,form=1) {PDF};
- \node at (barycentric cs:content=0 ,structure=0.25,form=1) {CSS};
- \node at (barycentric cs:content=0.5,structure=1 ,form=0) {XML};
- \node at (barycentric cs:content=0.5,structure=1 ,form=0.4) {HTML};
- \node at (barycentric cs:content=1 ,structure=0.2 ,form=0.8) {\TeX};
- \node at (barycentric cs:content=1 ,structure=0.6 ,form=0.8) {\LaTeX};
- \node at (barycentric cs:content=0.8,structure=0.8 ,form=1) {Word};
- \node at (barycentric cs:content=1 ,structure=0.05,form=0.05) {ASCII};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{coordinatesystem}
-
-
-\subsubsection{Node Coordinate System}
-\label{section-node-coordinates}
-
-In \pgfname\ and in \tikzname\ it is quite easy to define a node that you wish
-to reference at a later point. Once you have defined a node, there are
-different ways of referencing points of the node. To do so, you use the
-following coordinate system:
-
-\begin{coordinatesystem}{node}
- This coordinate system is used to reference a specific point inside or on
- the border of a previously defined node. It can be used in different ways,
- so let us go over them one by one.
-
- You can use three options to specify which coordinate you mean:
- %
- \begin{key}{/tikz/cs/name=\meta{node name}}
- Specifies the node that you wish to use to specify a coordinate. The
- \meta{node name} is the name that was previously used to name the node
- using the |name=|\meta{node name} option or the special node name
- syntax.
- \end{key}
- %
- \begin{key}{/tikz/anchor=\meta{anchor}}
- Specifies an anchor of the node. Here is an example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\begin{tikzpicture}
- \node (shape) at (0,2) [draw] {|class Shape|};
- \node (rect) at (-2,0) [draw] {|class Rectangle|};
- \node (circle) at (2,0) [draw] {|class Circle|};
- \node (ellipse) at (6,0) [draw] {|class Ellipse|};
-
- \draw (node cs:name=circle,anchor=north) |- (0,1);
- \draw (node cs:name=ellipse,anchor=north) |- (0,1);
- \draw [arrows = -{Triangle[open, angle=60:3mm]}]
- (node cs:name=rect,anchor=north)
- |- (0,1) -| (node cs:name=shape,anchor=south);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/cs/angle=\meta{degrees}}
- It is also possible to provide an angle \emph{instead} of an anchor.
- This coordinate refers to a point of the node's border where a ray shot
- from the center in the given angle hits the border. Here is an example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}
- \node (start) [draw,shape=ellipse] {start};
- \foreach \angle in {-90, -80, ..., 90}
- \draw (node cs:name=start,angle=\angle)
- .. controls +(\angle:1cm) and +(-1,0) .. (2.5,0);
- \end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- It is possible to provide \emph{neither} the |anchor=| option nor the
- |angle=| option. In this case, \tikzname\ will calculate an appropriate
- border position for you. Here is an example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}
- \path (0,0) node(a) [ellipse,rotate=10,draw] {An ellipse}
- (3,-1) node(b) [circle,draw] {A circle};
- \draw[thick] (node cs:name=a) -- (node cs:name=b);
-\end{tikzpicture}
-\end{codeexample}
-
- \tikzname\ will be reasonably clever at determining the border points that
- you ``mean'', but, naturally, this may fail in some situations. If
- \tikzname\ fails to determine an appropriate border point, the center will
- be used instead.
-
- Automatic computation of anchors works only with the line-to operations
- |--|, the vertical/horizontal versions \verb!|-! and \verb!-|!, and with
- the curve-to operation |..|. For other path commands, such as |parabola| or
- |plot|, the center will be used. If this is not desired, you should give a
- named anchor or an angle anchor.
-
- Note that if you use an automatic coordinate for both the start and the end
- of a line-to, as in |--(node cs:name=b)--|, then \emph{two} border
- coordinates are computed with a move-to between them. This is usually
- exactly what you want.
-
- If you use relative coordinates together with automatic anchor coordinates,
- the relative coordinates are computed relative to the node's center, not
- relative to the border point. Here is an example:
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) node(x) [draw] {Text}
- rectangle (1,1)
- (node cs:name=x) -- +(1,1);
-\end{codeexample}
-
- Similarly, in the following examples both control points are $(1,1)$:
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) node(x) [draw] {X}
- (2,0) node(y) {Y}
- (node cs:name=x) .. controls +(1,1) and +(-1,1) ..
- (node cs:name=y);
-\end{codeexample}
-
- The implicit way of specifying the node coordinate system is to simply use
- the name of the node in parentheses as in |(a)| or to specify a name
- together with an anchor or an angle separated by a dot as in |(a.north)| or
- |(a.10)|.
-
- Here is a more complete example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[fill=blue!20]
- \draw[help lines] (-1,-2) grid (6,3);
- \path (0,0) node(a) [ellipse,rotate=10,draw,fill] {An ellipse}
- (3,-1) node(b) [circle,draw,fill] {A circle}
- (2,2) node(c) [rectangle,rotate=20,draw,fill] {A rectangle}
- (5,2) node(d) [rectangle,rotate=-30,draw,fill] {Another rectangle};
- \draw[thick] (a.south) -- (b) -- (c) -- (d);
- \draw[thick,red,->] (a) |- +(1,3) -| (c) |- (b);
- \draw[thick,blue,<->] (b) .. controls +(right:2cm) and +(down:1cm) .. (d);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{coordinatesystem}
-
-% -----------------------------------------------------------------------------
-% Deprecated:
-% -----------------------------------------------------------------------------
-%
-% \subsubsection{Intersection Coordinate Systems}
-%
-% Often you wish to specify a point that is on the
-% intersection of two lines or shapes. For this, the following
-% coordinate system is useful:
-%
-% \begin{coordinatesystem}{intersection}
-% First, you must specify two objects that should be
-% intersected. These ``objects'' can either be lines or the shapes of
-% nodes. There are two option to specify the first object:
-% \begin{key}{/tikz/cs/first line={\ttfamily\char`\{}|(|\meta{first
-% coordinate}|)--(|\meta{second coordinate}|)|{\ttfamily\char`\}}}
-% Specifies that the first object is a line that goes from
-% \meta{first coordinate} to meta{second coordinate}.
-% \end{key}
-% Note that you have to write |--| between the coordinate, but this
-% does not mean that anything is added to the path. This is simply a
-% special syntax.
-% \begin{key}{/tikz/cs/first node=\meta{node}}
-% Specifies that the first object is a previously defined node named
-% \meta{node}.
-% \end{key}
-%
-% To specify the second object, you use one of the following keys:
-% \begin{key}{/tikz/cs/second line={\ttfamily\char`\{}|(|\meta{first
-% coordinate}|)--(|\meta{second coordinate}|)|{\ttfamily\char`\}}}
-% As above.
-% \end{key}
-% \begin{key}{/tikz/cs/second node=\meta{node}}
-% Specifies that the second object is a previously defined node
-% named \meta{node}.
-% \end{key}
-%
-% Since it is possible that two objects have multiple intersections,
-% you may need to specify which solution you want:
-% \begin{key}{/tikz/cs/solution=\meta{number} (initially 1)}
-% Specifies which solution should be used. Numbering starts with 1.
-% \end{key}
-% The coordinate specified in this way is the \meta{number}th
-% intersection of the two objects. If the objects do not intersect,
-% an error may occur.
-%
-% \begin{codeexample}[]
-% \begin{tikzpicture}
-% \draw[help lines] (0,0) grid (3,2);
-% \draw (0,0) coordinate (A) -- (3,2) coordinate (B)
-% (1,2) -- (3,0);
-%
-% \fill[red] (intersection cs:
-% first line={(A)--(B)},
-% second line={(1,2)--(3,0)}) circle (2pt);
-% \end{tikzpicture}
-% \end{codeexample}
-%
-% The implicit way of specifying this coordinate system is to write
-% \declare{|(intersection |\opt{\meta{number}}| of |\meta{first
-% object}%
-% | and |\meta{second object}|)|}. Here, \meta{first object} either
-% has the form \meta{$p_1$}|--|\meta{$p_2$} or it is just a node
-% name. Likewise for \meta{second object}. Note that there are \emph{no}
-% parentheses around the $p_i$. Thus, you would write
-% |(intersection of A--B and 1,2--3,0)| for the intersection of the
-% line through the coordinates |A| and |B| and the line through the
-% points $(1,2)$ and $(3,0)$. You would write
-% |(intersection 2 of c_1 and c_2)| for the second
-% intersection of the node named |c_1| and the node named
-% |c_2|.
-%
-% \tikzname\ needs an explicit algorithm for computing the
-% intersection of two shapes and such an algorithm is available only
-% for few shapes. Currently, the following intersection will be
-% computed correctly:
-% \begin{itemize}
-% \item a line and a line
-% \item a |circle| node and a line (in any order)
-% \item a |circle| and a |circle|
-% \end{itemize}
-% \begin{codeexample}[]
-% \begin{tikzpicture}[scale=.25]
-% \coordinate [label=-135:$a$] (a) at ($ (0,0) + (rand,rand) $);
-% \coordinate [label=45:$b$] (b) at ($ (3,2) + (rand,rand) $);
-%
-% \coordinate [label=-135:$u$] (u) at (-1,1);
-% \coordinate [label=45:$v$] (v) at (6,0);
-%
-% \draw (a) -- (b)
-% (u) -- (v);
-%
-% \node (c1) at (a) [draw,circle through=(b)] {};
-% \node (c2) at (b) [draw,circle through=(a)] {};
-%
-% \coordinate [label=135:$c$] (c) at (intersection 2 of c1 and c2);
-% \coordinate [label=-45:$d$] (d) at (intersection of u--v and c2);
-% \coordinate [label=135:$e$] (e) at (intersection of u--v and a--b);
-%
-% \foreach \p in {a,b,c,d,e,u,v}
-% \fill [opacity=.5] (\p) circle (8pt);
-% \end{tikzpicture}
-% \end{codeexample}
-% \end{coordinatesystem}
-% -----------------------------------------------------------------------------
-
-
-\subsubsection{Tangent Coordinate Systems}
-
-\begin{coordinatesystem}{tangent}
- This coordinate system, which is available only when the \tikzname\ library
- |calc| is loaded, allows you to compute the point that lies tangent to a
- shape. In detail, consider a \meta{node} and a \meta{point}. Now, draw a
- straight line from the \meta{point} so that it ``touches'' the \meta{node}
- (more formally, so that it is \emph{tangent} to this \meta{node}). The
- point where the line touches the shape is the point referred to by the
- |tangent| coordinate system.
-
- The following options may be given:
- %
- \begin{key}{/tikz/cs/node=\meta{node}}
- This key specifies the node on whose border the tangent should lie.
- \end{key}
- %
- \begin{key}{/tikz/cs/point=\meta{point}}
- This key specifies the point through which the tangent should go.
- \end{key}
- %
- \begin{key}{/tikz/cs/solution=\meta{number}}
- Specifies which solution should be used if there are more than one.
- \end{key}
-
- A special algorithm is needed in order to compute the tangent for a given
- shape. Currently, tangents can be computed for nodes whose shape is one of
- the following:
- %
- \begin{itemize}
- \item |coordinate|
- \item |circle|
- \end{itemize}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
-
- \coordinate (a) at (3,2);
-
- \node [circle,draw] (c) at (1,1) [minimum size=40pt] {$c$};
-
- \draw[red] (a) -- (tangent cs:node=c,point={(a)},solution=1) --
- (c.center) -- (tangent cs:node=c,point={(a)},solution=2) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
-
- There is no implicit syntax for this coordinate system.
-\end{coordinatesystem}
-
-
-\subsubsection{Defining New Coordinate Systems}
-
-While the set of coordinate systems that \tikzname\ can parse via their special
-syntax is fixed, it is possible and quite easy to define new explicitly named
-coordinate systems. For this, the following commands are used:
-
-\begin{command}{\tikzdeclarecoordinatesystem\marg{name}\marg{code}}
- This command declares a new coordinate system named \meta{name} that can
- later on be used by writing |(|\meta{name}| cs:|\meta{arguments}|)|. When
- \tikzname\ encounters a coordinate specified in this way, the
- \meta{arguments} are passed to \meta{code} as argument |#1|.
-
- It is now the job of \meta{code} to make sense of the \meta{arguments}. At
- the end of \meta{code}, the two \TeX\ dimensions |\pgf@x| and |\pgf@y|
- should be have the $x$- and $y$-canvas coordinate of the coordinate.
-
- It is not necessary, but customary, to parse \meta{arguments} using the
- key--value syntax. However, you can also parse it in any way you like.
-
- In the following example, a coordinate system |cylindrical| is defined.
- %
-\begin{codeexample}[]
-\makeatletter
-\define@key{cylindricalkeys}{angle}{\def\myangle{#1}}
-\define@key{cylindricalkeys}{radius}{\def\myradius{#1}}
-\define@key{cylindricalkeys}{z}{\def\myz{#1}}
-\tikzdeclarecoordinatesystem{cylindrical}%
-{%
- \setkeys{cylindricalkeys}{#1}%
- \pgfpointadd{\pgfpointxyz{0}{0}{\myz}}{\pgfpointpolarxy{\myangle}{\myradius}}
-}
-\begin{tikzpicture}[z=0.2pt]
- \draw [->] (0,0,0) -- (0,0,350);
- \foreach \num in {0,10,...,350}
- \fill (cylindrical cs:angle=\num,radius=1,z=\num) circle (1pt);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\tikzaliascoordinatesystem\marg{new name}\marg{old name}}
- Creates an alias of \meta{old name}.
-\end{command}
-
-
-\subsection{Coordinates at Intersections}
-\label{section-intersection-coordinates}
-
-You will wish to compute the intersection of two paths. For the special and
-frequent case of two perpendicular lines, a special coordinate system called
-|perpendicular| is available. For more general cases, the |intersection|
-library can be used.
-
-
-\subsubsection{Intersections of Perpendicular Lines}
-
-A frequent special case of path intersections is the intersection of a vertical
-line going through a point $p$ and a horizontal line going through some other
-point $q$. For this situation there is a useful coordinate system.
-
-\begin{coordinatesystem}{perpendicular}
- You can specify the two lines using the following keys:
-
- \begin{key}{/tikz/cs/horizontal line through={\ttfamily\char`\{}|(|\meta{coordinate}|)|{\ttfamily\char`\}}}
- Specifies that one line is a horizontal line that goes through the
- given coordinate.
- \end{key}
- %
- \begin{key}{/tikz/cs/vertical line through={\ttfamily\char`\{}|(|\meta{coordinate}|)|{\ttfamily\char`\}}}
- Specifies that the other line is vertical and goes through the given
- coordinate.
- \end{key}
-
- However, in almost all cases you should, instead, use the implicit syntax.
- Here, you write \declare{|(|\meta{p}\verb! |- !\meta{q}|)|} or
- \declare{|(|\meta{q}\verb! -| !\meta{p}|)|}.
-
- For example, \verb!(2,1 |- 3,4)! and \verb!(3,4 -| 2,1)! both yield the
- same as \verb!(2,4)! (provided the $xy$-co\-or\-di\-nate system has not
- been modified).
-
- The most useful application of the syntax is to draw a line up to some
- point on a vertical or horizontal line. Here is an example:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \path (30:1cm) node(p1) {$p_1$} (75:1cm) node(p2) {$p_2$};
-
- \draw (-0.2,0) -- (1.2,0) node(xline)[right] {$q_1$};
- \draw (2,-0.2) -- (2,1.2) node(yline)[above] {$q_2$};
-
- \draw[->] (p1) -- (p1 |- xline);
- \draw[->] (p2) -- (p2 |- xline);
- \draw[->] (p1) -- (p1 -| yline);
- \draw[->] (p2) -- (p2 -| yline);
-\end{tikzpicture}
-\end{codeexample}
-
- Note that in \declare{|(|\meta{c}\verb! |- !\meta{d}|)|} the coordinates
- \meta{c} and \meta{d} are \emph{not} surrounded by parentheses. If they
- need to be complicated expressions (like a computation using the
- |$|-syntax), you must surround them with braces; parentheses will then be %$
- added around them.
-
- As an example, let us specify a point that lies horizontally at the middle
- of the line from $A$ to~$B$ and vertically at the middle of the line from
- $C$ to~$D$:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \node (A) at (0,1) {A};
- \node (B) at (1,1.5) {B};
- \node (C) at (2,0) {C};
- \node (D) at (2.5,-2) {D};
-
- \draw (A) -- (B) node [midway] {x};
- \draw (C) -- (D) node [midway] {x};
-
- \node at ({$(A)!.5!(B)$} -| {$(C)!.5!(D)$}) {X};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{coordinatesystem}
-
-
-\subsubsection{Intersections of Arbitrary Paths}
-
-\begin{tikzlibrary}{intersections}
- This library enables the calculation of intersections of two arbitrary
- paths. However, due to the low accuracy of \TeX, the paths should not be
- ``too complicated''. In particular, you should not try to intersect paths
- consisting of lots of very small segments such as plots or decorated paths.
-\end{tikzlibrary}
-
-To find the intersections of two paths in \tikzname, they must be ``named''. A
-``named path'' is, quite simply, a path that has been named using the following
-key (note that this is a \emph{different} key from the |name| key, which only
-attaches a hyperlink target to a path, but does not store the path in a way the
-is useful for the intersection computation):
-
-\begin{keylist}{%
- /tikz/name path=\meta{name},
- /tikz/name path global=\meta{name}%
-}
- The effect of this key is that, after the path has been constructed, just
- before it is used, it is associated with \meta{name}. For |name path|, this
- association survives beyond the final semi-colon of the path but not the
- end of the surrounding scope. For |name path global|, the association will
- survive beyond any scope as well. Handle with care.
-
- Any paths created by nodes on the (main) path are ignored, unless this key
- is explicitly used. If the same \meta{name} is used for the main path and
- the node path(s), then the paths will be added together and then associated
- with \meta{name}.
-\end{keylist}
-
-To find the intersection of named paths, the following key is used:
-
-\begin{key}{/tikz/name intersections=\marg{options}}
- This key changes the key path to |/tikz/intersection| and processes
- \meta{options}. These options determine, among other things, which paths to
- use for the intersection. Having processed the options, any intersections
- are then found. A coordinate is created at each intersection, which by
- default, will be named |intersection-1|, |intersection-2|, and so on.
- Optionally, the prefix |intersection| can be changed, and the total number
- of intersections stored in a \TeX-macro.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
-\begin{tikzpicture}[every node/.style={opacity=1, black, above left}]
- \draw [help lines] grid (3,2);
- \draw [name path=ellipse] (2,0.5) ellipse (0.75cm and 1cm);
- \draw [name path=rectangle, rotate=10] (0.5,0.5) rectangle +(2,1);
- \fill [red, opacity=0.5, name intersections={of=ellipse and rectangle}]
- (intersection-1) circle (2pt) node {1}
- (intersection-2) circle (2pt) node {2};
-\end{tikzpicture}
-\end{codeexample}
-
- The following keys can be used in \meta{options}:
-
- \begin{key}{/tikz/intersection/of=\meta{name path 1}| and |\meta{name path 2}}
- This key is used to specify the names of the paths to use for the
- intersection.
- \end{key}
-
- \begin{key}{/tikz/intersection/name=\meta{prefix} (initially intersection)}
- This key specifies the prefix name for the coordinate nodes placed at
- each intersection.
- \end{key}
-
- \begin{key}{/tikz/intersection/total=\meta{macro}}
- This key means that the total number of intersections found will be
- stored in \meta{macro}.
- \end{key}
-
-\begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
-\begin{tikzpicture}
- \clip (-2,-2) rectangle (2,2);
- \draw [name path=curve 1] (-2,-1) .. controls (8,-1) and (-8,1) .. (2,1);
- \draw [name path=curve 2] (-1,-2) .. controls (-1,8) and (1,-8) .. (1,2);
-
- \fill [name intersections={of=curve 1 and curve 2, name=i, total=\t}]
- [red, opacity=0.5, every node/.style={above left, black, opacity=1}]
- \foreach \s in {1,...,\t}{(i-\s) circle (2pt) node {\footnotesize\s}};
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{key}{/tikz/intersection/by=\meta{comma-separated list}}
- This key allows you to specify a list of names for the intersection
- coordinates. The intersection coordinates will still be named
- \meta{prefix}|-|\meta{number}, but additionally the first coordinate
- will also be named by the first element of the \meta{comma-separated
- list}. What happens is that the \meta{comma-separated list} is passed
- to the |\foreach| statement and for \meta{list member} a coordinate is
- created at the already-named intersection.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
-\begin{tikzpicture}
- \clip (-2,-2) rectangle (2,2);
- \draw [name path=curve 1] (-2,-1) .. controls (8,-1) and (-8,1) .. (2,1);
- \draw [name path=curve 2] (-1,-2) .. controls (-1,8) and (1,-8) .. (1,2);
-
- \fill [name intersections={of=curve 1 and curve 2, by={a,b}}]
- (a) circle (2pt)
- (b) circle (2pt);
-\end{tikzpicture}
-\end{codeexample}
-
- You can also use the |...| notation of the |\foreach| statement inside
- the \meta{comma-separated list}.
-
- In case an element of the \meta{comma-separated list} starts with
- options in square brackets, these options are used when the coordinate
- is created. A coordinate name can still, but need not, follow the
- options. This makes it easy to add labels to intersections:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
-\begin{tikzpicture}
- \clip (-2,-2) rectangle (2,2);
- \draw [name path=curve 1] (-2,-1) .. controls (8,-1) and (-8,1) .. (2,1);
- \draw [name path=curve 2] (-1,-2) .. controls (-1,8) and (1,-8) .. (1,2);
-
- \fill [name intersections={
- of=curve 1 and curve 2,
- by={[label=center:a],[label=center:...],[label=center:i]}}];
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/intersection/sort by=\meta{path name}}
- By default, the intersections are simply returned in the order that the
- intersection algorithm finds them. Unfortunately, this is not
- necessarily a ``helpful'' ordering. This key can be used to sort the
- intersections along the path specified by \meta{path name}, which
- should be one of the paths mentioned in the |/tikz/intersection/of|
- key.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
-\begin{tikzpicture}
-\clip (-0.5,-0.75) rectangle (3.25,2.25);
-\foreach \pathname/\shift in {line/0cm, curve/2cm}{
- \tikzset{xshift=\shift}
- \draw [->, name path=curve] (1,1.5) .. controls (-1,1) and (2,0.5) .. (0,0);
- \draw [->, name path=line] (0,-.5) -- (1,2) ;
- \fill [name intersections={of=line and curve,sort by=\pathname, name=i}]
- [red, opacity=0.5, every node/.style={left=.25cm, black, opacity=1}]
- \foreach \s in {1,2,3}{(i-\s) circle (2pt) node {\footnotesize\s}};
-}
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-\end{key}
-
-
-\subsection{Relative and Incremental Coordinates}
-
-\subsubsection{Specifying Relative Coordinates}
-
-You can prefix coordinates by |++| to make them ``relative''. A coordinate such
-as |++(1cm,0pt)| means ``1cm to the right of the previous position, making this
-the new current position''. Relative coordinates are often useful in ``local''
-contexts:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
- \draw (2,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
- \draw (1.5,1.5) -- ++(1,0) -- ++(0,1) -- ++(-1,0) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
-
-Instead of |++| you can also use a single |+|. This also specifies a relative
-coordinate, but it does not ``update'' the current point for subsequent usages
-of relative coordinates. Thus, you can use this notation to specify numerous
-points, all relative to the same ``initial'' point:
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
- \draw (2,0) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
- \draw (1.5,1.5) -- +(1,0) -- +(1,1) -- +(0,1) -- cycle;
-\end{tikzpicture}
-\end{codeexample}
-
-There is a special situation, where relative coordinates are interpreted
-differently. If you use a relative coordinate as a control point of a Bézier
-curve, the following rule applies: First, a relative first control point is
-taken relative to the beginning of the curve. Second, a relative second control
-point is taken relative to the end of the curve. Third, a relative end point of
-a curve is taken relative to the start of the curve.
-
-This special behavior makes it easy to specify that a curve should ``leave or
-arrive from a certain direction'' at the start or end. In the following
-example, the curve ``leaves'' at $30^\circ$ and ``arrives'' at $60^\circ$:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (1,0) .. controls +(30:1cm) and +(60:1cm) .. (3,-1);
- \draw[gray,->] (1,0) -- +(30:1cm);
- \draw[gray,<-] (3,-1) -- +(60:1cm);
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{Rotational Relative Coordinates}
-
-You may sometimes wish to specify points relative not only to the previous
-point, but additionally relative to the tangent entering the previous point.
-For this, the following key is useful:
-
-\begin{key}{/tikz/turn}
- This key can be given as an option to a \meta{coordinate} as in the
- following example:
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) -- (1,1) -- ([turn]-45:1cm) -- ([turn]-30:1cm);
-\end{codeexample}
- %
- The effect of this key is to locally shift the coordinate system so that
- the last point reached is at the origin and the coordinate system is
- ``turned'' so that the $x$-axis points in the direction of a tangent
- entering the last point. This means, in effect, that when you use polar
- coordinates of the form \meta{relative angle}|:|\meta{distance} together
- with the |turn| option, you specify a point that lies at \meta{distance}
- from the last point in the direction of the last tangent entering the last
- point, but with a rotation of \meta{relative angle}.
-
- This key also works with curves \dots
- %
-\begin{codeexample}[]
-\tikz [delta angle=30, radius=1cm]
- \draw (0,0) arc [start angle=0] -- ([turn]0:1cm)
- arc [start angle=30] -- ([turn]0:1cm)
- arc [start angle=60] -- ([turn]30:1cm);
-\end{codeexample}
-\begin{codeexample}[]
-\tikz \draw (0,0) to [bend left] (2,1) -- ([turn]0:1cm);
-\end{codeexample}
- %
- \dots and with plots \dots
- %
-\begin{codeexample}[]
-\tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,0) } -- ([turn]30:1cm);
-\end{codeexample}
-
- Although the above examples use polar coordinates with |turn|, you can also
- use any normal coordinate. For instance, |([turn]1,1)| will append a line
- of length $\sqrt 2$ that is turns by $45^\circ$ relative to the tangent to
- the last point.
- %
-\begin{codeexample}[]
-\tikz \draw (0.5,0.5) -| (2,1) -- ([turn]1,1)
- .. controls ([turn]0:1cm) .. ([turn]-90:1cm);
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Relative Coordinates and Scopes}
-\label{section-scopes-relative}
-
-An interesting question is, how do relative coordinates behave in the presence
-of scopes? That is, suppose we use curly braces in a path to make part of it
-``local'', how does that affect the current position? On the one hand, the
-current position certainly changes since the scope only affects options, not
-the path itself. On the other hand, it may be useful to ``temporarily escape''
-from the updating of the current point.
-
-Since both interpretations of how the current point and scopes should
-``interact'' are useful, there is a (local!) option that allows you to decide
-which you need.
-
-\begin{key}{/tikz/current point is local=\opt{\meta{boolean}} (initially false)}
- Normally, the scope path operation has no effect on the current point. That
- is, curly braces on a path have no effect on the current position:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0);
- \draw[red] (2,0) -- ++(1,0) { -- ++(0,1) } -- ++(-1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- If you set this key to |true|, this behavior changes. In this case, at the
- end of a group created on a path, the last current position reverts to
- whatever value it had at the beginning of the scope. More precisely, when
- \tikzname\ encounters |}| on a path, it checks whether at this particular
- moment the key is set to |true|. If so, the current position reverts to the
- value it had when the matching |{| was read.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) -- ++(1,0) -- ++(0,1) -- ++(-1,0);
- \draw[red] (2,0) -- ++(1,0)
- { [current point is local] -- ++(0,1) } -- ++(-1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
- In the above example, we could also have given the option outside the
- scope, for instance as a parameter to the whole scope.
-\end{key}
-
-
-\subsection{Coordinate Calculations}
-\label{tikz-lib-calc}
-
-\begin{tikzlibrary}{calc}
- You need to load this library in order to use the coordinate calculation
- functions described in the present section.
-\end{tikzlibrary}
-
-It is possible to do some basic calculations that involve coordinates. In
-essence, you can add and subtract coordinates, scale them, compute midpoints,
-and do projections. For instance, |($(a) + 1/3*(1cm,0)$)| is the coordinate
-that is $1/3 \text{cm}$ to the right of the point |a|:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \node (a) at (1,1) {A};
- \fill [red] ($(a) + 1/3*(1cm,0)$) circle (2pt);
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{The General Syntax}
-
-The general syntax is the following:
-%
-\begin{quote}
- \declare{|(|\opt{|[|\meta{options}|]|}|$|\meta{coordinate computation}|$)|}.
-\end{quote}
-
-As you can see, the syntax uses the \TeX\ math symbol |$| to %$
-indicate that a ``mathematical computation'' is involved. However, the |$| %$
-has no other effect, in particular, no mathematical text is typeset.
-
-The \meta{coordinate computation} has the following structure:
-%
-\begin{enumerate}
- \item It starts with
- %
- \begin{quote}
- \opt{\meta{factor}|*|}\meta{coordinate}\opt{\meta{modifiers}}
- \end{quote}
- \item This is optionally followed by |+| or |-| and then another
- %
- \begin{quote}
- \opt{\meta{factor}|*|}\meta{coordinate}\opt{\meta{modifiers}}
- \end{quote}
- \item This is once more followed by |+| or |-| and another of the above
- modified coordinate; and so on.
-\end{enumerate}
-
-In the following, the syntax of factors and of the different modifiers
-is explained in detail.
-
-
-\subsubsection{The Syntax of Factors}
-
-The \meta{factor}s are optional and detected by checking whether the
-\meta{coordinate computation} starts with a |(|. Also, after each $\pm$ a
-\meta{factor} is present if, and only if, the |+| or |-| sign is not directly
-followed by~|(|.
-
-If a \meta{factor} is present, it is evaluated using the |\pgfmathparse| macro.
-This means that you can use pretty complicated computations inside a factor. A
-\meta{factor} may even contain opening parentheses, which creates a
-complication: How does \tikzname\ know where a \meta{factor} ends and where a
-coordinate starts? For instance, if the beginning of a \meta{coordinate
-computation} is |2*(3+4|\dots, it is not clear whether |3+4| is part of a
-\meta{coordinate} or part of a \meta{factor}. Because of this, the following
-rule is used: Once it has been determined, that a \meta{factor} is present, in
-principle, the \meta{factor} contains everything up to the next occurrence of
-|*(|. Note that there is no space between the asterisk and the parenthesis.
-
-It is permissible to put the \meta{factor} in curly braces. This can be used
-whenever it is unclear where the \meta{factor} would end.
-
-Here are some examples of coordinate specifications that consist of exactly one
-\meta{factor} and one \meta{coordinate}:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \fill [red] ($2*(1,1)$) circle (2pt);
- \fill [green] (${1+1}*(1,.5)$) circle (2pt);
- \fill [blue] ($cos(0)*sin(90)*(1,1)$) circle (2pt);
- \fill [black] (${3*(4-3)}*(1,0.5)$) circle (2pt);
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{The Syntax of Partway Modifiers}
-
-A \meta{coordinate} can be followed by different \meta{modifiers}. The first
-kind of modifier is the \emph{partway modifier}. The syntax (which is loosely
-inspired by Uwe Kern's |xcolor| package) is the following:
-%
-\begin{quote}
- \meta{coordinate}\declare{|!|\meta{number}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
-\end{quote}
-%
-One could write for instance
-%
-\begin{codeexample}[code only]
-(1,2)!.75!(3,4)
-\end{codeexample}
-%
-The meaning of this is: ``Use the coordinate that is three quarters on the way
-from |(1,2)| to |(3,4)|.'' In general, \meta{coordinate
-x}|!|\meta{number}|!|\meta{coordinate y} yields the coordinate $(1 -
-\meta{number})\meta{coordinate x} + \meta{number} \meta{coordinate y}$. Note
-that this is a bit different from the way the \meta{number} is interpreted in
-the |xcolor| package: First, you use a factor between $0$ and $1$, not a
-percentage, and, second, as the \meta{number} approaches $1$, we approach the
-second coordinate, not the first. It is permissible to use a \meta{number} that
-is smaller than $0$ or larger than $1$. The \meta{number} is evaluated using
-the |\pgfmathparse| command and, thus, it can involve complicated computations.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \draw (1,0) -- (3,2);
-
- \foreach \i in {0,0.2,0.5,0.9,1}
- \node at ($(1,0)!\i!(3,2)$) {\i};
-\end{tikzpicture}
-\end{codeexample}
-
-The \meta{second coordinate} may be prefixed by an \meta{angle}, separated with
-a colon, as in |(1,1)!.5!60:(2,2)|. The general meaning of
-\meta{a}|!|\meta{factor}|!|\meta{angle}|:|\meta{b} is: ``First, consider the
-line from \meta{a} to \meta{b}. Then rotate this line by \meta{angle}
-\emph{around the point \meta{a}}. Then the two endpoints of this line will be
-\meta{a} and some point \meta{c}. Use this point \meta{c} for the subsequent
-computation, namely the partway computation.''
-
-Here are two examples:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,3);
-
- \coordinate (a) at (1,0);
- \coordinate (b) at (3,2);
-
- \draw[->] (a) -- (b);
-
- \coordinate (c) at ($ (a)!1! 10:(b) $);
-
- \draw[->,red] (a) -- (c);
-
- \fill ($ (a)!.5! 10:(b) $) circle (2pt);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (4,4);
-
- \foreach \i in {0,0.1,...,2}
- \fill ($(2,2) !\i! \i*180:(3,2)$) circle (2pt);
-\end{tikzpicture}
-\end{codeexample}
-
-You can repeatedly apply modifiers. That is, after any modifier you can add
-another (possibly different) modifier.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \draw (0,0) -- (3,2);
- \draw[red] ($(0,0)!.3!(3,2)$) -- (3,0);
- \fill[red] ($(0,0)!.3!(3,2)!.7!(3,0)$) circle (2pt);
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{The Syntax of Distance Modifiers}
-
-A \emph{distance modifier} has nearly the same syntax as a partway modifier,
-only you use a \meta{dimension} (something like |1cm|) instead of a
-\meta{factor} (something like |0.5|):
-%
-\begin{quote}
- \meta{coordinate}\declare{|!|\meta{dimension}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
-\end{quote}
-
-When you write \meta{a}|!|\meta{dimension}|!|\meta{b}, this means the
-following: Use the point that is distanced \meta{dimension} from \meta{a} on
-the straight line from \meta{a} to \meta{b}. Here is an example:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \draw (1,0) -- (3,2);
-
- \foreach \i in {0cm,1cm,15mm}
- \node at ($(1,0)!\i!(3,2)$) {\i};
-\end{tikzpicture}
-\end{codeexample}
-
-As before, if you use a \meta{angle}, the \meta{second coordinate} is rotated
-by this much around the \meta{coordinate} before it is used.
-
-The combination of an \meta{angle} of |90| degrees with a distance can be used
-to ``offset'' a point relative to a line. Suppose, for instance, that you have
-computed a point |(c)| that lies somewhere on a line from |(a)| to~|(b)| and
-you now wish to offset this point by |1cm| so that the distance from this
-offset point to the line is |1cm|. This can be achieved as follows:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \coordinate (a) at (1,0);
- \coordinate (b) at (3,1);
-
- \draw (a) -- (b);
-
- \coordinate (c) at ($ (a)!.25!(b) $);
- \coordinate (d) at ($ (c)!1cm!90:(b) $);
-
- \draw [<->] (c) -- (d) node [sloped,midway,above] {1cm};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{The Syntax of Projection Modifiers}
-
-The projection modifier is also similar to the above modifiers: It also gives a
-point on a line from the \meta{coordinate} to the \meta{second coordinate}.
-However, the \meta{number} or \meta{dimension} is replaced by a
-\meta{projection coordinate}:
-%
-\begin{quote}
- \meta{coordinate}\declare{|!|\meta{projection coordinate}|!|\opt{\meta{angle}|:|}\meta{second coordinate}}
-\end{quote}
-
-Here is an example:
-%
-\begin{codeexample}[code only]
-(1,2)!(0,5)!(3,4)
-\end{codeexample}
-
-The effect is the following: We project the \meta{projection coordinate}
-orthogonally onto the line from \meta{coordinate} to \meta{second coordinate}.
-This makes it easy to compute projected points:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \coordinate (a) at (0,1);
- \coordinate (b) at (3,2);
- \coordinate (c) at (2.5,0);
-
- \draw (a) -- (b) -- (c) -- cycle;
-
- \draw[red] (a) -- ($(b)!(a)!(c)$);
- \draw[orange] (b) -- ($(a)!(b)!(c)$);
- \draw[blue] (c) -- ($(a)!(c)!(b)$);
-\end{tikzpicture}
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-decorations.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-decorations.tex
deleted file mode 100644
index df7c779ddd..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-decorations.tex
+++ /dev/null
@@ -1,559 +0,0 @@
-% Copyright 2019 by Mark Wibrow
-%
-% 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{Decorated Paths}
-\label{section-tikz-decorations}
-
-\subsection{Overview}
-
-Decorations are a general concept to make (sub)paths ``more interesting''.
-Before we have a look at the details, let us have a look at some examples:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{
- decorations.pathmorphing,
- decorations.pathreplacing,
- decorations.shapes,
-}}]
-\begin{tikzpicture}[thick]
- \draw (0,3) -- (3,3);
- \draw[decorate,decoration=zigzag] (0,2.5) -- (3,2.5);
- \draw[decorate,decoration=brace] (0,2) -- (3,2);
- \draw[decorate,decoration=triangles] (0,1.5) -- (3,1.5);
- \draw[decorate,decoration={coil,segment length=4pt}] (0,1) -- (3,1);
- \draw[decorate,decoration={coil,aspect=0}] (0,.5) -- (3,.5);
- \draw[decorate,decoration={expanding waves,angle=7}] (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- \node [fill=red!20,draw,decorate,decoration={bumps,mirror},
- minimum height=1cm]
- {Bumpy};
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- \filldraw[fill=blue!20] (0,3)
- decorate [decoration=saw] { -- (3,3) }
- decorate [decoration={coil,aspect=0}] { -- (2,1) }
- decorate [decoration=bumps] { -| (0,3) };
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- \node [fill=yellow!50,draw,thick, minimum height=2cm, minimum width=3cm,
- decorate, decoration={random steps,segment length=3pt,amplitude=1pt}]
- {Saved from trash};
-\end{tikzpicture}
-\end{codeexample}
-
-The general idea of decorations is the following: First, you construct a path
-using the usual path construction commands. The resulting path is, in essence,
-a series of straight and curved lines. Instead of directly using this path for
-filling or drawing, you can then specify that it should form the basis for a
-decoration. In this case, depending on which decoration you use, a new path is
-constructed ``along'' the path you specified. For instance, with the |zigzag|
-decoration, the new path is a zigzagging line that goes along the old path.
-
-Let us have a look at an example: In the first picture, we see a path that
-consists of a line, an arc, and a line. In the second picture, this path has
-been used as the basis of a decoration.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\tikz \fill
- [fill=blue!20,draw=blue,thick] (0,0) -- (2,1) arc (90:-90:.5) -- cycle;
-\end{codeexample}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\tikz \fill [decorate,decoration={zigzag}]
- [fill=blue!20,draw=blue,thick] (0,0) -- (2,1) arc (90:-90:.5) -- cycle;
-\end{codeexample}
-
-It is also possible to decorate only a subpath (the exact syntax will be
-explained later in this section).
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\tikz \fill [decoration={zigzag}]
- [fill=blue!20,draw=blue,thick] (0,0) -- (2,1)
- decorate { arc (90:-90:.5) } -- cycle;
-\end{codeexample}
-
-The |zigzag| decoration will be called a \emph{path morphing} decoration
-because it morphs a path into a different, but topologically equivalent path.
-Not all decorations are path morphing; rather there are three kinds of
-decorations.
-
-\begin{enumerate}
- \item The just-mentioned \emph{path morphing} decorations morph the path in
- the sense that what used to be a straight line might afterwards be a
- squiggly line or might have bumps. However, a line is still and a line
- and path deforming decorations do not change the number of subpaths.
-
- Examples of such decorations are the |snake| or the |zigzag|
- decoration. Many such decorations are defined in the library
- |decorations.pathmorphing|.
-
- \item \emph{Path replacing} decorations completely replace the path by a
- different path that is only ``loosely based'' on the original path. For
- instance, the |crosses| decoration replaces a path by a path consisting
- of a sequence of crosses. Note how in the following example filling the
- path has no effect since the path consist only of (numerous)
- unconnected straight line subpaths:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
-\tikz \fill [decorate,decoration={crosses}]
- [fill=blue!20,draw=blue,thick] (0,0) -- (2,1) arc (90:-90:.5) -- cycle;
-\end{codeexample}
-
- Examples of path replacing decorations are |crosses| or |ticks| or
- |shape backgrounds|. Such decorations are defined in the library
- |decorations.pathreplacing|, but also in |decorations.shapes|.
- \item \emph{Path removing} decorations completely remove the
- to-be-decorated path. Thus, they have no effect on the main path that
- is being constructed. Instead, they typically have numerous \emph{side
- effects}. For instance, they might ``write some text'' along the
- (removed) path or they might place nodes along this path. Note that for
- such decorations the path usage command for the main path have no
- influence on how the decoration looks like.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\tikz \fill [decorate,decoration={text along path,
- text=This is a text along a path. Note how the path is lost.}]
- [fill=blue!20,draw=blue,thick] (0,0) -- (2,1) arc (90:-90:.5) -- cycle;
-\end{codeexample}
- %
-\end{enumerate}
-
-Decorations are defined in different decoration libraries, see
-Section~\ref{section-library-decorations} for details. It is also possible to
-define your own decorations, see Section~\ref{section-base-decorations}, but
-you need to use the \pgfname\ basic layer and a bit of theory is involved.
-
-Decorations can be used to decorate already decorated paths. In the following
-three graphics, we start with a simple path, then decorate it once, and then
-decorate the decorated path once more.
-%
-\begin{codeexample}[]
-\tikz \fill [fill=blue!20,draw=blue,thick]
- (0,0) rectangle (3,2);
-\end{codeexample}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\tikz \fill [fill=blue!20,draw=blue,thick]
- decorate[decoration={zigzag,segment length=10mm,amplitude=2.5mm}]
- { (0,0) rectangle (3,2) };
-\end{codeexample}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{
- decorations.pathmorphing,
- decorations.shapes,
-}}]
-\tikz \fill [fill=blue!20,draw=blue,thick]
- decorate[decoration={crosses,segment length=2mm}] {
- decorate[decoration={zigzag,segment length=10mm,amplitude=2.5mm}] {
- (0,0) rectangle (3,2)
- }
- };
-\end{codeexample}
-
-One final word of warning: Decorations can be pretty slow to typeset and they
-can be inaccurate. The reason is that \pgfname\ has to a \emph{lot} of rather
-difficult computations in the background and \TeX\ is not very good at doing
-math. Decorations are fastest when applied to straight line segments, but even
-then they are much slower than other alternatives. For instance, the |ticks|
-decoration can be simulated by clever use of a dashing pattern and the dashing
-pattern will literally be thousands of times faster to typeset. However, for
-most decorations there are no real alternatives.
-
-\begin{tikzlibrary}{decorations}
- In order to use decorations, you first have to load a |decorations| library.
- This |decorations| library defines the basic options described in the
- following, but it does not define any new decorations. This is done by
- libraries like |decorations.text|. Since these more specialized libraries
- include the |decorations| library automatically, you usually do not have to
- bother about it.
-\end{tikzlibrary}
-
-
-\subsection{Decorating a Subpath Using the Decorate Path Command}
-
-The most general way to decorate a (sub)path is the following path command.
-
-\begin{pathoperation}{decorate}{\opt{\oarg{options}}\marg{subpath}}
- This path operation causes the \meta{subpath} to be decorated using the
- current decoration. Depending on the decoration, this may or may not extend
- the current path.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \draw decorate [decoration={name=zigzag}]
- { (0,0) .. controls (0,2) and (3,0) .. (3,2) |- (0,0) };
-\end{tikzpicture}
-\end{codeexample}
- %
- The path can include straight lines, curves, rectangles, arcs, circles,
- ellipses, and even already decorated paths (that is, you can nest
- applications of the |decorate| path command, see below).
-
- Due to the limits on the precision in \TeX, some inaccuracies in
- positioning when crossing input segment boundaries may occasionally be
- found.
-
- You can use nodes normally inside the \meta{subpath}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{
- decorations.pathmorphing,
- decorations.shapes,
-}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \draw decorate [decoration={name=zigzag}]
- { (0,0) -- (2,2) node (hi) [left,draw=red] {Hi!} arc(90:0:1)};
-
- \draw [blue] decorate [decoration={crosses}] {(3,0) -- (hi)};
-\end{tikzpicture}
-\end{codeexample}
-
- The following key is used to select the decoration and also to select
- further ``rendering options'' for the decoration.
-
- \begin{key}{/pgf/decoration=\meta{decoration options}}
- \keyalias{tikz}
- This option is used to specify which decoration is used and how it will
- look like. Note that this key will \emph{not} cause any decorations to
- be applied, immediately. It takes the |decorate| path command or the
- |decorate| option to actually decorate a path. The |decoration| option
- is only used to specify which decoration should be used, in principle.
- You can also use this option at the beginning of a picture or a scope
- to specify the decoration to be used with each invocation of the
- |decorate| path command. Naturally, any local options of the |decorate|
- path command override these ``global'' options.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{
- decorations.pathmorphing,
- decorations.shapes,
-}}]
-\begin{tikzpicture}[decoration=zigzag]
- \draw decorate {(0,0) -- (3,2)};
- \draw [red] decorate [decoration=crosses] {(0,2) -- (3,0)};
-\end{tikzpicture}
-\end{codeexample}
-
- The \meta{decoration options} are special options (which have the path
- prefix |/pgf/decoration/|) that determine the properties of the
- decoration. Which options are appropriate for a decoration strongly
- depend on the decoration, you will have to look up the appropriate
- options in the documentation of the decoration, see
- Section~\ref{section-library-decorations}.
-
- There is one option (available only in \tikzname) that is special:
- %
- \begin{key}{/pgf/decoration/name=\meta{name} (initially none)}
- Use this key to set which decoration is to be used. The \meta{name}
- can both be a decoration or a meta-decoration (you need to worry
- about the difference only if you wish to define your own
- decorations).
-
- If you set \meta{name} to |none|, no decorations are added.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \draw decorate [decoration={name=zigzag}]
- { (0,0) .. controls (0,2) and (3,0) .. (3,2) };
-\end{tikzpicture}
-\end{codeexample}
- %
- Since this option is used so often, you can also leave out the
- |name=| part. Thus, the above example can be rewritten more
- succinctly:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- \draw [help lines] grid (3,2);
- \draw decorate [decoration=zigzag]
- { (0,0) .. controls (0,2) and (3,0) .. (3,2) };
-\end{tikzpicture}
-\end{codeexample}
- %
- In general, when \meta{decoration options} are parsed, for each
- unknown key it is checked whether that key happens to be a
- (meta-)decoration and, if so, the |name| option is executed for
- this key.
- \end{key}
-
- Further options allow you to adjust the position of decorations
- relative to the to-be-decorated path. See
- Section~\ref{section-decorations-adjust} below for details.
- \end{key}
-
- Recall that some decorations actually completely remove the to-be-decorated
- path. In such cases, the construction of the main path is resumed after the
- |decorate| path command ends.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}[decoration={text along path,text=
- around and around and around and around we go}]
-
- \draw (0,0) -- (1,1) decorate { -- (2,1) } -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
-
- It is permissible to nest |decorate| commands. In this case, the path
- resulting from the first decoration process is used as the to-be-decorated
- path for the second decoration process. This is especially useful for
- drawing fractals. The |Koch snowflake| decoration replaces a straight line
- like \tikz\draw (0,0) -- (1,0); by
- \tikz[decoration=Koch snowflake] \draw decorate{(0,0) -- (1,0)};.
- Repeatedly applying this transformation to a triangle yields a fractal that
- looks a bit like a snowflake, hence the name.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.fractals}}]
-\begin{tikzpicture}[decoration=Koch snowflake,draw=blue,fill=blue!20,thick]
- \filldraw (0,0) -- ++(60:1) -- ++(-60:1) -- cycle ;
- \filldraw decorate{ (0,-1) -- ++(60:1) -- ++(-60:1) -- cycle };
- \filldraw decorate{ decorate{ (0,-2.5) -- ++(60:1) -- ++(-60:1) -- cycle }};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{pathoperation}
-
-
-\subsection{Decorating a Complete Path}
-
-You may sometimes wish to decorate a path over whose construction you have no
-control. For instance, the path of the background of a node is created without
-having a chance to issue a |decorate| path command. In such cases you can use
-the following option, which allows you to decorate a path ``after the fact''.
-
-\begin{key}{/tikz/decorate=\opt{\meta{boolean}} (default true)}
- When this key is set, the whole path is decorated after it has been
- finished. The decoration used for decorating the path is set via the
- |decoration| way, in exactly the same way as for the |decorate| path
- command. Indeed, the following two commands have the same effect:
- %
- \begin{enumerate}
- \item |\path decorate[|\meta{options}|] {|\meta{path}|};|
- \item |\path [decorate,|\meta{options}|] |\meta{path}|;|
- \end{enumerate}
- %
- The main use or the |decorate| option is the you can also use it with the
- nodes. It then causes the background path of the node to be decorated. Note
- that you can decorate a background path only once in this manner. That is,
- in contrast to the |decorate| path command you cannot apply this option
- twice (this would just set it to |true|, once more).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{
- decorations.pathmorphing,
- decorations.text,
- shapes.geometric,
-}}]
-\begin{tikzpicture}[decoration=zigzag]
- \draw [help lines] (0,0) grid (3,5);
-
- \draw [fill=blue!20,decorate] (1.5,4) circle (1cm);
-
- \node at (1.5,2.5) [fill=red!20,decorate,ellipse] {Ellipse};
-
- \node at (1.5,1) [inner sep=6mm,fill=red!20,decorate,ellipse,decoration=
- {text along path,text={This is getting silly}}] {Ellipse};
-\end{tikzpicture}
-\end{codeexample}
-
- In the last example, the |text along path| decoration removes the path. In
- such cases it is useful to use a pre- or postaction to cause the decoration
- to be applied only before or after the main path has been used.
- Incidentally, this is another application of the |decorate| option that you
- cannot achieve with the decorate path command.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{
- decorations.pathmorphing,
- decorations.text,
- shapes.geometric,
-}}]
-\begin{tikzpicture}[decoration=zigzag]
- \node at (1.5,1) [inner sep=6mm,fill=red!20,ellipse,
- postaction={decorate,decoration=
- {text along path,text={This is getting silly}}}] {Ellipse};
-\end{tikzpicture}
-\end{codeexample}
- %
- Here is more useful example, where a postaction is used to add the path
- after the main path has been drawn.
- %
-% \catcode`\|12 % !?
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
-\begin{tikzpicture}
-\draw [help lines] grid (3,2);
-\fill [draw=red,fill=red!20,
- postaction={decorate,decoration={raise=2pt,text along path,
- text=around and around and around and around we go}}]
- (0,1) arc (180:-180:1.5cm and 1cm);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Adjusting Decorations}
-\label{section-decorations-adjust}
-
-\subsubsection{Positioning Decorations Relative to the To-Be-Decorate Path}
-
-The following option, which are only available with \tikzname, allow you to
-modify the positioning of decorations relative to the to-be-decorated path.
-
-\begin{key}{/pgf/decoration/raise=\meta{dimension} (initially 0pt)}
- The segments of the decoration are raised by \meta{dimension} relative to
- the to-be-decorated path. More precisely, the segments of the path are
- offset by this much ``to the left'' of the path as we travel along the
- path. This raising is done after and in addition to any transformations set
- using the |transform| option (see below).
-
- A negative \meta{dimension} will offset the decoration ``to the right'' of
- the to-be-decorated path.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \draw (0,0) -- (1,1) arc (90:0:2 and 1);
- \draw decorate [decoration=crosses]
- { (0,0) -- (1,1) arc (90:0:2 and 1) };
- \draw[red] decorate [decoration={crosses,raise=5pt}]
- { (0,0) -- (1,1) arc (90:0:2 and 1) };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/decoration/mirror=\opt{\meta{boolean}}}
- Causes the segments of the decoration to be mirrored along the
- to-be-decorated path. This is done after and in addition to any
- transformations set using the |transform| and/or |raise| options.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathreplacing}}]
-\begin{tikzpicture}
- \node (a) {A};
- \node (b) at (2,1) {B};
- \draw (a) -- (b);
- \draw[decorate,decoration=brace] (a) -- (b);
- \draw[decorate,decoration={brace,mirror},red] (a) -- (b);
- \draw[decorate,decoration={brace,mirror,raise=5pt},blue] (a) -- (b);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/decoration/transform=\meta{transformations}}
- This key allows you to specify general \meta{transformations} to be applied
- to the segments of a decoration. These transformations are applied before
- and independently of |raise| and |mirror| transformations. The
- \meta{transformations} should be normal \tikzname\ transformations like
- |shift| or |rotate|.
-
- In the following example the |shift only| transformation is used to make
- sure that the crosses are \emph{not} sloped along the path.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.shapes}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \draw (0,0) -- (1,1) arc (90:0:2 and 1);
- \draw[red,very thick] decorate [decoration={
- crosses,transform={shift only},shape size=1.5mm}]
- { (0,0) -- (1,1) arc (90:0:2 and 1) };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Starting and Ending Decorations Early or Late}
-
-You sometimes may wish to ``end'' a decoration a bit early on the path. For
-instance, you might wish a |snake| decoration to stop 5mm before the end of the
-path and to continue in a straight line. There are different ways of achieving
-this effect, but the easiest may be the |pre| and |post| options, which only
-have an effect in \tikzname. Note, however, that they can only be used with
-decorations, not with meta-decorations.
-
-\begin{key}{/pgf/decoration/pre=\meta{decoration} (initially lineto)}
- This key sets a decoration that should be used before the main decoration
- starts. The \meta{decoration} will be used for a length of |pre length|,
- which |0pt| by default. Thus, for the |pre| option to have any effect, you
- also need to set the |pre length| option.
- %
- % TODO: Nesting tikzpictures is NOT supported
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\tikz [decoration={zigzag,pre=lineto,pre length=1cm}]
- \draw [decorate] (0,0) -- (2,1) arc (90:0:1);
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\tikz [decoration={zigzag,pre=moveto,pre length=1cm}]
- \draw [decorate] (0,0) -- (2,1) arc (90:0:1);
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{
- decorations.pathmorphing,
- decorations.shapes,
-}}]
-\tikz [decoration={zigzag,pre=crosses,pre length=1cm}]
- \draw [decorate] (0,0) -- (2,1) arc (90:0:1);
-\end{codeexample}
-
- Note that the default |pre| option is |lineto|, not |curveto|. This means
- that the default |pre| decoration will not follow curves (for efficiency
- reasons). Change the |pre| key to |curveto| if you have a curved path.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\tikz [decoration={zigzag,pre length=3cm}]
- \draw [decorate] (0,0) -- (2,1) arc (90:0:1);
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\tikz [decoration={zigzag,pre=curveto,pre length=3cm}]
- \draw [decorate] (0,0) -- (2,1) arc (90:0:1);
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/pgf/decoration/pre length=\meta{dimension} (initially 0pt)}
- This key sets the distance along which the pre-decoration should be used.
- If you do not need/wish a pre-decoration, set this key to |0pt| (exactly
- this string, not just to something that evaluates to the same things such
- as |0cm|).
-\end{key}
-
-\begin{key}{/pgf/decorations/post=\meta{decoration} (initially lineto)}
- Works like |pre|, only for the end of the decoration.
-\end{key}
-
-\begin{key}{/pgf/decorations/post length=\meta{dimension} (initially 0pt)}
- Works like |pre length|, only for the end of the decoration.
-\end{key}
-
-Here is a typical example that shows how these keys can be used:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- [decoration=snake,
- line around/.style={decoration={pre length=#1,post length=#1}}]
-
- \draw[->,decorate] (0,0) -- ++(3,0);
- \draw[->,decorate,line around=5pt] (0,-5mm) -- ++(3,0);
- \draw[->,decorate,line around=1cm] (0,-1cm) -- ++(3,0);
-\end{tikzpicture}
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-design.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-design.tex
deleted file mode 100644
index 978b0e665b..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-design.tex
+++ /dev/null
@@ -1,274 +0,0 @@
-% 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{Design Principles}
-
-This section describes the design principles behind the \tikzname\ frontend,
-where \tikzname\ means ``\tikzname\ ist \emph{kein} Zeichenprogramm''. To use
-\tikzname, as a \LaTeX\ user say |\usepackage{tikz}| somewhere in the preamble,
-as a plain \TeX\ user say |\input tikz.tex|. \tikzname's job is to make your
-life easier by providing an easy-to-learn and easy-to-use syntax for describing
-graphics.
-
-The commands and syntax of \tikzname\ were influenced by several sources. The
-basic command names and the notion of path operations is taken from
-\textsc{metafont}, the option mechanism comes from \textsc{pstricks}, the
-notion of styles is reminiscent of \textsc{svg}, the graph syntax is taken from
-\textsc{graphviz}. To make it all work together, some compromises were
-necessary. I also added some ideas of my own, like coordinate transformations.
-
-The following basic design principles underlie \tikzname:
-%
-\begin{enumerate}
- \item Special syntax for specifying points.
- \item Special syntax for path specifications.
- \item Actions on paths.
- \item Key--value syntax for graphic parameters.
- \item Special syntax for nodes.
- \item Special syntax for trees.
- \item Special syntax for graphs.
- \item Grouping of graphic parameters.
- \item Coordinate transformation system.
-\end{enumerate}
-
-
-\subsection{Special Syntax For Specifying Points}
-
-\tikzname\ provides a special syntax for specifying points and coordinates. In
-the simplest case, you provide two \TeX\ dimensions, separated by commas, in
-round brackets as in |(1cm,2pt)|.
-
-You can also specify a point in polar coordinates by using a colon instead of a
-comma as in |(30:1cm)|, which means ``1cm in a 30 degrees direction''.
-
-If you do not provide a unit, as in |(2,1)|, you specify a point in \pgfname's
-$xy$-coordinate system. By default, the unit $x$-vector goes 1cm to the right
-and the unit $y$-vector goes 1cm upward.
-
-By specifying three numbers as in |(1,1,1)| you specify a point in \pgfname's
-$xyz$-coordinate system.
-
-It is also possible to use an anchor of a previously defined shape as in
-|(first node.south)|.
-
-You can add two plus signs before a coordinate as in |++(1cm,0pt)|. This means
-``1cm to the right of the last point used''. This allows you to easily specify
-relative movements. For example, |(1,0) ++(1,0) ++(0,1)| specifies the three
-coordinates |(1,0)|, then |(2,0)|, and |(2,1)|.
-
-Finally, instead of two plus signs, you can also add a single one. This also
-specifies a point in a relative manner, but it does not ``change'' the current
-point used in subsequent relative commands. For example, |(1,0) +(1,0) +(0,1)|
-specifies the three coordinates |(1,0)|, then |(2,0)|, and |(1,1)|.
-
-
-\subsection{Special Syntax For Path Specifications}
-
-When creating a picture using \tikzname, your main job is the specification of
-\emph{paths}. A path is a series of straight or curved lines, which need not be
-connected. \tikzname\ makes it easy to specify paths, partly using the syntax
-of \textsc{metapost}. For example, to specify a triangular path you use
-%
-\begin{codeexample}[code only]
-(5pt,0pt) -- (0pt,0pt) -- (0pt,5pt) -- cycle
-\end{codeexample}
-%
-and you get \tikz \draw (5pt,0pt) -- (0pt,0pt) -- (0pt,5pt) -- cycle; when you
-draw this path.
-
-
-\subsection{Actions on Paths}
-
-A path is just a series of straight and curved lines, but it is not yet
-specified what should happen with it. One can \emph{draw} a path, \emph{fill} a
-path, \emph{shade} it, \emph{clip} it, or do any combination of these. Drawing
-(also known as \emph{stroking}) can be thought of as taking a pen of a certain
-thickness and moving it along the path, thereby drawing on the canvas. Filling
-means that the interior of the path is filled with a uniform color. Obviously,
-filling makes sense only for \emph{closed} paths and a path is automatically
-closed prior to filling, if necessary.
-
-Given a path as in |\path (0,0) rectangle (2ex,1ex);|, you can draw it by
-adding the |draw| option as in |\path[draw] (0,0) rectangle (2ex,1ex);|, which
-yields \tikz \path[draw] (0,0) rectangle (2ex,1ex);. The |\draw| command is
-just an abbreviation for |\path[draw]|. To fill a path, use the |fill| option
-or the |\fill| command, which is an abbreviation for |\path[fill]|. The
-|\filldraw| command is an abbreviation for |\path[fill,draw]|. Shading is
-caused by the |shade| option (there are |\shade| and |\shadedraw|
-abbreviations) and clipping by the |clip| option. There is also a |\clip|
-command, which does the same as |\path[clip]|, but not commands like
-|\drawclip|. Use, say, |\draw[clip]| or |\path[draw,clip]| instead.
-
-All of these commands can only be used inside |{tikzpicture}| environments.
-
-\tikzname\ allows you to use different colors for filling and stroking.
-
-
-\subsection{Key--Value Syntax for Graphic Parameters}
-
-Whenever \tikzname\ draws or fills a path, a large number of graphic parameters
-influences the rendering. Examples include the colors used, the dashing
-pattern, the clipping area, the line width, and many others. In \tikzname, all
-these options are specified as lists of so called key--value pairs, as in
-|color=red|, that are passed as optional parameters to the path drawing and
-filling commands. This usage is similar to \textsc{pstricks}. For example, the
-following will draw a thick, red triangle;
-%
-\begin{codeexample}[]
-\tikz \draw[line width=2pt,color=red] (1,0) -- (0,0) -- (0,1) -- cycle;
-\end{codeexample}
-
-
-\subsection{Special Syntax for Specifying Nodes}
-
-\tikzname\ introduces a special syntax for adding text or, more generally,
-nodes to a graphic. When you specify a path, add nodes as in the following
-example:
-%
-\begin{codeexample}[]
-\tikz \draw (1,1) node {text} -- (2,2);
-\end{codeexample}
-%
-Nodes are inserted at the current position of the path, but either \emph{after}
-(the default) or \emph{before} the complete path is rendered. When special
-options are given, as in |\draw (1,1) node[circle,draw] {text};|, the text is
-not just put at the current position. Rather, it is surrounded by a circle and
-this circle is ``drawn''.
-
-You can add a name to a node for later reference either by using the option
-|name=|\meta{node name} or by stating the node name in parentheses outside the
-text as in |node[circle](name){text}|.
-
-Predefined shapes include |rectangle|, |circle|, and |ellipse|, but it is
-possible (though a bit challenging) to define new shapes.
-
-
-\subsection{Special Syntax for Specifying Trees}
-
-The ``node syntax'' can also be used to draw tress: A |node| can be followed by
-any number of children, each introduced by the keyword |child|. The children
-are nodes themselves, each of which may have children in turn.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node {root}
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-\end{codeexample}
-%
-Since trees are made up from nodes, it is possible to use options to modify the
-way trees are drawn. Here are two examples of the above tree, redrawn with
-different options:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,trees}}]
-\begin{tikzpicture}
- [edge from parent fork down, sibling distance=15mm, level distance=15mm,
- every node/.style={fill=red!30,rounded corners},
- edge from parent/.style={red,-{Circle[open]},thick,draw}]
- \node {root}
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- [parent anchor=east,child anchor=west,grow=east,
- sibling distance=15mm, level distance=15mm,
- every node/.style={ball color=red,circle,text=white},
- edge from parent/.style={draw,dashed,thick,red}]
- \node {root}
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Special Syntax for Graphs}
-
-The |\node| command gives you fine control over where nodes should be placed,
-what text they should use, and what they should look like. However, when you
-draw a graph, you typically need to create numerous fairly similar nodes that
-only differ with respect to the name they show. In these cases, the |graph|
-syntax can be used, which is another syntax layer build ``on top'' of the node
-syntax.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grow down, branch right] {
- root -> { left, right -> {child, child} }
-};
-\end{codeexample}
-%
-The syntax of the |graph| command extends the so-called \textsc{dot}-notation
-used in the popular \textsc{graphviz} program.
-
-Depending on the version of \TeX\ you use (it must allow you to call Lua code,
-which is the case for Lua\TeX), you can also ask \tikzname\ to do automatically
-compute good positions for the nodes of a graph using one of several integrated
-\emph{graph drawing algorithms}.
-
-
-\subsection{Grouping of Graphic Parameters}
-
-Graphic parameters should often apply to several path drawing or filling
-commands. For example, we may wish to draw numerous lines all with the same
-line width of 1pt. For this, we put these commands in a |{scope}| environment
-that takes the desired graphic options as an optional parameter. Naturally, the
-specified graphic parameters apply only to the drawing and filling commands
-inside the environment. Furthermore, nested |{scope}| environments or
-individual drawing commands can override the graphic parameters of outer
-|{scope}| environments. In the following example, three red lines, two green
-lines, and one blue line are drawn:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \begin{scope}[color=red]
- \draw (0mm,10mm) -- (10mm,10mm);
- \draw (0mm, 8mm) -- (10mm, 8mm);
- \draw (0mm, 6mm) -- (10mm, 6mm);
- \end{scope}
- \begin{scope}[color=green]
- \draw (0mm, 4mm) -- (10mm, 4mm);
- \draw (0mm, 2mm) -- (10mm, 2mm);
- \draw[color=blue] (0mm, 0mm) -- (10mm, 0mm);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-The |{tikzpicture}| environment itself also behaves like a |{scope}|
-environment, that is, you can specify graphic parameters using an optional
-argument. These optional apply to all commands in the picture.
-
-
-\subsection{Coordinate Transformation System}
-
-\tikzname\ supports both \pgfname's \emph{coordinate} transformation system to
-perform transformations as well as \emph{canvas} transformations, a more
-low-level transformation system. (For details on the difference between
-coordinate transformations and canvas transformations see
-Section~\ref{section-design-transformations}.)
-
-The syntax is set up in such a way that it is harder to use canvas
-transformations than coordinate transformations. There are two reasons for
-this: First, the canvas transformation must be used with great care and often
-results in ``bad'' graphics with changing line width and text in wrong sizes.
-Second, \pgfname\ loses track of where nodes and shapes are positioned when
-canvas transformations are used. So, in almost all circumstances, you should
-use coordinate transformations rather than canvas transformations.
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-graphs.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-graphs.tex
deleted file mode 100644
index 0135679c6e..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-graphs.tex
+++ /dev/null
@@ -1,3703 +0,0 @@
-% Copyright 2019 by Till Tantau
-% Copyright 2019 by Jannis Pohlmann
-%
-% 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{Specifying Graphs}
-\label{section-library-graphs}
-
-\subsection{Overview}
-
-\tikzname\ offers a powerful path command for specifying how the nodes in a
-graph are connected by edges and arcs: The |graph| path command, which becomes
-available when you load the |graphs| library.
-
-\begin{tikzlibrary}{graphs}
- The package must be loaded to use the |graph| path command.
-\end{tikzlibrary}
-
-In this section, by \emph{graph} we refer to a set of nodes together with some
-edges (sometimes also called arcs, in case they are directed) such as the
-following:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph { a -> {b, c} -> d };
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph {
- subgraph I_nm [V={a, b, c}, W={1,...,4}];
-
- a -> { 1, 2, 3 };
- b -> { 1, 4 };
- c -> { 2 [>green!75!black], 3, 4 [>red]}
-};
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz
- \graph [nodes={draw, circle}, clockwise, radius=.5cm, empty nodes, n=5] {
- subgraph I_n [name=inner] --[complete bipartite]
- subgraph I_n [name=outer]
- };
-\end{codeexample}
-
-\begin{codeexample}[
- preamble={\usetikzlibrary{graphs}},
- pre={\definecolor{graphicbackground}{rgb}{0.96,0.96,0.8}},
-]
-\tikz
- \graph [nodes={draw, circle}, clockwise, radius=.75cm, empty nodes, n=8] {
- subgraph C_n [name=inner] <->[shorten <=1pt, shorten >=1pt]
- subgraph C_n [name=outer]
- };
-\end{codeexample}
-
-\begin{codeexample}[width=6.6cm,preamble={\usetikzlibrary{graphs}}]
-\tikz [>={To[sep]}, rotate=90, xscale=-1,
- mark/.style={fill=black!50}, mark/.default=]
- \graph [trie, simple,
- nodes={circle,draw},
- edges={nodes={
- inner sep=1pt, anchor=mid,
- fill=graphicbackground}}, % yellowish background
- put node text on incoming edges]
- {
- root[mark] -> {
- a -> n -> {
- g [mark],
- f -> a -> n -> g [mark]
- },
- f -> a -> n -> g [mark],
- g[mark],
- n -> {
- g[mark],
- f -> a -> n -> g[mark]
- }
- },
- { [edges=red] % highlight one path
- root -> f -> a -> n
- }
- };
-\end{codeexample}
-
-The nodes of a graph are normal \tikzname\ nodes, the edges are normal lines
-drawn between nodes. There is nothing in the |graphs| library that you cannot
-do using the normal |\node| and the |edge| commands. Rather, its purpose is to
-offer a concise and powerful way of \emph{specifying} which nodes are present
-and how they are connected. The |graphs| library only offers simple methods for
-specifying \emph{where} the nodes should be shown, its main strength is in
-specifying which nodes and edges are present in principle. The problem of
-finding ``good positions on the canvas'' for the nodes of a graph is left to
-\emph{graph drawing algorithms}, which are covered in Part~\ref{part-gd} of
-this manual and which are not part of the |graphs| library; indeed, these
-algorithms can be used also with graphs specified using |node| and |edge|
-commands.
-%
-\ifluatex
-As an example, consider the above drawing of a trie, which is drawn without
-using the graph drawing libraries. Its layout can be somewhat improved by
-loading the |layered| graph drawing library, saying |\tikz[layered layout,...|,
-and then using Lua\TeX, resulting in the following drawing of the same graph:
-\medskip
-
-\tikz [layered layout, >={To[sep]}, rotate=90, xscale=-1,
- mark/.style={fill=black!50}, mark/.default=]
- \graph [trie, simple, sibling distance=8mm,
- nodes={circle,draw},
- edges={nodes={
- inner sep=1pt, anchor=mid, fill=white}},
- put node text on incoming edges]
- {
- root[mark] -> {
- a -> n -> {
- g [mark],
- f -> a -> n -> g [mark]
- },
- f -> a -> n -> g [mark],
- g[mark],
- n -> {
- g[mark],
- f -> a -> n -> g[mark]
- }
- },
- { [edges=red] % highlight one path
- root -> f -> a -> n
- }
- };
-\medskip
-\fi
-
-The |graphs| library uses a syntax that is quite different from the normal
-\tikzname\ syntax for specifying nodes. The reason for this is that for many
-medium-sized graphs it can become quite cumbersome to specify all the nodes
-using |\node| repeatedly and then using a great number of |edge| command;
-possibly with complicated |\foreach| statements. Instead, the syntax of the
-|graphs| library is loosely inspired by the \textsc{dot} format, which is quite
-useful for specifying medium-sized graphs, with some extensions on top.
-
-
-\subsection{Concepts}
-
-The present section aims at giving a quick overview of the main concepts behind
-the |graph| command. The exact syntax is explained in more detail in later
-sections.
-
-
-\subsubsection{Concept: Node Chains}
-
-The basic way of specifying a graph is to write down a \emph{node chain} as in
-the following example:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz [every node/.style = draw]
- \graph { foo -> bar -> blub };
-\end{codeexample}
-
-As can be seen, the text |foo -> bar -> blub| creates three nodes, one with
-the text |foo|, one with |bar| and one with the text |blub|. These nodes are
-connected by arrows, which are caused by the |->| between the node texts. Such
-a sequence of node texts and arrows between them is called a \emph{chain} in
-the following.
-
-Inside a graph there can be more than one chain:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- a -> b -> c;
- d -> e -> f;
- g -> f;
-};
-\end{codeexample}
-
-Multiple chains are separated by a semicolon or a comma (both have exactly the
-same effect). As the example shows, when a node text is seen for the second
-time, instead of creating a new node, a connection is created to the already
-existing node.
-
-When a node like |f| is created, both the node name and the node text are
-identical by default. This is not always desirable and can be changed by using
-the |as| key or by providing another text after a slash:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- x1/$x_1$ -> x2 [as=$x_2$, red] -> x34/{$x_3,x_4$};
- x1 -> [bend left] x34;
-};
-\end{codeexample}
-
-When you wish to use a node name that contains special symbols like commas or
-dashes, you must surround the node name by quotes. This allows you to use quite
-arbitrary text as a ``node name'':
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- "$x_1$" -> "$x_2$"[red] -> "$x_3,x_4$";
- "$x_1$" ->[bend left] "$x_3,x_4$";
-};
-\end{codeexample}
-
-
-\subsubsection{Concept: Chain Groups}
-
-Multiple chains that are separated by a semicolon or a comma and that are
-surrounded by curly braces form what will be called a \emph{chain group} or
-just a \emph{group}. A group in itself has no special effect. However, things
-get interesting when you write down a node or even a whole group and connect it
-to another group. In this case, the ``exit points'' of the first node or group
-get connected to the ``entry points'' of the second node or group:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- a -> {
- b -> c,
- d -> e
- } -> f
-};
-\end{codeexample}
-
-Chain groups make it easy to create tree structures:
-%
-\begin{codeexample}[width=10cm,preamble={\usetikzlibrary{graphs}}]
-\tikz
- \graph [grow down,
- branch right=2.5cm] {
- root -> {
- child 1,
- child 2 -> {
- grand child 1,
- grand child 2
- },
- child 3 -> {
- grand child 3
- }
- }
-};
-\end{codeexample}
-
-As can be seen, the placement is not particularly nice by default, use the
-algorithms from the graph drawing libraries to get a better layout. For
-instance, adding |tree layout| to the above code (and
-|\usetikzlibrary{graphdrawing}| as well as |\usegdlibrary{trees}| to the
-preamble) results in the following somewhat more pleasing rendering:
-%
-\ifluatex
-\medskip
-
-\tikz \graph [grow down, branch right=2.5cm, tree layout] {
- root -> {
- child 1,
- child 2 -> {
- grand child 1,
- grand child 2
- },
- child 3 -> {
- grand child 3
- }
- }
-};
-\else
- (You need to use Lua\TeX\ to typeset this graphic.)
-\fi
-
-
-\subsubsection{Concept: Edge Labels and Styles}
-
-When connectors like |->| or |--| are used to connect nodes or whole chain
-groups, one or more edges will typically be created. These edges can be styled
-easily by providing options in square brackets directly after these connectors:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- a ->[red] b --[thick] {c, d};
-};
-\end{codeexample}
-
-Using the quotes syntax, see Section~\ref{section-label-quotes}, you can even
-add labels to the edges easily by putting the labels in quotes:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz \graph {
- a ->[red, "foo"] b --[thick, "bar"] {c, d};
-};
-\end{codeexample}
-
-For the first edge, the effect is as desired, however between |b| and the group
-|{c,d}| two edges are inserted and the options |thick| and the label option
-|"bar"| is applied to both of them. While this is the correct and consistent
-behavior, we typically might wish to specify different labels for the edge
-going from |b| to |c| and the edge going from |b| to |d|. To achieve this
-effect, we can no longer specify the label as part of the options of |--|.
-Rather, we must pass the desired label to the nodes |c| and |d|, but we must
-somehow also indicate that these options actually ``belong'' to the edge
-``leading'' to nodes. This is achieved by preceding the options with a
-greater-than sign:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz \graph {
- a -> b -- {c [> "foo"], d [> "bar"']};
-};
-\end{codeexample}
-
-Symmetrically, preceding the options by |<| causes the options and labels to
-apply to the ``outgoing'' edges of the node:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz \graph {
- a [< red] -> b -- {c [> blue], d [> "bar"']};
-};
-\end{codeexample}
-
-This syntax allows you to easily create trees with special edge labels as in
-the following example of a treap:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz
- \graph [edge quotes={fill=white,inner sep=1pt},
- grow down, branch right, nodes={circle,draw}] {
- "" -> h [>"9"] -> {
- c [>"4"] -> {
- a [>"2"],
- e [>"0"]
- },
- j [>"7"]
- }
- };
-\end{codeexample}
-
-
-\subsubsection{Concept: Node Sets}
-
-When you write down some node text inside a |graph| command, a new node is
-created by default unless this node has already been created inside the same
-|graph| command. In particular, if a node has already been declared outside of
-the current |graph| command, a new node of the same name gets created.
-
-This is not always the desired behavior. Often, you may wish to make nodes part
-of a graph than have already been defined prior to the use of the |graph|
-command. For this, simply surround a node name by parentheses. This will cause
-a reference to be created to an already existing node:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz {
- \node (a) at (0,0) {A};
- \node (b) at (1,0) {B};
- \node (c) at (2,0) {C};
-
- \graph { (a) -> (b) -> (c) };
-}
-\end{codeexample}
-
-You can even go a step further: A whole collection of nodes can all be flagged
-to belong to a \emph{node set} by adding the option |set=|\meta{node set name}.
-Then, inside a |graph| command, you can collectively refer to these nodes by
-surrounding the node set name in parentheses:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,shapes.geometric}}]
-\tikz [new set=my nodes] {
- \node [set=my nodes, circle, draw] at (1,1) {A};
- \node [set=my nodes, rectangle, draw] at (1.5,0) {B};
- \node [set=my nodes, diamond, draw] at (1,-1) {C};
- \node (d) [star, draw] at (3,0) {D};
-
- \graph { X -> (my nodes) -> (d) };
-}
-\end{codeexample}
-
-
-\subsubsection{Concept: Graph Macros}
-
-Often, a graph will consist -- at least in parts -- of standard parts. For
-instance, a graph might contain a cycle of certain size or a path or a clique.
-To facilitate specifying such graphs, you can define a \emph{graph macro}. Once
-a graph macro has been defined, you can use the name of the graph to make a
-copy of the graph part of the graph currently being specified:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph { subgraph K_n [n=6, clockwise] };
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph { subgraph C_n [n=5, clockwise] -> mid };
-\end{codeexample}
-
-The library |graphs.standard| defines a number of such graphs, including the
-complete clique $K_n$ on $n$ nodes, the complete bipartite graph $K_{n,m}$ with
-shores sized $n$ and $m$, the cycle $C_n$ on $n$ nodes, the path $P_n$ on $n$
-nodes, and the independent set $I_n$ on $n$ nodes.
-
-
-\subsubsection{Concept: Graph Expressions and Color Classes}
-
-When a graph is being constructed using the |graph| command, it is constructed
-recursively by uniting smaller graphs to larger graphs. During this recursive
-union process the nodes of the graph get implicitly \emph{colored}
-(conceptually) and you can also explicitly assign colors to individual nodes
-and even change the colors as the graph is being specified. All nodes having
-the same color form what is called a \emph{color class}.
-
-The power of color class is that special \emph{connector operators} allow you
-to add edges between nodes having certain colors. For instance, saying
-|clique=red| at the beginning of a group will cause all nodes that have been
-flagged as being (conceptually) ``red'' to be connected as a clique. Similarly,
-saying |complete bipartite={red}{green}| will cause edges to be added between
-all red and all green nodes. More advanced connectors, like the |butterfly|
-connector, allow you to add edges between color classes in a fancy manner.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz [x=8mm, y=6mm, circle]
- \graph [nodes={fill=blue!70}, empty nodes, n=8] {
- subgraph I_n [name=A] --[butterfly={level=4}]
- subgraph I_n [name=B] --[butterfly={level=2}]
- subgraph I_n [name=C] --[butterfly]
- subgraph I_n [name=D] --
- subgraph I_n [name=E]
- };
-\end{codeexample}
-
-
-\subsection{Syntax of the Graph Path Command}
-
-\subsubsection{The Graph Command}
-
-In order to construct a graph, you should use the |graph| path command, which
-can be used anywhere on a path at any place where you could also use a command
-like, say, |plot| or |--|.
-
-\begin{command}{\graph}
- Inside a |{tikzpicture}| this is an abbreviation for |\path graph|.
-\end{command}
-
-\begin{pathoperation}{graph}{\opt{\oarg{options}}\meta{group specification}}
- When this command is encountered on a path, the construction of the current
- path is suspended (similarly to an |edge| command or a |node| command). In
- a local scope, the \meta{options} are first executed with the key path
- |/tikz/graphs| using the following command:
- %
- \begin{command}{\tikzgraphsset\marg{options}}
- Executes the \meta{options} with the path prefix |/tikz/graphs|.
- \end{command}
- %
- Apart from the keys explained in the following, further permissible keys
- will be listed during the course of the rest of this section.
-
- \begin{stylekey}{/tikz/graphs/every graph}
- This style is executed at the beginning of every |graph| path command
- prior to the \meta{options}.
- \end{stylekey}
-
- Once the scope has been set up and once the \meta{options} have been
- executed, a parser starts to parse the \meta{group specification}. The
- exact syntax of such a group specification in explained in detail in
- Section~\ref{section-library-graphs-group-spec}. Basically, a group
- specification is a list of chain specifications, separated by commas or
- semicolons.
-
- Depending on the content of the \meta{group specification}, two things will
- happen:
- %
- \begin{enumerate}
- \item A number of new nodes may be created. These will be inserted into
- the picture in the same order as if they had been created using
- multiple |node| path commands at the place where the |graph| path
- command was used. In other words, all nodes created in a |graph|
- path command will be painted on top of any nodes created earlier in
- the path and behind any nodes created later in the path. Like
- normal nodes, the newly created nodes always lie on top of the path
- that is currently being created (which is often empty, for instance
- when the |\graph| command is used).
- \item Edges between the nodes may be added. They are added in the same
- order as if the |edge| command had been used at the position where
- the |graph| command is being used.
- \end{enumerate}
-
- Let us now have a look at some common keys that may be used inside the
- \meta{options}:
- %
- \begin{key}{/tikz/graphs/nodes=\meta{options}}
- This option causes the \meta{options} to be applied to each newly
- created node inside the \meta{group specification}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [nodes=red] { a -> b -> c };
-\end{codeexample}
- %
- Multiple uses of this key accumulate.
- \end{key}
- %
- \begin{key}{/tikz/graphs/edges=\meta{options}}
- This option causes the \meta{options} to be applied to each newly
- created edge inside the \meta{group specification}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [edges={red,thick}] { a -> b -> c };
-\end{codeexample}
- %
- Again, multiple uses of this key accumulate.
- \end{key}
- %
- \begin{key}{/tikz/graphs/edge=\meta{options}}
- This is an alias for |edges|.
- \end{key}
-
- \begin{key}{/tikz/graphs/edge node=\meta{node specification}}
- This key specifies that the \meta{node specification} should be added
- to each newly created edge as an implicitly placed node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [edge node={node [red, near end] {X}}] { a -> b -> c };
-\end{codeexample}
- %
- Again, multiple uses of this key accumulate.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [edge node={node [near end] {X}},
- edge node={node [near start] {Y}}] { a -> b -> c };
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/graphs/edge label=\meta{text}}
- This key is an abbreviation for |edge node=node[auto]{|\meta{text}|}|.
- The net effect is that the |text| is placed next to the newly created
- edges.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [edge label=x] { a -> b -> {c,d} };
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/graphs/edge label'=\meta{text}}
- This key is an abbreviation for |edge node=node[auto,swap]{|\meta{text}|}|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [edge label=out, edge label'=in]
- { subgraph C_n [clockwise, n=5] };
-\end{codeexample}
- \end{key}
-\end{pathoperation}
-
-
-\subsubsection{Syntax of Group Specifications}
-\label{section-library-graphs-group-spec}
-
-A \meta{group specification} inside a |graph| path command has the following
-syntax:
-%
-\begin{quote}
- |{|\opt{\oarg{options}}\meta{list of chain specifications}|}|
-\end{quote}
-%
-The \meta{chain specifications} must contain chain specifications, whose syntax
-is detailed in the next section, separated by either commas or semicolons; you
-can freely mix them. It is permissible to use empty lines (which are mapped to
-|\par| commands internally) to structure the chains visually, they are simply
-ignored by the parser.
-
-In the following example, the group specification consists of three chain
-specifications, namely of |a -> b|, then |c| alone, and finally |d -> e -> f|:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- a -> b,
- c;
-
- d -> e -> f
-};
-\end{codeexample}
-%
-The above has the same effect as the more compact group specification
-|{a->b,c,d->e->f}|.
-
-Commas are used to detect where chain specifications end. However, you will
-often wish to use a comma also inside the options of a single node like in the
-following example:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- a [red, draw] -> b [blue, draw],
- c [brown, draw, circle]
-};
-\end{codeexample}
-
-Note that the above example works as expected: The first comma inside the
-option list of |a| is \emph{not} interpreted as the end of the chain
-specification ``|a [red|''. Rather, commas inside square brackets are
-``protected'' against being interpreted as separators of group specifications.
-
-The \meta{options} that can be given at the beginning of a group specification
-are local to the group. They are executed with the path prefix |/tikz/graphs|.
-Note that for the outermost group specification of a graph it makes no
-difference whether the options are passed to the |graph| command or whether
-they are given at the beginning of this group. However, for groups nested
-inside other groups, it does make a difference:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- a -> { [nodes=red] % the option is local to these nodes:
- b, c
- } ->
- d
-};
-\end{codeexample}
-
-\medskip
-\textbf{Using foreach.}
-There is special support for the |\foreach| statement inside groups: You may
-use the statement inside a group specification at any place where a \meta{chain
-specification} would normally go. In this case, the |\foreach| statement is
-executed and for each iteration the content of the statement's body is treated
-and parsed as a new chain specification.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [math nodes, branch down=5mm] {
- a -> {
- \foreach \i in {1,2,3} {
- a_\i -> { x_\i, y_\i }
- },
- b
- }
-};
-\end{codeexample}
-
-\medskip
-\textbf{Using macros.}
-In some cases you may wish to use macros and \TeX\ code to compute which nodes
-and edges are present in a group. You cannot use macros in the normal way
-inside a graph specification since the parser does not expand macros as it
-scans for the start and end of groups and node names. Rather, only after
-commas, semicolons, and hyphens have already been detected and only after all
-other parsing decisions have been made will macros be expanded. At this point,
-when a macro expands to, say |a,b|, this will not result in two nodes to be
-created since the parsing is already done. For these reasons, a special key is
-needed to make it possible to ``compute'' which nodes should be present in a
-group.
-
-\begin{key}{/tikz/graph/parse=\meta{text}}
- This key can only be used inside the \meta{options} of a \meta{group
- specification}. Its effect is that the \meta{text} is inserted at the
- beginning of the current group as if you had entered it there. Naturally,
- it makes little sense to just write down some static \meta{text} since you
- could just as well directly place it at the beginning of the group. The
- real power of this command stems from the fact that the keys mechanism
- allows you to say, for instance, |parse/.expand once| to insert the text
- stored in some macro into the group.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\def\mychain{ a -> b -> c; }
-\tikz \graph { [parse/.expand once=\mychain] d -> e };
-\end{codeexample}
- %
- In the following, more fancy example we use a loop to create a chain of
- dynamic length.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\def\mychain#1{
- \def\mytext{1}
- \foreach \i in {2,...,#1} {
- \xdef\mytext{\mytext -> \i}
- }
-}
-\tikzgraphsset{my chain/.style={
- /utils/exec=\mychain{#1},
- parse/.expand once=\mytext}
-}
-\tikz \graph { [my chain=4] };
-\end{codeexample}
- %
- Multiple uses of this key accumulate, that is, all the \text{text}s given
- in the different uses is inserted in the order it is given.
-\end{key}
-
-
-\subsubsection{Syntax of Chain Specifications}
-
-A \meta{chain specification} has the following syntax: It consists of a
-sequence of \meta{node specifications}, where subsequent node specifications
-are separated by \meta{edge specifications}. Node specifications, which
-typically consist of some text, are discussed in the next section in more
-detail. They normally represent a single node that is either newly created or
-exists already, but they may also specify a whole set of nodes.
-
-An \meta{edge specification} specifies \emph{which} of the node(s) to the left
-of the edge specification should be connected to which node(s) to the right of
-it and it also specifies in which direction the connections go. In the
-following, we only discuss how the direction is chosen, the powerful mechanism
-behind choosing which nodes should be connect is detailed in
-Section~\ref{section-library-graphs-color-classes}.
-
-The syntax of an edge specification is always one of the following five
-possibilities:
-%
-\begin{quote}
- |->| \opt{\oarg{options}}\\
- |--| \opt{\oarg{options}}\\
- |<-| \opt{\oarg{options}}\\
- |<->| \opt{\oarg{options}}\\
- |-!-| \opt{\oarg{options}}
-\end{quote}
-
-The first four correspond to a directed edge, an undirected edge, a
-``backward'' directed edge, and a bidirected edge, respectively. The fifth edge
-specification means that there should be no edge (this specification can be
-used together with the |simple| option to remove edges that have previously
-been added, see Section~\ref{section-library-graphs-simple}).
-
-Suppose the nodes \meta{left nodes} are to the left of the \meta{edge
-specification} and \meta{right nodes} are to the right and suppose we have
-written |->| between them. Then the following happens:
-%
-\begin{enumerate}
- \item The \meta{options} are executed (inside a local scope) with the path
- |/tikz/graphs|. These options may setup the connector algorithm (see
- below) and may also use keys like |edge| or |edge label| to specify how
- the edge should look like. As a convenience, whenever an unknown key is
- encountered for the path |/tikz/graphs|, the key is passed to the
- |edge| key. This means that you can directly use options like |thick|
- or |red| inside the \meta{options} and they will apply to the edge as
- expected.
- \item The chosen connector algorithm, see
- Section~\ref{section-library-graphs-color-classes}, is used to compute
- from which of the \meta{left nodes} an edge should lead to which of the
- \meta{right nodes}. Suppose that $(l_1,r_1)$, \dots, $(l_n,r_n)$ is the
- list of node pairs that result (so there should be an edge between
- $l_1$ and $r_1$ and another edge between $l_2$ and $r_2$ and so on).
- \item For each pair $(l_i,r_i)$ an edge is created. This is done by calling
- the following key (for the edge specification |->|, other keys are
- executed for the other kinds of specifications):
- %
- \begin{key}{/tikz/graphs/new ->=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
- This key will be called for a |->| edge specification with the
- following four parameters:
- %
- \begin{enumerate}
- \item \meta{left node} is the name of the ``left'' node, that
- is, the name of $l_i$.
- \item \meta{right node} is the name of the right node.
- \item \meta{edge options} are the accumulated options from all
- calls of |/tikz/graph/edges| in groups that surround the
- edge specification.
- \item \meta{edge nodes} is text like |node {A} node {B}| that
- specifies some nodes that should be put as labels on the
- edge using \tikzname's implicit positioning mechanism.
- \end{enumerate}
- %
- By default, the key executes the following code:
- %
- \begin{quote}
- |\path [->,every new ->]|\\
- \hbox{}\quad|(|\meta{left node}|\tikzgraphleftanchor) edge [|%
- \meta{edge options}|]| \meta{edge nodes}||\\
- \hbox{}\quad|(|\meta{right node}|\tikzgraphrightanchor);|
- \end{quote}
- %
- You are welcome to change the code underlying the key.
- %
- \begin{stylekey}{/tikz/every new ->}
- This key gets executed by default for a |new ->|.
- \end{stylekey}
- \end{key}
- %
- \begin{key}{/tikz/graphs/left anchor=\meta{anchor}}
- This anchor is used for the node that is to the left of an edge
- specification. Setting this anchor to the empty string means that
- no special anchor is used (which is the default). The \meta{anchor}
- is stored in the macro |\tikzgraphleftanchor| with a leading dot.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- {a,b,c} -> [complete bipartite] {e,f,g}
-};
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [left anchor=east, right anchor=west] {
- {a,b,c} -- [complete bipartite] {e,f,g}
-};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/graphs/right anchor=\meta{anchor}}
- Works like |left anchor|, only for |\tikzgraphrightanchor|.
- \end{key}
- %
- For the other three kinds of edge specifications, the following keys
- will be called:
- %
- \begin{key}{/tikz/graphs/new --=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
- This key is called for |--| with the same parameters as above. The
- only difference in the definition is that in the |\path| command
- the |->| gets replaced by |-|.
- %
- \begin{stylekey}{/tikz/every new --}
- \end{stylekey}
- \end{key}
- %
- \begin{key}{/tikz/graphs/new <->=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
- Called for |<->| with the same parameters as above. The |->| is
- replaced by |<-|
- %
- \begin{stylekey}{/tikz/every new <->}
- \end{stylekey}
- \end{key}
- %
- \begin{key}{/tikz/graphs/new <-=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
- Called for |<-| with the same parameters as above.%
- \footnote{%
- You might wonder why this key is needed: It seems more logical
- at first sight to just call |new edge directed| with swapped
- first parameters. However, a positioning algorithm might wish
- to take the fact into account that an edge is ``backward''
- rather than ``forward'' in order to improve the layout. Also,
- different arrow heads might be used.
- }
- %
- \begin{stylekey}{/tikz/every new <-}
- \end{stylekey}
- \end{key}
- %
- \begin{key}{/tikz/graphs/new -\protect\exclamationmarktext-=\marg{left node}\marg{right node}\marg{edge options}\marg{edge nodes}}
- Called for |-!-| with the same parameters as above. Does nothing by
- default.
- \end{key}
-\end{enumerate}
-
-Here is an example that shows the default rendering of the different edge
-specifications:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [branch down=5mm] {
- a -> b;
- c -- d;
- e <- f;
- g <-> h;
- i -!- j;
-};
-\end{codeexample}
-
-
-\subsubsection{Syntax of Node Specifications}
-\label{section-library-graphs-node-spec}
-
-Node specifications are the basic building blocks of a graph specification.
-There are three different possible kinds of node specifications, each of which
-has a different syntax:
-%
-\begin{description}
- \item[Direct Node Specification]
- \ \\
- \opt{|"|}\meta{node name}\opt{|"|}\opt{|/|\opt{|"|}\meta{text}\opt{|"|}} \opt{\oarg{options}}\\
- (note that the quotation marks are optional and only needed when the
- \meta{node name} contains special symbols)
- \item[Reference Node Specification]
- \ \\
- |(|\meta{node name or node set name}|)|
- \item[Group Node Specification]
- \ \\
- \meta{group specification}
-\end{description}
-
-The rule for determining which of the possible kinds is meant is as follows: If
-the node specification starts with an opening parenthesis, a reference node
-specification is meant; if it starts with an opening curly brace, a group
-specification is meant; and in all other cases a direct node specification is
-meant.
-
-\medskip
-\textbf{Direct Node Specifications.} If after reading the first symbol of a
-node specification is has been detected to be \emph{direct}, \tikzname\ will
-collect all text up to the next edge specification and store it as the
-\meta{node name}; however, square brackets are used to indicate options and a
-slash ends the \meta{node name} and start a special \meta{text} that is used as
-a rendering text instead of the original \meta{node name}.
-
-Due to the way the parsing works and due to the restrictions on node names,
-most special characters are forbidding inside the \meta{node name}, including
-commas, semicolons, hyphens, braces, dots, parentheses, slashes, dashes, and
-more (but spaces, single underscores, and the hat character \emph{are}
-allowed). To use special characters in the name of a node, you can optionally
-surround the \meta{node name} and/or the \meta{text} by quotation marks. In
-this case, you can use all of the special symbols once more. The details of
-what happens, exactly, when the \meta{node name} is surrounded by quotation
-marks is explained later; surrounding the \meta{text} by quotation marks has
-essentially the same effect as surrounding it by curly braces.
-
-Once the node name has been determined, it is checked whether the same node
-name was already used inside the current graph. If this is the case, then we
-say that the already existing node is \emph{referenced}; otherwise we say that
-the node is \emph{fresh}.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- a -> b; % both are fresh
- c -> a; % only c is fresh, a is referenced
-};
-\end{codeexample}
-
-This behavior of deciding whether a node is fresh or referenced can, however,
-be modified by using the following keys:
-%
-\begin{key}{/tikz/graphs/use existing nodes=\opt{\meta{true or false}} (default true)}
- When this key is set to |true|, all nodes will be considered to the
- referenced, no node will be fresh. This option is useful if you have
- already created all the nodes of a graph prior to using the |graph| command
- and you now only wish to connect the nodes. It also implies that an error
- is raised if you reference a node which has not been defined previously.
-\end{key}
-
-\begin{key}{/tikz/graphs/fresh nodes=\opt{\meta{true or false}} (default true)}
- When this key is set to |true|, all nodes will be considered to be fresh.
- This option is useful when you create for instance a tree with many
- identical nodes.
-
- When a node name is encountered that was already used previously, a new
- name is chosen is follows: An apostrophe (|'|) is appended repeatedly until
- a node name is found that has not yet been used:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [branch down=5mm] {
- { [fresh nodes]
- a -> {
- b -> {c, c},
- b -> {c, c},
- b -> {c, c},
- }
- },
- b' -- b''
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/number nodes=\opt{\meta{start number}} (default 1)}
- When this key is used in a scope, each encountered node name will get
- appended a new number, starting with \meta{start}. Typically, this ensures
- that all node names are different. Between the original node name and the
- appended number, the setting of the following will be inserted:
- %
- \begin{key}{/tikz/graphs/number nodes sep=\meta{text} (initially \normalfont space)}
- \end{key}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [branch down=5mm] {
- { [number nodes]
- a -> {
- b -> {c, c},
- b -> {c, c},
- b -> {c, c},
- }
- },
- b 2 -- b 5
-};
-\end{codeexample}
- %
-\end{key}
-
-When a fresh node has been detected, a new node is created in the inside a
-protecting scope. For this, the current placement strategy is asked to compute
-a default position for the node, see
-Section~\ref{section-library-graphs-placement} for details. Then, the command
-%
-\begin{quote}
- |\node (|\meta{full node name}|) [|\meta{node options}|] {|\meta{text}|};|
-\end{quote}
-%
-is called. The different parameters are as follows:
-%
-\begin{itemize}
- \item The \meta{full node name} is normally the \meta{node name} that has
- been determined as described before. However, there are two exceptions:
-
- First, if the \meta{node name} is empty (which happens when there is no
- \meta{node name} before the slash), then a fresh internal node name is
- created and used as \meta{full node name}. This name is guaranteed to
- be different from all node names used in this or any other graph. Thus,
- a direct node starting with a slash represents an anonymous fresh node.
-
- Second, you can use the following key to prefix the \meta{node name}
- inside the \meta{full node name}:
-
- \begin{key}{/tikz/graphs/name=\meta{text}}
- This key prepends the \meta{text}, followed by a separating symbol
- (a space by default), to all \meta{node name}s inside a \meta{full
- node name}. Repeated calls of this key accumulate, leading to
- ever-longer ``name paths'':
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\begin{tikzpicture}
- \graph {
- { [name=first] 1, 2, 3} --
- { [name=second] 1, 2, 3}
- };
- \draw [red] (second 1) circle [radius=3mm];
-\end{tikzpicture}
-\end{codeexample}
- %
- Note that, indeed, in the above example six nodes are created even
- though the first and second set of nodes have the same \meta{node
- name}. The reason is that the full names of the six nodes are all
- different. Also note that only the \meta{node name} is used as the
- node text, not the full name. This can be changed as described
- later on.
-
- This key can be used repeatedly, leading to ever longer node names.
- \end{key}
-
- \begin{key}{/tikz/graphs/name separator=\meta{symbols} (initially \string\space)}
- Changes the symbol that is used to separate the \meta{text} from
- the \meta{node name}. The default is |\space|, resulting in a
- space.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\begin{tikzpicture}
- \graph [name separator=] { % no separator
- { [name=first] 1, 2, 3} --
- { [name=second] 1, 2, 3}
- };
- \draw [red] (second1) circle [radius=3mm];
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\begin{tikzpicture}
- \graph [name separator=-] {
- { [name=first] 1, 2, 3} --
- { [name=second] 1, 2, 3}
- };
- \draw [red] (second-1) circle [radius=3mm];
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- \item The \meta{node options} are
- %
- \begin{enumerate}
- \item The options that have accumulated in calls to |nodes| from
- the surrounding scopes.
- \item The local \meta{options}.
- \end{enumerate}
- %
- The options are executed with the path prefix |/tikz/graphs|, but any
- unknown key is executed with the prefix |/tikz|. This means, in
- essence, that some esoteric keys are more difficult to use inside the
- options and that any key with the prefix |/tikz/graphs| will take
- precedence over a key with the prefix |/tikz|.
- \item The \meta{text} that is passed to the |\node| command is computed as
- follows: First, you can use the following key to directly set the
- \meta{text}:
- %
- \begin{key}{/tikz/graphs/as=\meta{text}}
- The \meta{text} is used as the text of the node. This allows you to
- provide a text for the node that differs arbitrarily from the name
- of the node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph { a [as=$x$] -- b [as=$y_5$] -> c [red, as={a--b}] };
-\end{codeexample}
- %
- This key always takes precedence over all of the mechanisms
- described below.
- \end{key}
- %
- In case the |as| key is not used, a default text is chosen as follows:
- First, when a direct node specification contains a slash (or, for
- historical reasons, a double underscore), the text to the right of the
- slash (or double underscore) is stored in the macro
- |\tikzgraphnodetext|; if there is no slash, the \meta{node name} is
- stored in |\tikzgraphnodetext|, instead. Then, the current value of the
- following key is used as \meta{text}:
- %
- \begin{key}{/tikz/graphs/typeset=\meta{code}}
- The macro or code stored in this key is used as the \meta{text} of
- the node. Inside the \meta{code}, the following macros are
- available:
- %
- \begin{command}{\tikzgraphnodetext}
- This macro expands to the \meta{text} to the right of the
- double underscore or slash in a direct node specification or,
- if there is no slash, to the \meta{node name}.
- \end{command}
- %
- \begin{command}{\tikzgraphnodename}
- This macro expands to the name of the current node without the
- path.
- \end{command}
- %
- \begin{command}{\tikzgraphnodepath}
- This macro expands to the current path of the node. These paths
- result from the use of the |name| key as described above.
- \end{command}
- %
- \begin{command}{\tikzgraphnodefullname}
- This macro contains the concatenation of the above two.
- \end{command}
- \end{key}
- %
- By default, the typesetter is just set to |\tikzgraphnodetext|, which
- means that the default text of a node is its name. However, it may be
- useful to change this: For instance, you might wish that the text of
- all graph nodes is, say, surrounded by parentheses:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [typeset=(\tikzgraphnodetext)]
- { a -> b -> c };
-\end{codeexample}
- %
- A more advanced macro might take apart the node text and render it
- differently:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\def\mytypesetter{\expandafter\myparser\tikzgraphnodetext\relax}
-\def\myparser#1 #2 #3\relax{%
- $#1_{#2,\dots,#3}$
-}
-\tikz \graph [typeset=\mytypesetter, grow down]
- { a 1 n -> b 2 m -> c 4 nm };
-\end{codeexample}
- %
- The following styles install useful predefined typesetting macros:
- %
- \begin{key}{/tikz/graphs/empty nodes}
- Just sets |typeset| to nothing, which causes all nodes to have an
- empty text (unless, of course, the |as| option is used):
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [empty nodes, nodes={circle, draw}] { a -> {b, c} };
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/graphs/math nodes}
- Sets |typeset| to |$\tikzgraphnodetext$|, which causes all nodes
- names to be typeset in math mode:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [math nodes, nodes={circle, draw}] { a_1 -> {b^2, c_3^n} };
-\end{codeexample}
- \end{key}
-\end{itemize}
-
-If a node is referenced instead of fresh, then this node becomes the node that
-will be connected by the preceding or following edge specification to other
-nodes. The \meta{options} are executed even for a referenced node, but they
-cannot be used to change the appearance of the node (because the node exists
-already). Rather, the \meta{options} can only be used to change the logical
-coloring of the node, see Section~\ref{section-library-graphs-color-classes}
-for details.
-
-\medskip
-\textbf{Quoted Node Names.} When the \meta{node name} and/or the \meta{text} of
-a node is surrounded by quotation marks, you can use all sorts of special
-symbols as part of the text that are normally forbidden:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\begin{tikzpicture}
- \graph [grow right=2cm] {
- "Hi, World!" -> "It's \emph{important}!"[red,rotate=-45];
- "name"/actual text -> "It's \emph{important}!";
- };
- \draw (name) circle [radius=3pt];
-\end{tikzpicture}
-\end{codeexample}
-
-In detail, for the following happens when quotation marks are encountered at
-the beginning of a node name or its text:
-%
-\begin{itemize}
- \item Everything following the quotation mark up to the next single
- quotation mark is collected into a macro \meta{collected}. All sorts of
- special characters, including commas, square brackets, dashes, and even
- backslashes are allowed here. Basically, the only restriction is that
- braces must be balanced.
- \item A double quotation mark (|""|) does not count as the ``next single
- quotation mark''. Rather, it is replaced by a single quotation mark.
- For instance, |"He said, ""Hello world."""| would be stored inside
- \meta{collected} as |He said, "Hello world."| However, this rule
- applies only on the outer-most level of braces. Thus, in
- %
-\begin{codeexample}[code only]
-"He {said, ""Hello world.""}"
-\end{codeexample}
- %
- we would get |He {said, ""Hello world.""}| as \meta{collected}.
- \item ``The next single quotation mark'' refers to the next quotation mark
- on the current level of braces, so in |"hello {"} world"|, the next
- quotation mark would be the one following |world|.
-\end{itemize}
-
-Now, once the \meta{collected} text has been gather, it is used as follows:
-When used as \meta{text} (what is actually displayed), it is just used ``as
-is''. When it is used as \meta{node name}, however, the following happens:
-Every ``special character'' in \meta{collected} is replaced by its Unicode
-name, surrounded by |@|-signs. For instance, if \meta{collected} is
-|Hello, world!|, the \meta{node name} is the somewhat longer text
-|Hello@COMMA@ world@EXCLAMATION MARK@|. Admittedly, referencing such a node
-from outside the graph is cumbersome, but when you use exactly the same
-\meta{collected} text once more, the same \meta{node name} will result. The
-following characters are considered ``special'':
-%
-\begin{quote}
- \texttt{\char`\|}|$&^~_[](){}/.-,+*'`!":;<=>?@#%\{}|%$
-\end{quote}
-%
-These are exactly the Unicode character with a decimal code number between 33
-and 126 that are neither digits nor letters.
-
-\medskip
-\textbf{Reference Node Specifications.} A reference node specification is a
-node specification that starts with an opening parenthesis. In this case,
-parentheses must surround a \meta{name} as in |(foo)|, where |foo| is the
-\meta{name}. The following will now happen:
-%
-\begin{enumerate}
- \item It is tested whether \meta{name} is the name of a currently active
- \emph{node set}. This case will be discussed in a moment.
- \item Otherwise, the \meta{name} is interpreted and treated as a referenced
- node, but independently of whether the node has already been fresh in
- the current graph or not. In other words, the node must have been
- defined either already inside the graph (in which case the parenthesis
- are more or less superfluous) or it must have been defined outside the
- current picture.
-
- The way the referenced node is handled is the same way as for a direct
- node that is a referenced node.
-
- If the node does not already exist, an error message is printed.
-\end{enumerate}
-
-Let us now have a look at node sets. Inside a |{tikzpicture}| you can locally
-define a \emph{node set} by using the following key:
-%
-\begin{key}{/tikz/new set=\meta{set name}}
- This will setup a node set named \meta{set name} within the current scope.
- Inside the scope, you can add nodes to the node set using the |set| key. If
- a node set of the same name already exists in the current scope, it will be
- reset and made empty for the current scope.
-
- Note that this command has the path |/tikz| and is normally used
- \emph{outside} the |graph| command.
-\end{key}
-%
-\begin{key}{/tikz/set=\meta{set name}}
- This key can be used as an option with a |node| command. The \meta{set
- name} must be the name of a node set that has previously been created
- inside some enclosing scope via the |new set| key. The effect is that the
- current node is added to the node set.
-\end{key}
-
-When you use a |graph| command inside a scope where some node set called
-\meta{set name} is defined, then inside this |graph| command you use
-|(|\meta{set name}|)| to reference \emph{all} of the nodes in the node set. The
-effect is the same as if instead of the reference to the set name you had
-created a group specification containing a list of references to all the nodes
-that are part of the node set.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\begin{tikzpicture}[new set=red, new set=green, shorten >=2pt]
- \foreach \i in {1,2,3} {
- \node [draw, red!80, set=red] (r\i) at (\i,1) {$r_\i$};
- \node [draw, green!50!black, set=green] (g\i) at (\i,2) {$g_\i$};
- }
- \graph {
- root [xshift=2cm] ->
- (red) -> [complete bipartite, right anchor=south]
- (green)
- };
-\end{tikzpicture}
-\end{codeexample}
-
-There is an interesting caveat with referencing node sets: Suppose that at the
-beginning of a graph you just say |(foo);| where |foo| is a set name. Unless
-you have specified special options, this will cause the following to happen: A
-group is created whose members are all the nodes of the node set |foo|. These
-nodes become referenced nodes, but otherwise nothing happens since, by default,
-the nodes of a group are not connected automatically. However, the referenced
-nodes have now been referenced inside the graph, you can thus subsequently
-access them as if they had been defined inside the graph. Here is an example
-showing how you can create nodes outside a |graph| command and then connect
-them inside as if they had been declared inside:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\begin{tikzpicture}[new set=import nodes]
- \begin{scope}[nodes={set=import nodes}] % make all nodes part of this set
- \node [red] (a) at (0,1) {$a$};
- \node [red] (b) at (1,1) {$b$};
- \node [red] (d) at (2,1) {$d$};
- \end{scope}
-
- \graph {
- (import nodes); % "import" the nodes
-
- a -> b -> c -> d -> e; % only c and e are new
- };
-\end{tikzpicture}
-\end{codeexample}
-
-\medskip
-\textbf{Group Node Specifications.} At a place where a node specification
-should go, you can also instead provide a group specification. Since nodes
-specifications are part of chain specifications, which in turn are part of
-group specifications, this is a recursive definition.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph { a -> {b,c,d} -> {e -> {f,g}, h} };
-\end{codeexample}
-
-As can be seen in the above example, when two groups of nodes are connected via
-an edge specification, it is not immediately obvious which connecting edges are
-added. This is detailed in Section~\ref{section-library-graphs-color-classes}.
-
-
-\subsubsection{Specifying Tries}
-
-In computer science, a \emph{trie} is a special kind of tree, where for each
-node and each symbol of an alphabet, there is at most one child of the node
-labeled with this symbol.
-
-The |trie| key is useful for drawing tries, but it can also be used in other
-situations. What it does, essentially, is to prepend the node names of all
-nodes \emph{before} the current node of the current chain to the node's name.
-This will often make it easier or more natural to specify graphs in which
-several nodes have the same label.
-
-\begin{key}{/tikz/graphs/trie=\opt{\meta{true or false}} (default true, initially false)}
- If this key is set to |true|, after a node has been created on a chain, the
- |name| key is executed with the node's \meta{node name}. Thus, all nodes
- later on this chain have the ``path'' of nodes leading to this node as
- their name. This means, in particular, that
- %
- \begin{enumerate}
- \item two nodes of the same name but in different parts of a chain will
- be different,
- \item while if another chain starts with the same nodes, no new nodes
- get created.
- \end{enumerate}
- %
- In total, this is exactly the behavior you would expect of a trie:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [trie] {
- a -> {
- a,
- c -> {a, b},
- b
- }
-};
-\end{codeexample}
- %
- You can even ``reiterate'' over a path in conjunction with the |simple|
- option. However, in this case, the default placement strategies will not
- work and you will need options like |layered layout| from the graph drawing
- libraries, which need Lua\TeX.
- %
-\ifluatex
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}\usegdlibrary{layered}}]
-\tikz \graph [trie, simple, layered layout] {
- a -> b -> a,
- a -> b -> c,
- a -> {d,a}
-};
-\end{codeexample}
- %
- In the following example, we setup the |typeset| key so that it shows the
- complete names of the nodes:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,graphdrawing}\usegdlibrary{layered}}]
-\tikz \graph [trie, simple, layered layout,
- typeset=\tikzgraphnodefullname] {
- a -> b -> a,
- a -> b -> c,
- a -> {d,a}
-};
-\end{codeexample}
-\fi
- %
- You can also use the |trie| key locally and later reference nodes using
- their full name:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- { [trie, simple]
- a -> {
- b,
- c -> a
- }
- },
- a b ->[red] a c a
-};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Quick Graphs}
-\label{section-library-graphs-quick}
-
-The graph syntax is powerful, but this power comes at a price: parsing the
-graph syntax, which is done by \TeX, can take some time. Normally, the parsing
-is fast enough that you will not notice it, but it can be bothersome when you
-have graphs with hundreds of nodes as happens frequently when nodes are
-generated algorithmically by some other program. Fortunately, when another
-program generated a graph specification, we typically do not need the full
-power of the graph syntax. Rather, a small subset of the graph syntax would
-suffice that allows to specify nodes and edges. For these reasons, the is a
-special ``quick'' version of the graph syntax.
-
-Note, however, that using this syntax will usually at most halve the time
-needed to parse a graph. Thus, it really mostly makes sense in conjunction with
-large, algorithmically generated graphs.
-
-\begin{key}{/tikz/graphs/quick}
- When you provide this key with a graph, the syntax of graph specifications
- gets restricted. You are no longer allowed to use certain features of the
- graph syntax; but all features that are still allowed are also allowed in
- the same way when you do not provide the |quick| option. Thus, leaving out
- the |quick| option will never hurt.
-
- Since the syntax is so severely restricted, it is easier to explain which
- aspects of the graph syntax \emph{will} still work:
- %
- \begin{enumerate}
- \item A quick graph consists of a sequence of either nodes, edges
- sequences, or groups. These are separated by commas or semicolons.
- \item Every node is of the form
- %
- \begin{quote}
- |"|\meta{node name}|"|\opt{|/"|\meta{node text}|"[|\meta{options}|]|}
- \end{quote}
-
- The quotation marks are mandatory. The part |/"|\meta{node text}|"|
- may be missing, in which case the node name is used as the node
- text. The \meta{options} may also be missing. The \meta{node name}
- may not contain any ``funny'' characters (unlike in the normal
- graph command).
- \item Every chain is of the form
- %
- \begin{quote}
- \meta{node spec} \meta{connector} \meta{node spec}
- \meta{connector} \dots \meta{connector} \meta{node spec}|;|
- \end{quote}
-
- Here, the \meta{node spec} are node specifications as described
- above, the \meta{connector} is one of the four connectors |->|,
- |<-|, |--|, and |<->| (the connector |-!-| is not allowed since the
- |simple| option is also not allowed). Each connector may be
- followed by options in square brackets. The semicolon may be
- replaced by a comma.
- \item Every group is of the form
- %
- \begin{quote}
- |{ [|\meta{options}|]| \meta{chains and groups} |};|
- \end{quote}
- %
- The \meta{options} are compulsory. The semicolon can, again, be
- replaced by a comma.
- \item The |number nodes| option will work as expected.
- \end{enumerate}
-
- Here is a typical way this syntax might be used:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz \graph [quick] { "a" --["foo"] "b"[x=1] };
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [quick] {
- "a"/"$a$" -- "b"[x=1] --[red] "c"[x=2];
- { [nodes=blue] "a" -- "d"[y=1]; };
-};
-\end{codeexample}
-
- Let us now have a look at the most important things that will \emph{not}
- work when the |quick| option is used:
-
- \begin{itemize}
- \item Connecting a node and a group as in |a->{b,c}|.
- \item Node names without quotation marks as in |a--b|.
- \item Everything described in subsequent subsections, which includes
- subgraphs (graph macros), graph sets, graph color classes,
- anonymous nodes, the |fresh nodes| option, sublayouts, simple
- graphs, edge annotations.
- \item Placement strategies -- you either have to define all node
- positions explicitly using |at=| or |x=| and |y=| or you must use a
- graph drawing algorithm like |layered layout|.
- \end{itemize}
-\end{key}
-
-
-\subsection{Simple Versus Multi-Graphs}
-\label{section-library-graphs-simple}
-
-The |graphs| library allows you to construct both simple graphs and
-multi-graphs. In a simple graph there can be at most one edge between any two
-vertices, while in a multi-graph there can be multiple edges (hence the name).
-The two keys |multi| and |simple| allow you to switch (even locally inside on
-of the graph's scopes) between which kind of graph is being constructed. By
-default, the |graph| command produces a multi-graph since these are faster to
-construct.
-
-\begin{key}{/tikz/graphs/multi}
- When this edge is set for a whole graph (which is the default) or just for
- a group (which is useful if the whole graph is simple in general, but a
- part is a multi-graph), then when you specify an edge between two nodes
- several times, several such edges get created:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [multi] { % "multi" is not really necessary here
- a ->[bend left, red] b;
- a ->[bend right, blue] b;
-};
-\end{codeexample}
- %
- In case |multi| is used for a scope inside a larger scope where the
- |simple| option is specified, then inside the local |multi| scope edges are
- immediately created and they are completely ignored when it comes to
- deciding which kind of edges should be present in the surrounding simple
- graph. From the surrounding scope's point of view it is as if the local
- |multi| graph contained no edges at all.
-
- This means, in particular, that you can use the |multi| option with a
- single edge to ``enforce'' this edge to be present in a simple graph.
-\end{key}
-
-\begin{key}{/tikz/graphs/simple}
- In contrast a multi-graph, in a simple graph, at most one edge gets created
- for every pair of vertices:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [simple]{
- a ->[bend left, red] b;
- a ->[bend right, blue] b;
-};
-\end{codeexample}
- %
- As can be seen, the second edge ``wins'' over the first edge. The general
- rule is as follows: In a simple graph, whenever an edge between two
- vertices is specified multiple times, only the very last specification and
- its options will actually be executed.
-
- The real power of the |simple| option lies in the fact that you can first
- create a complicated graph and then later redirect and otherwise modify
- edges easily:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [simple, grow right=2cm] {
- {a,b,c,d} ->[complete bipartite] {e,f,g,h};
-
- { [edges={red,thick}] a -> e -> d -> g -> a };
-};
-\end{codeexample}
-
- One particularly interesting kind of edge specification for a simple graph
- is |-!-|. Recall that this is used to indicate that ``no edge'' should be
- added between certain nodes. In a multi-graph, this key usually has no
- effect (unless the key |new -!-| has been redefined) and is pretty
- superfluous. In a simple graph, however, it counts as an edge kind and you
- can thus use it to remove an edge that been added previously:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [simple] {
- subgraph K_n [n=8, clockwise];
- % Get rid of the following edges:
- 1 -!- 2;
- 3 -!- 4;
- 6 -!- 8;
- % And make one edge red:
- 1 --[red] 3;
-};
-\end{codeexample}
-
- Creating a graph such as the above in other fashions is pretty awkward.
-
- For every unordered pair $\{u,v\}$ of vertices at most one edge will be
- created in a simple graph. In particular, when you say |a -> b| and later
- also |a <- b|, then only the edge |a <- b| will be created. Similarly, when
- you say |a -> b| and later |b -> a|, then only the edge |b -> a| will be
- created.
-
- The power of the |simple| command comes at a certain cost: As the graph is
- being constructed, a (sparse) array is created that keeps track for each
- edge of the last edge being specified. Then, at the end of the scope
- containing the |simple| command, for every pair of vertices the edge is
- created. This is implemented by two nested loops iterating over all
- possible pairs of vertices -- which may take quite a while in a graph of,
- say, 1000 vertices. Internally, the |simple| command is implemented as an
- operator that adds the edges when it is called, but this should be
- unimportant in normal situations.
-\end{key}
-
-
-\subsection{Graph Edges: Labeling and Styling}
-
-When the |graphs| library creates an edge between two nodes in a graph, the
-appearance (called ``styling'' in \tikzname) can be specified in different
-ways. Sometimes you will simply wish to say ``the edges between these two
-groups of node should be red'', but sometimes you may wish to say ``this
-particular edge going into this node should be red''. In the following,
-different ways of specifying such styling requirements are discussed. Note that
-adding labels to edges is, from \tikzname's point of view, almost the same as
-styling edges, since they are also specified using options.
-
-
-\subsubsection{Options For All Edges Between Two Groups}
-
-When you write |... ->[options] ...| somewhere inside your graph specification,
-this typically cause one or more edges to be created between the nodes in the
-chain group before the |->| and the nodes in the chain group following it. The
-|options| are applied to all of them. In particular, if you use the |quotes|
-library and you write some text in quotes inside the |options|, this text will
-be added as a label to each edge:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz
- \graph [edge quotes=near start] {
- { a, b } -> [red, "x", complete bipartite] { c, d };
- };
-\end{codeexample}
-
-As documented in the |quotes| library in more detail, you can easily modify the
-appearance of edge labels created using the quotes syntax by adding options
-after the closing quotes:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz \graph {
- a ->["x"] b ->["y"'] c ->["z" red] d;
-};
-\end{codeexample}
-
-The following options make it easy to setup the styling of nodes created in
-this way:
-%
-\begin{key}{/tikz/graphs/edge quotes=\opt{\meta{options}}}
- A shorthand for setting the style |every edge quotes| to \meta{options}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
- \tikz \graph [edge quotes={blue,auto}] {
- a ->["x"] b ->["y"'] c ->["b" red] d;
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/edge quotes center}
- A shorthand for |edge quotes| to |anchor=center|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz \graph [edge quotes center] {
- a ->["x"] b ->["y"] c ->["z" red] d;
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/edge quotes mid}
- A shorthand for |edge quotes| to |anchor=mid|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz \graph [edge quotes mid] {
- a ->["x"] b ->["y"] c ->["z" red] d;
-};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Changing Options For Certain Edges}
-
-Consider the following tree-like graph:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph { a -> {b,c} };
-\end{codeexample}
-
-Suppose we wish to specify that the edge from |a| to |b| should be red, while
-the edge from |a| to |c| should be blue. The difficulty lies in the fact that
-\emph{both} edges are created by the single |->| operator and we can only add
-one of these option |red| or |blue| to the operator.
-
-There are several ways to solve this problem. First, we can simply split up the
-specification and specify the two edges separately:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- a -> [red] b;
- a -> [blue] c;
-};
-\end{codeexample}
-%
-While this works quite well, we can no longer use the nice chain group syntax
-of the |graphs| library. For the rather simple graph |a->{b,c}| this is not a
-big problem, but if you specify a tree with, say, 30 nodes it is really
-worthwhile being able to specify the tree ``in its natural form in the \TeX\
-code'' rather than having to list all of the edges explicitly. Also, as can be
-seen in the above example, the node placement is changed, which is not always
-desirable.
-
-One can sidestep this problem using the |simple| option: This option allows you
-to first specify a graph and then, later on, replace edges by other edges and,
-thereby, provide new options:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [simple] {
- a -> {b,c};
- a -> [red] b;
- a -> [blue] c;
-};
-\end{codeexample}
-
-The first line is the original specification of the tree, while the following
-two lines replace some edges of the tree (in this case, all of them) by edges
-with special options. While this method is slower and in the above example
-creates even longer code, it is very useful if you wish to, say, highlight a
-path in a larger tree: First specify the tree normally and, then, ``respecify''
-the path or paths with some other edge options in force. In the following
-example, we use this to highlight a whole subtree of a larger tree:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [simple] {
- % The larger tree, no special options in force
- a -> {
- b -> {c,d},
- e -> {f,g},
- h
- },
- { [edges=red] % Now highlight a part of the tree
- a -> e -> {f,g}
- }
-};
-\end{codeexample}
-
-
-\subsubsection{Options For Incoming and Outgoing Edges}
-
-When you use the syntax |... ->[options] ...| to specify options, you specify
-options for the ``connections between two sets of nodes''. In many cases,
-however, it will be more natural to specify options ``for the edges lead to or
-coming from a certain node'' and you will want to specify these options ``at
-the node''. Returning to the example of the graph |a->{b,c}| where we want a
-red edge between |a| and |b| and a blue edge between |a| and |c|, this could
-also be phrased as follows: ``Make the edge leading to |b| red and make the
-edge leading to |c| blue''.
-
-For this situation, the |graphs| library offers a number of special keys, which
-are documented in the following. However, most of the time you will not use
-these keys directly, but, rather, use a special syntax explained in
-Section~\ref{section-syntax-outgoing-incoming}.
-
-\begin{key}{/tikz/graphs/target edge style=\meta{options}}
- This key can (only) be used with a \emph{node} inside a graph
- specification. When used, the \meta{options} will be added to every edge
- that is created by a connector like |->| in which the node is a
- \emph{target}. Consider the following example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- { a, b } ->
- { c [target edge style=red], d } ->
- { e, f }
-};
-\end{codeexample}
- %
- In the example, only when the edge from |a| to |c| is created, |c| is the
- ``target'' of the edge. Thus, only this edge becomes red.
-
- When an edge already has options set directly, the \meta{options} are
- executed after these direct options, thus, they ``overrule'' them:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- { a, b } -> [blue, thick]
- { c [target edge style=red], d } ->
- { e, f }
-};
-\end{codeexample}
-
- The \meta{options} set in this way will stay attached to the node, so also
- for edges created later on that lead to the node will have these options
- set:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- { a, b } ->
- { c [target edge style=red], d } ->
- { e, f },
- b -> c
-};
-\end{codeexample}
-
- Multiple uses of this key accumulate. However, you may sometimes also wish
- to ``clear'' these options for a key since at some later point you no
- longer wish the \meta{options} to be added when some further edges are
- added. This can be achieved using the following key:
- %
- \begin{key}{/tikz/graphs/target edge clear}
- Clears all \meta{options} for edges with the node as a target and
- also edge labels (see below) for this node.
- \end{key}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- { a, b } ->
- { c [target edge style=red], d },
- b -> c[target edge clear]
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/target edge node=\meta{node specification}}
- This key works like |target edge style|, only the \meta{node specification}
- will not be added as options to any newly created edges with the current
- node as their target, but rather it will be added as a node specification.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- { a, b } ->
- { c [target edge node=node{X}], d } ->
- { e, f }
-};
-\end{codeexample}
- %
- As for |target edge style| multiple uses of this key accumulate and the key
- |target edge clear| will (also) clear all target edge nodes that have been
- set for a node earlier on.
-\end{key}
-
-\begin{key}{/tikz/graphs/source edge style=\meta{options}}
- Works exactly like |target edge style|, only now the \meta{options} are
- only added when the node is a source of a newly created edge:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- { a, b } ->
- { c [source edge style=red], d } ->
- { e, f }
-};
-\end{codeexample}
- %
- If both for the source and also for the target of an edge \meta{options}
- have been specified, the options are applied in the following order:
- %
- \begin{enumerate}
- \item First come the options from the edge itself.
- \item Then come the options contributed by the source node using this
- key.
- \item Then come the options contributed by the target node using
- |target node style|.
- \end{enumerate}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- a [source edge style=red] ->[green]
- b [target edge style=blue] % blue wins
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/source edge node=\meta{node specification}}
- Works like |source edge style| and |target edge node|.
-\end{key}
-
-\begin{key}{/tikz/graphs/source edge clear=\meta{node specification}}
- Works like |target edge clear|.
-\end{key}
-
-
-\subsubsection{Special Syntax for Options For Incoming and Outgoing Edges}
-\label{section-syntax-outgoing-incoming}
-
-The keys |target node style| and its friends are powerful, but a bit cumbersome
-to write down. For this reason, the |graphs| library introduces a special
-syntax that is based on what I call the ``first-char syntax'' of keys. Inside
-the options of a node inside a graph, the following special rules apply:
-%
-\begin{enumerate}
- \item Whenever an option starts with |>|, the rest of the options are
- passed to |target edge style|. For instance, when you write |a[>red]|,
- then this has the same effect as if you had written
- %
-\begin{codeexample}[code only]
-a[target edge style={red}]
-\end{codeexample}
- %
- \item Whenever an options starts with |<|, the rest of the options are
- passed to |source edge style|.
- \item In both of the above case, in case the options following the |>| or
- |<| sign start with a quote, the created edge label is passed to
- |source edge node| or |target edge node|, respectively.
-
- This is exactly what you want to happen.
-\end{enumerate}
-%
-Additionally, the following styles provide shorthands for ``clearing'' the
-target and source options:
-%
-\begin{key}{/tikz/graphs/clear >}
- A more easy-to-remember shorthand for |target edge clear|.
-\end{key}
-%
-\begin{key}{/tikz/graphs/clear <}
- A more easy-to-remember shorthand for |source edge clear|.
-\end{key}
-
-These mechanisms make it especially easy to create trees in which the edges are
-labeled in some special way:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz
- \graph [edge quotes={fill=white,inner sep=1pt},
- grow down, branch right] {
- / -> h [>"9"] -> {
- c [>"4" text=red,] -> {
- a [>"2", >thick],
- e [>"0"]
- },
- j [>"7"]
- }
- };
-\end{codeexample}
-
-
-\subsubsection{Placing Node Texts on Incoming Edges}
-
-Normally, the text of a node is shown (only) inside the node. In some case, for
-instance when drawing certain kind of trees, the nodes themselves should not
-get any text, but rather the edge leading to the node should be labeled as in
-the following example:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,quotes}}]
-\tikz \graph [empty nodes]
-{
- root -> {
- a [>"a"],
- b [>"b"] -> {
- c [>"c"],
- d [>"d"]
- }
- }
-};
-\end{codeexample}
-%
-As the example shows, it is a bit cumbersome that we have to label the nodes
-and then specify the same text once more using the incoming edge syntax.
-
-For these cases, it would be better if the text of the node where not used with
-the node but, rather, be passed directly to the incoming or the outgoing edge.
-The following styles do exactly this:
-
-\begin{key}{/tikz/graphs/put node text on incoming edges=\opt{\meta{options}}}
- When this key is used with a node or a group, the following happens:
- %
- \begin{enumerate}
- \item The command
- |target edge node={node[|\meta{options}|]{\tikzgraphnodetext}}| is
- executed. This means that all incoming edges of the node get a
- label with the text that would usually be displayed in the node.
- You can use keys like |math nodes| normally.
- \item The command |as={}| is executed. This means that the node itself
- will display nothing.
- \end{enumerate}
- %
- Here is an example that show how this command is used.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [put node text on incoming edges,
- math nodes, nodes={circle,draw}]
- { a -> b -> {c, d} };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/put node text on outgoing edges=\opt{\meta{options}}}
- Works like the previous key, only with |target| replaced by |source|.
-\end{key}
-
-
-\subsection{Graph Operators, Color Classes, and Graph Expressions}
-\label{section-library-graphs-color-classes}
-
-\tikzname's |graph| command employs a powerful mechanism for adding edges
-between nodes and sets of nodes. To a graph theorist, this mechanism may be
-known as a \emph{graph expression}: A graph is specified by starting with small
-graphs and then applying \emph{operators} to them that form larger graphs and
-that connect and recolor colored subsets of the graph's node in different ways.
-
-
-\subsubsection{Color Classes}
-\label{section-library-graph-coloring}
-
-\tikzname\ keeps track of a \emph{(multi)coloring} of the graph as it is being
-constructed. This does not mean that the actual color of the nodes on the page
-will be different, rather, in the following we refer to ``logical'' colors in
-the way graph theoreticians do. These ``logical'' colors are only important
-while the graph is being constructed and they are ``thrown away'' at the end of
-the construction. The actual (``physical'') colors of the nodes are set
-independently of these logical colors.
-
-As a graph is being constructed, each node can be part of one or more
-overlapping \emph{color classes}. So, unlike what is sometimes called a
-\emph{legal coloring}, the logical colorings that \tikzname\ keeps track of may
-assign multiple colors to the same node and two nodes connected by an edge may
-well have the same color.
-
-Color classes must be declared prior to use. This is done using the following
-key:
-%
-\begin{key}{/tikz/graphs/color class=\meta{color class name}}
- This sets up a new color class called \meta{color class name}. Nodes and
- whole groups of nodes can now be colored with \meta{color class name}. This
- is done using the following keys, which become
- available inside the current scope:
- %
- \begin{key}{/tikz/graphs/\meta{color class name}}
- This key internally uses the |operator| command to setup an operator
- that will cause all nodes of the current group to get the ``logical
- color'' \meta{color class name}. Nodes retain this color in all
- encompassing scopes, unless it is explicitly changed (see below) or
- unset (again, see below).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [color class=red] {
- [cycle=red] % causes all "logically" red nodes to be connected in
- % a cycle
- a,
- b [red],
- { [red] c ->[bend right] d },
- e
-};
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [color class=red, color class=green,
- math nodes, clockwise, n=5] {
- [complete bipartite={red}{green}]
- { [red] r_1, r_2 },
- { [green] g_1, g_2, g_3 }
-};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/graphs/not \meta{color class name}}
- Sets up an operator for the current scope so that all nodes in it loose
- the color \meta{color class name}. You can also use |!|\meta{color
- class name} as an alias for this key.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [color class=red, color class=green,
- math nodes, clockwise, n=5] {
- [complete bipartite={red}{green}]
- { [red] r_1, r_2 },
- { [green] g_1, g_2, g_3 },
- g_2 [not green]
-};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/graphs/recolor \meta{color class name} by=\meta{new color}}
- Causes all keys having color \meta{color class name} to get \meta{new
- color} instead. They loose having color \meta{color class name}, but
- other colors are not affected.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [color class=red, color class=green,
- math nodes, clockwise, n=5] {
- [complete bipartite={red}{green}]
- { [red] r_1, r_2 },
- { [green] g_1, g_2, g_3 },
- g_2 [recolor green by=red]
-};
-\end{codeexample}
- \end{key}
-\end{key}
-
-The following color classes are available by default:
-%
-\begin{itemize}
- \item Color class |all|. Every node is part of this class by default. This
- is useful to access all nodes of a (sub)graph, since you can simply
- access all nodes of this color class.
- \item Color classes |source| and |target|. These classes are used to
- identify nodes that lead ``into'' a group of nodes and nodes from which
- paths should ``leave'' the group. Details on how these colors are
- assigned are explained in Section~\ref{section-library-graphs-join}. By
- saying |not source| or |not target| with a node, you can influence how
- it is connected:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph { a -> { b, c, d } -> e };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph { a -> { b[not source], c, d[not target] } -> e };
-\end{codeexample}
- %
- \item Color classes |source'| and |target'|. These are temporary colors
- that are also explained in Section~\ref{section-library-graphs-join}.
-\end{itemize}
-
-
-\subsubsection{Graph Operators on Groups of Nodes}
-
-Recall that the |graph| command constructs graphs recursively from nested
-\meta{group specifications}. Each such \meta{group specification} describes a
-subset of the nodes of the final graph. A \emph{graph operator} is an algorithm
-that gets the nodes of a group as input and (typically) adds edges between
-these nodes in some sensible way. For instance, the |clique| operator will
-simply add edges between all nodes of the group.
-
-\begin{key}{/tikz/graphs/operator=\meta{code}}
- This key has an effect in three places:
- %
- \begin{enumerate}
- \item It can be used in the \meta{options} of a \meta{direct node
- specification}.
- \item It can be used in the \meta{options} of a \meta{group
- specification}.
- \item It can be used in the \meta{options} of an \meta{edge
- specification}.
- \end{enumerate}
- %
- The first case is a special case of the second, since it is treated like a
- group specification containing a single node. The last case is more
- complicated and discussed in the next section. So, let us focus on the
- second case.
-
- Even though the \meta{options} of a group are given at the beginning of the
- \meta{group specification}, the \meta{code} is only executed when the group
- has been parsed completely and all its nodes have been identified. If you
- use the |operator| multiple times in the \meta{options}, the effect
- accumulates, that is, all code passed to the different calls of |operator|
- gets executed in the order it is encountered.
-
- The \meta{code} can do ``whatever it wants'', but it will typically add
- edges between certain nodes. You can configure what kind of edges
- (directed, undirected, etc.) are created by using the following keys:
- %
- \begin{key}{/tikz/graphs/default edge kind=\meta{value} (initially -\/-)}
- This key stores one of the five edge kinds |--|, |<-|, |->|, |<->|, and
- |-!-|. When an operator wishes to create a new edge, it should
- typically set
- %
-\begin{codeexample}[code only]
-\tikzgraphsset{new \pfkeysvalueof{/tikz/graphs/default edge kind}=...}
-\end{codeexample}
- %
- While this key can be set explicitly, it may be more convenient to use
- the abbreviating keys listed below. Also, this key is automatically set
- to the current value of \meta{edge specification} when a joining
- operator is called, see the discussion of joining operators in
- Section~\ref{section-library-graphs-join}.
- \end{key}
- %
- \begin{key}{/tikz/graphs/--}
- Sets the |default edge kind| to |--|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph { subgraph K_n [--, n=5, clockwise, radius=6mm] };
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/graphs/->}
- Sets the |default edge kind| to |->|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph { subgraph K_n [->, n=5, clockwise, radius=6mm] };
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/graphs/<-}
- Sets the |default edge kind| to |<-|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph { subgraph K_n [<-, n=5, clockwise, radius=6mm] };
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/graphs/<->}
- Sets the |default edge kind| to |<->|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph { subgraph K_n [<->, n=5, clockwise, radius=6mm] };
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/graphs/-\protect\exclamationmarktext-}
- Sets the |default edge kind| to |-!-|.
- \end{key}
-
- When the \meta{code} of an operator is executed, the following commands can
- be used to find the nodes that should be connected:
- %
- \begin{command}{\tikzgraphforeachcolorednode\marg{color name}\marg{macro}}
- When this command is called inside \meta{code}, the following will
- happen: \tikzname\ will iterate over all nodes inside the
- just-specified group that have the color \meta{color name}. The order
- in which they are iterated over is the order in which they appear
- inside the group specification (if a node is encountered several times
- inside the specification, only the first occurrence counts). Then, for
- each node the \meta{macro} is executed with the node's name as the only
- argument.
-
- In the following example we use an operator to connect every node
- colored |all| inside the subgroup to he node |root|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\def\myconnect#1{\tikzset{graphs/new ->={root}{#1}{}{}}}
-
-\begin{tikzpicture}
- \node (root) at (-1,-1) {root};
-
- \graph {
- x,
- {
- [operator=\tikzgraphforeachcolorednode{all}{\myconnect}]
- a, b, c
- }
- };
-\end{tikzpicture}
-\end{codeexample}
- \end{command}
-
- \begin{command}{\tikzgraphpreparecolor\marg{color name}\marg{counter}\marg{prefix}}
- This command is used to ``prepare'' the nodes of a certain color for
- random access. The effect is the following: It is counted how many
- nodes there are having color \meta{color name} in the current group and
- the result is stored in \meta{counter}. Next, macros named
- \meta{prefix}|1|, \meta{prefix}|2|, and so on are defined, that store
- the names of the first, second, third, and so on node having the color
- \meta{color name}.
-
- The net effect is that after you have prepared a color, you can quickly
- iterate over them. This is especially useful when you iterate over
- several color at the same time.
-
- As an example, let us create an operator then adds a zig-zag path
- between two color classes:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\newcount\leftshorecount \newcount\rightshorecount
-\newcount\mycount \newcount\myothercount
-\def\zigzag{
- \tikzgraphpreparecolor{left shore}\leftshorecount{left shore prefix}
- \tikzgraphpreparecolor{right shore}\rightshorecount{right shore prefix}
- \mycount=0\relax
- \loop
- \advance\mycount by 1\relax%
- % Add the "forward" edge
- \tikzgraphsset{new ->=
- {\csname left shore prefix\the\mycount\endcsname}
- {\csname right shore prefix\the\mycount\endcsname}{}{}}
- \myothercount=\mycount\relax%
- \advance\myothercount by1\relax%
- \tikzgraphsset{new <-=
- {\csname left shore prefix\the\myothercount\endcsname}
- {\csname right shore prefix\the\mycount\endcsname}{}{}}
- \ifnum\myothercount<\leftshorecount\relax
- \repeat
-}
-\begin{tikzpicture}
- \graph [color class=left shore, color class=right shore]
- { [operator=\zigzag]
- { [left shore, Cartesian placement] a, b, c },
- { [right shore, Cartesian placement, nodes={xshift=1cm}] d, e, f }
- };
-\end{tikzpicture}
-\end{codeexample}
- %
- Naturally, in order to turn the above code into a usable operator, some
- more code would be needed (like default values and taking care of
- shores of different sizes).
- \end{command}
-\end{key}
-
-There are a number of predefined operators, like |clique| or |cycle|, see the
-reference Section~\ref{section-library-graphs-reference} for a complete list.
-
-
-\subsubsection{Graph Operators for Joining Groups}
-\label{section-library-graphs-join}
-
-When you join two nodes |foo| and |bar| by the edge specification |->|, it is
-fairly obvious, what should happen: An edge from |(foo)| to |(bar)| should be
-created. However, suppose we use an edge specification between two node sets
-like |{a,b,c}| and |{d,e,f}|. In this case, it is not so clear which edges
-should be created. One might argue that all possible edges from any node in the
-first set to any node in the second set should be added. On the other hand, one
-might also argue that only a matching between these two sets should be created.
-Things get even more muddy when a longer chain of node sets are joined.
-
-Instead of fixing how edges are created between two node sets, \tikzname\ takes
-a somewhat more general, but also more complicated approach, which can be
-broken into two parts. In the following, assume that the following chain
-specification is given:
-%
-\begin{quote}
- \meta{spec$_1$} \meta{edge specification} \meta{spec$_2$}
-\end{quote}
-%
-An example might be |{a,b,c} -> {d, e->f}|.
-
-\medskip
-\textbf{The source and target vertices.} Let us start with the question of
-which vertices of the first node set should be connected to vertices in the
-second node set.
-
-There are two predefined special color classes that are used for this: |source|
-and |target|. For every group specification, some vertices are colored as
-|source| vertices and some vertices are |target| vertices (a node can both be a
-target and a source). Initially, every vertex is both a source and a target,
-but that can change as we will see in a moment.
-
-The intuition behind source and target vertices is that, in some sense, edges
-``from the outside'' lead into the group via the source vertices and lead out
-of the group via the target vertices. To be more precise, the following
-happens:
-%
-\begin{enumerate}
- \item The target vertices of the first group are connected to the source
- vertices of the second group.
- \item In the group resulting from the union of the nodes from
- \meta{spec$_1$} and \meta{spec$_2$}, the source vertices are only those
- from the first group, and the target vertices are only those from the
- second group.
-\end{enumerate}
-
-Let us go over the effect of these rules for the example
-|{a,b,c} -> {d, e->f}|. First, each individual node is initially both a
-|source| and a |target| vertex. Then, in |{a,b,c}| all nodes are still both
-source and target vertices since just grouping vertices does not change their
-colors. Now, in |e->f| something interesting happens for the first time: the
-target vertices of the ``group'' |e| (which is just the node |e|) are connected
-to the source vertices of the ``group'' |f|. This means, that an edge is added
-from |e| to |f|. Then, in the resulting group |e->f| the only source vertex is
-|e| and the only target vertex is |f|. This implies that in the group
-|{d,e->f}| the sources are |d| and |e| and the targets are |d| and~|f|.
-
-Now, in |{a,b,c} -> {d,e->f}| the targets of |{a,b,c}| (which are all three of
-them) are connected to the sources of |{d,e->f}| (which are just |d| and~|e|).
-Finally, in the whole graph only |a|, |b|, and |c| are sources while only |d|
-and |f| are targets.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\def\hilightsource#1{\fill [green, opacity=.25] (#1) circle [radius=2mm]; }
-\def\hilighttarget#1{\fill [red, opacity=.25] (#1) circle [radius=2mm]; }
-\tikz \graph
- [operator=\tikzgraphforeachcolorednode{source}{\hilightsource},
- operator=\tikzgraphforeachcolorednode{target}{\hilighttarget}]
- { {a,b,c} -> {d, e->f} };
-\end{codeexample}
-
-The next objective is to make more precise what it means that ``the targets of
-the first graph'' and the ``sources of the second graph'' should be connected.
-We know already of a general way of connecting nodes of a graph: operators!
-Thus, we use an operator for this job. For instance, the |complete bipartite|
-operator adds an edge from every node having a certain color to every node have
-a certain other color. This is exactly what we need here: The first color is
-``the color |target| restricted to the nodes of the first graph'' and the
-second color is ``the color |source| restricted to the nodes of the second
-graph''.
-
-However, we cannot really specify that only nodes from a certain subgraph are
-meant -- the |operator| machinery only operates on all nodes of the current
-graph. For this reason, what really happens is the following: When the |graph|
-command encounters \meta{spec$_1$} \meta{edge specification} \meta{spec$_2$},
-it first computes and colors the nodes of the first and the second
-specification independently. Then, the |target| nodes of the first graph are
-recolored to |target'| and the |source| nodes of the second graph are recolored
-to |source'|. Then, the two graphs are united into one graph and a
-\emph{joining operator} is executed, which should add edges between |target'|
-and |source'|. Once this is done, the colors |target'| and |source'| get
-erased. Note that in the resulting graph only the |source| nodes from the first
-graph are still |source| nodes and likewise for the |target| nodes of the
-second graph.
-
-\medskip
-\textbf{The joining operators.} The job of a joining operator is to add edges
-between nodes colored |target'| and |source'|. The following rule is used to
-determine which operator should be chosen for performing this job:
-%
-\begin{enumerate}
- \item If the \meta{edge specification} explicitly sets the |operator| key
- to something non-empty (and also not to |\relax|), then the \meta{code}
- of this |operator| call is used.
- \item Otherwise, the current value of the following key is used:
- %
- \begin{key}{/tikz/graphs/default edge operator=\meta{key} (initially matching and star)}
- This key stores the name of a \meta{key} that is executed for every
- \meta{edge specification} whose \meta{options} do not contain the
- |operator| key.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [default edge operator=matching] {
- {a, b} ->[matching and star]
- {c, d, e} --[complete bipartite]
- {f, g, h} --
- {i, j, k}
-};
-\end{codeexample}
- \end{key}
-\end{enumerate}
-
-A typical joining operator is |complete bipartite|. It takes the names of two
-color classes as input and adds edges from all vertices of the first class to
-all vertices of the second class. Now, the trick is that the default value for
-the |complete bipartite| key is |{target'}{source'}|. Thus, if you just write
-|->[complete bipartite]|, the same happens as if you had written
-%
-\begin{quote}
- |->[complete bipartite={target'}{source'}]|
-\end{quote}
-%
-This is exactly what we want to happen. The same default values are also set
-for other joining operators like |matching| or |butterfly|.
-
-Even though an operator like |complete bipartite| is typically used together
-with an edge specification, it can also be used as a normal operator together
-with a group specification. In this case, however, the color classes must be
-named explicitly:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\begin{tikzpicture}
- \graph [color class=red, color class=green, math nodes]
- { [complete bipartite={red}{green}]
- { [red, Cartesian placement] r_1, r_2, r_3 },
- { [green, Cartesian placement, nodes={xshift=1cm}] g_1, g_2, g_3 }
- };
-\end{tikzpicture}
-\end{codeexample}
-
-A list of predefined joining operators can be found in the reference
-Section~\ref{section-library-graphs-reference}.
-
-The fact that joining operators can also be used as normal operators leads to a
-subtle problem: A normal operator will typically use the current value of
-|default edge kind| to decide which kind of edges should be put between the
-identified vertices, while a joining operator should, naturally, use the kind
-of edge specified by the \meta{edge specification}. This problem is solved as
-follows: Like a normal operator, a joining operator should also use the current
-value of |default edge kind| for the edges it produces. The trick is that this
-will automatically be set to the current \meta{edge specification} when the
-operator explicitly in the \meta{options} of the edge specification or
-implicitly in the |default edge operator|.
-
-
-\subsection{Graph Macros}
-\label{section-library-graphs-macros}
-
-A \emph{graph macro} is a small graph that is inserted at some point into the
-graph that is currently being constructed. There is special support for such
-graph macros in \tikzname. You might wonder why this is necessary -- can't one
-use \TeX's normal macro mechanism? The answer is ``no'': one cannot insert new
-nodes into a graph using normal macros because the chains, groups, and nodes
-are determined prior to macro expansion. Thus, any macro encountered where some
-node text should go will only be expanded when this node is being named and
-typeset.
-
-A graph macro is declared using the following key:
-
-\begin{key}{/tikz/graphs/declare=\marg{graph name}\marg{specification}}
- This key declares that \meta{graph name} can subsequently be used as a
- replacement for a \meta{node name}. Whenever the \meta{graph name} is used
- in the following, a graph group will be inserted instead whose content is
- exactly \meta{specification}. In case \meta{graph name} is used together
- with some \meta{options}, they are executed prior to inserting the
- \meta{specification}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [branch down=4mm, declare={claw}{1 -- {2,3,4}}] {
- a;
- claw;
- b;
-};
-\end{codeexample}
- %
- In the next example, we use a key to configure a subgraph:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [ n/.code=\def\n{#1}, branch down=4mm,
- declare={star}{root -- { \foreach \i in {1,...,\n} {\i} }}]
-{ star [n=5]; };
-\end{codeexample}
- %
- Actually, the |n| key is already defined internally for a similar purpose.
-
- As a last example, let us define a somewhat more complicated graph macro.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\newcount\mycount
-\tikzgraphsset{
- levels/.store in=\tikzgraphlevel,
- levels=1,
- declare={bintree}{%
- [/utils/exec={%
- \ifnum\tikzgraphlevel=1\relax%
- \def\childtrees{ / }%
- \else%
- \mycount=\tikzgraphlevel%
- \advance\mycount by-1\relax%
- \edef\childtrees{
- / -> {
- bintree[levels=\the\mycount],
- bintree[levels=\the\mycount]
- }}
- \fi%
- },
- parse/.expand once=\childtrees
- ]
- % Everything is inside the \childtrees...
- }
-}
-\tikz \graph [grow down=5mm, branch right=5mm] { bintree [levels=5] };
-\end{codeexample}
- %
-\end{key}
-
-Note that when you use a graph macro several time inside the same graph, you
-will typically have to use the |name| option so that different copies of the
-subgraph are created:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [branch down=4mm, declare={claw}{1 -- {2,3,4}}] {
- claw [name=left],
- claw [name=right]
-};
-\end{codeexample}
-
-You will find a list of useful graph macros in the reference section,
-Section~\ref{section-library-graphs-reference-macros}.
-
-
-\subsection{Online Placement Strategies}
-\label{section-library-graphs-placement}
-
-The main job of the |graphs| library is to make it easy to specify which nodes
-are present in a graph and how they are connected. In contrast, it is
-\emph{not} the primary job of the library to compute good positions for nodes
-in a graph -- use for instance a |\matrix|, specify good positions ``by hand''
-or use the graph drawing facilities. Nevertheless, some basic support for
-automatic node placement is provided for simple cases. The |graphs| library
-will provide you with information about the position of nodes inside their
-groups and chains.
-
-As a graph is being constructed, a \emph{placement strategy} is used to
-determine a (reasonably good) position for the nodes as they are created. These
-placement strategies get some information about what \tikzname\ has already
-seen concerning the already constructed nodes, but it gets no information
-concerning the upcoming nodes. Because of this lack of information concerning
-the future, the strategies need to be what is called an \emph{online strategy}
-in computer science. (The opposite are \emph{offline strategies}, which get
-information about the whole graph and all the sizes of the nodes in it. The
-graph drawing libraries employ such offline strategies.)
-
-Strategies are selected using keys like |no placement| or
-|Cartesian placement|. It is permissible to use different strategies inside
-different parts of a graph, even though the different strategies do not always
-work together in perfect harmony.
-
-
-\subsubsection{Manual Placement}
-\label{section-graphs-xy}
-
-\begin{key}{/tikz/graphs/no placement}
- This strategy simply ``switches off'' the whole placement mechanism,
- causing all nodes to be placed at the origin by default. You need to use
- this strategy if you position nodes ``by hand''. For this, you can use the
- |at| key, the |shift| keys:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [no placement]
-{
- a[at={(0:0)}] -> b[at={(1,0)}] -> c[yshift=1cm];
-};
-\end{codeexample}
- %
- Since the syntax and the many braces and parentheses are a bit cumbersome,
- the following two keys might also be useful:
- %
- \begin{key}{/tikz/graphs/x=\meta{x dimension}}
- When you use this key, it will have the same effect as if you had
- written |at={(|\meta{x dimension}|,|\meta{y dimension}|)}|, where
- \meta{y dimension} is a value set using the |y| key:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [no placement]
-{
- a[x=0,y=0] -> b[x=1,y=0] -> c[x=0,y=1];
-};
-\end{codeexample}
- %
- Note that you can specify an |x| or a |y| key for a whole scope and
- then vary only the other key:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [no placement]
-{
- a ->
- { [x=1] % group option
- b [y=0] -> c[y=1]
- };
-};
-\end{codeexample}
- %
- Note that these keys have the path |/tikz/graphs/|, so they will be
- available inside |graph|s and will not clash with the usual |x| and |y|
- keys of \tikzname, which are used to specify the basic lengths of
- vectors.
- \end{key}
- %
- \begin{key}{/tikz/graphs/y=\meta{y dimension}}
- See above.
- \end{key}
-\end{key}
-
-
-\subsubsection{Placement on a Grid}
-
-\begin{key}{/tikz/graphs/Cartesian placement}
- This strategy is the default strategy. It works, roughly, as follows: For
- each new node on a chain, advance a ``logical width'' counter and for each
- new node in a group, advance a ``logical depth'' counter. When a chain
- contains a whole group, then the ``logical width'' taken up by the group is
- the maximum over the logical widths taken up by the chains inside the
- group; and symmetrically the logical depth of a chain is the maximum of the
- depths of the groups inside it.
-
- This slightly confusing explanation is perhaps best exemplified. In the
- below example, the two numbers indicate the two logical width and depth of
- each node as computed by the |graphs| library. Just ignore the arcane code
- that is used to print these numbers.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz
- \graph [nodes={align=center, inner sep=1pt}, grow right=7mm,
- typeset={\tikzgraphnodetext\\[-4pt]
- \tiny\mywidth\\[-6pt]\tiny\mydepth},
- placement/compute position/.append code=
- \pgfkeysgetvalue{/tikz/graphs/placement/width}{\mywidth}
- \pgfkeysgetvalue{/tikz/graphs/placement/depth}{\mydepth}]
-{
- a,
- b,
- c -> d -> {
- e -> f -> g,
- h -> i
- } -> j,
- k -> l
-};
-\end{codeexample}
- %
- You will find a detailed description of how these logical units are
- computed, exactly, in Section~\ref{section-library-graphs-new-online}.
-
- Now, even though we talk about ``widths'' and ``depths'' and even though by
- default a graph ``grows'' to the right and down, this is by no means fixed.
- Instead, you can use the following keys to change how widths and heights
- are interpreted:
- %
- \begin{key}{/tikz/graphs/chain shift=\meta{coordinate} (initially {(1,0)})}
- Under the regime of the |Cartesian placement| strategy, each node is
- shifted by the current logical width times this \meta{coordinate}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [chain shift=(45:1)] {
- a -> b -> c;
- d -> e;
- f -> g -> h;
-};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/graphs/group shift=\meta{coordinate} (initially {(0,-1)})}
- Like for |chain shift|, each node is shifted by the current logical
- depth times this \meta{coordinate}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [chain shift=(45:7mm), group shift=(-45:7mm)] {
- a -> b -> c;
- d -> e;
- f -> g -> h;
-};
-\end{codeexample}
- \end{key}
-\end{key}
-
-\begin{key}{/tikz/graphs/grow up=\meta{distance} (default 1)}
- Sets the |chain shift| to |(0,|\meta{distance}|)|, so that chains ``grow
- upward''. The distance by which the center of each new element is removed
- from the center of the previous one is \meta{distance}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grow up=7mm] { a -> b -> c};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/grow down=\meta{distance} (default 1)}
- Like |grow up|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grow down=7mm] { a -> b -> c};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/grow left=\meta{distance} (default 1)}
- Like |grow up|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grow left=7mm] { a -> b -> c};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/grow right=\meta{distance} (default 1)}
- Like |grow up|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grow right=7mm] { a -> b -> c};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/branch up=\meta{distance} (default 1)}
- Sets the |group shift| so that groups ``branch upward''. The distance by
- which the center of each new element is removed from the center of the
- previous one is \meta{distance}.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [branch up=7mm] { a -> b -> {c, d, e} };
-\end{codeexample}
- %
- Note that when you draw a tree, the |branch ...| keys specify how siblings
- (or adjacent branches) are arranged, while the |grow ...| keys specify in
- which direction the branches ``grow''.
-\end{key}
-
-\begin{key}{/tikz/graphs/branch down=\meta{distance} (default 1)}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [branch down=7mm] { a -> b -> {c, d, e}};
-\end{codeexample}
-%
-\end{key}
-
-\begin{key}{/tikz/graphs/branch left=\meta{distance} (default 1)}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [branch left=7mm, grow down=7mm] { a -> b -> {c, d, e}};
-\end{codeexample}
-%
-\end{key}
-
-\begin{key}{/tikz/graphs/branch right=\meta{distance} (default 1)}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [branch right=7mm, grow down=7mm] { a -> b -> {c, d, e}};
-\end{codeexample}
-%
-\end{key}
-
-The following keys place nodes in a $N\times M$ grid.
-%
-\begin{key}{/tikz/graphs/grid placement}
- This key works similar to |Cartesian placement|. As for that placement
- strategy, a node has logical width and depth 1. However, the computed total
- width and depth are mapped to a $N\times M$ grid. The values of $N$ and $M$
- depend on the size of the graph and the value of |wrap after|. The number
- of columns $M$ is either set to |wrap after| explicitly or computed
- automatically as $\sqrt{\texttt{\string|V\string|}}$. $N$ is the number of
- rows needed to lay out the graph in a grid with $M$ columns.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-% An example with 6 nodes, 3 columns and therefor 2 rows
-\tikz \graph [grid placement] { subgraph I_n[n=6, wrap after=3] };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-% An example with 9 nodes with columns and rows computed automatically
-\tikz \graph [grid placement] { subgraph Grid_n [n=9] };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-% Directions can be changed
-\tikz \graph [grid placement, branch up, grow left] { subgraph Grid_n [n=9] };
-\end{codeexample}
- %
- In case a user-defined graph instead of a pre-defined |subgraph| is to be
- laid out using |grid placement|, |n| has to be specified explicitly:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grid placement] {
- [n=6, wrap after=3]
- a -- b -- c -- d -- e -- f
-};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Placement Taking Node Sizes Into Account}
-
-Options like |grow up| or |branch right| do not take the sizes of the
-to-be-positioned nodes into account -- all nodes are placed quite ``dumbly'' at
-grid positions. It turns out that the |Cartesian placement| can also be used to
-place nodes in such a way that their height and/or width is taken into account.
-Note, however, that while the following options may yield an adequate placement
-in many situations, when you need advanced alignments you should use a |matrix|
-or advanced offline strategies to place the nodes.
-
-\begin{key}{/tikz/graphs/grow right sep=\meta{distance} (default 1em)}
- This key has several effects, but let us start with the bottom line: Nodes
- along a chain are placed in such a way that the left end of a new node is
- \meta{distance} from the right end of the previous node:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grow right sep, left anchor=east, right anchor=west] {
- start -- {
- long text -- {short, very long text} -- more text,
- long -- longer -- longest
- } -- end
-};
-\end{codeexample}
- %
- What happens internally is the following: First, the |anchor| of the nodes
- is set to |west| (or |north west| or |south west|, see below). Second, the
- logical width of a node is no longer |1|, but set to the actual width of
- the node (which we define as the horizontal difference between the |west|
- anchor and the |east| anchor) in points. Third, the |chain shift| is set to
- |(1pt,0pt)|.
-\end{key}
-
-\begin{key}{/tikz/graphs/grow left sep=\meta{distance} (default 1em)}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grow left sep] { long -- longer -- longest };
-\end{codeexample}
-%
-\end{key}
-
-\begin{key}{/tikz/graphs/grow up sep=\meta{distance} (default 1em)}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grow up sep] {
- a / $a=x$ --
- b / {$b=\displaystyle \int_0^1 x dx$} --
- c [draw, circle, inner sep=7mm]
-};
-\end{codeexample}
-%
-\end{key}
-
-\begin{key}{/tikz/graphs/grow down sep=\meta{distance} (default 1em)}
- As above.
-\end{key}
-
-\begin{key}{/tikz/graphs/branch right sep=\meta{distance} (default 1em)}
- This key works like |grow right sep|, only it affects groups rather than
- chains.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grow down, branch right sep] {
- start -- {
- an even longer text -- {short, very long text} -- more text,
- long -- longer -- longest,
- some text -- a -- b
- } -- end
-};
-\end{codeexample}
- %
- When both this key and, say, |grow down sep| are set, instead of the |west|
- anchor, the |north west| anchor will be selected automatically.
-\end{key}
-
-\begin{key}{/tikz/graphs/branch left sep=\meta{distance} (default 1em)}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grow down sep, branch left sep] {
- start -- {
- an even longer text -- {short, very long text} -- more text,
- long -- longer,
- some text -- a -- b
- } -- end
-};
-\end{codeexample}
-%
-\end{key}
-
-\begin{key}{/tikz/graphs/branch up sep=\meta{distance} (default 1em)}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [branch up sep] { a, b, c[draw, circle, inner sep=7mm] };
-\end{codeexample}
-%
-\end{key}
-
-\begin{key}{/tikz/graphs/branch down sep=\meta{distance} (default 1em)}
-\end{key}
-
-
-\subsubsection{Placement On a Circle}
-
-The following keys place nodes on circles. Note that, typically, you do not use
-|circular placement| directly, but rather use one of the two keys |clockwise|
-or |counterclockwise|.
-
-\begin{key}{/tikz/graphs/circular placement}
- This key works quite similar to |Cartesian placement|. As for that
- placement strategy, a node has logical width and depth |1|. However, the
- computed total width and depth are mapped to polar coordinates rather than
- Cartesian coordinates.
-
- \begin{key}{/tikz/graphs/chain polar shift=|(|\meta{angle}|:|\meta{radius}|)| (initially {(0:1)})}
- Under the regime of the |circular placement| strategy, each node on a
- chain is shifted by
- |(|\meta{logical width}\meta{angle}|:|\meta{logical width}\meta{angle}|)|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [circular placement] {
- a -> b -> c;
- d -> e;
- f -> g -> h;
-};
-\end{codeexample}
- %
- \end{key}
- %
- \begin{key}{/tikz/graphs/group polar shift=|(|\meta{angle}|:|\meta{radius}|)| (initially {(45:0)})}
- Like for |group shift|, each node on a chain is shifted by
- |(|\meta{logical depth}\meta{angle}|:|\meta{logical depth}\meta{angle}|)|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [circular placement, group polar shift=(30:0)] {
- a -> b -> c;
- d -> e;
- f -> g -> h;
-};
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [circular placement,
- chain polar shift=(30:0),
- group polar shift=(0:1cm)] {
- a -- b -- c;
- d -- e;
- f -- g -- h;
-};
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/graphs/radius=\meta{dimension} (initially 1cm)}
- This is an initial value that is added to the total computed radius
- when the polar shift of a node has been calculated. Essentially, this
- key allows you to set the \meta{radius} of the innermost circle.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [circular placement, radius=5mm] { a, b, c, d };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [circular placement, radius=1cm] { a, b, c, d };
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/graphs/phase=\meta{angle} (initially 90)}
- This is an initial value that is added to the total computed angle when
- the polar shift of a node has been calculated.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [circular placement] { a, b, c, d };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [circular placement, phase=0] { a, b, c, d };
-\end{codeexample}
- \end{key}
-\end{key}
-
-\label{key-graphs-clockwise}%
-\begin{key}{/tikz/graphs/clockwise=\meta{number} (default \string\tikzgraphVnum)}
- This key sets the |group shift| so that if there are exactly \meta{number}
- many nodes in a group, they will form a complete circle. If you do not
- provide a \meta{number}, the current value of |\tikzgraphVnum| is used,
- which is exactly what you want when you use predefined graph macros like
- |subgraph K_n|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [clockwise=4] { a, b, c, d };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [clockwise] { subgraph K_n [n=5] };
-\end{codeexample}
- %
-\end{key}
-
-\label{key-graphs-counterclockwise}%
-\begin{key}{/tikz/graphs/counterclockwise=\meta{number} (default \string\tikzgraphVnum)}
- Works like |clockwise|, only the direction is inverted.
-\end{key}
-
-
-\subsubsection{Levels and Level Styles}
-
-As a graph is being parsed, the |graph| command keeps track of a parameter
-called the \emph{level} of a node. Provided that the graph is actually
-constructed in a tree-like manner, the level is exactly equal to the level of
-the node inside this tree.
-
-\begin{key}{/tikz/graphs/placement/level}
- This key stores a number that is increased for each element on a chain, but
- gets reset at the end of a group:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [ branch down=5mm, typeset=
- \tikzgraphnodetext:\pgfkeysvalueof{/tikz/graphs/placement/level}]
-{
- a -> {
- b,
- c -> {
- d,
- e -> {f,g},
- h
- },
- j
- }
-};
-\end{codeexample}
- %
- Unlike the parameters |depth| and |width| described in the next section,
- the key |level| is always available.
-\end{key}
-
-In addition to keeping track of the value of the |level| key, the |graph|
-command also executes the following keys whenever it creates a node:
-
-\begin{stylekey}{/tikz/graph/level=\meta{level}}
- This key gets executed for each newly created node with \meta{level} set to
- the current level of the node. You can use this key to, say, reconfigure
- the node distance or the node color.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/graph/level \meta{level}}
- This key also gets executed for each newly created node with \meta{level}
- set to the current level of the node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [
- branch down=5mm,
- level 1/.style={nodes=red},
- level 2/.style={nodes=green!50!black},
- level 3/.style={nodes=blue}]
-{
- a -> {
- b,
- c -> {
- d,
- e -> {f,g},
- h
- },
- j
- }
-};
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [
- branch down=5mm,
- level 1/.style={grow right=2cm},
- level 2/.style={grow right=1cm},
- level 3/.style={grow right=5mm}]
-{
- a -> {
- b,
- c -> {
- d,
- e -> {f,g},
- h
- },
- j
- }
-};
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsubsection{Defining New Online Placement Strategies}
-\label{section-library-graphs-new-online}
-
-In the following the details of how to define a new placement strategy are
-explained. Most readers may wish to skip this section.
-
-As a graph specification is being parsed, the |graphs| library will keep track
-of different numbers that identify the positions of the nodes. Let us start
-with what happens on a chain. First, the following counter is increased for
-each element of the chain:
-%
-\begin{key}{/tikz/graphs/placement/element count}
- This key stores a number that tells us the position of the node on the
- current chain. However, you only have access to this value inside the code
- passed to the macro |compute position|, explained later on.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [
- grow right sep, typeset=\tikzgraphnodetext:\mynum,
- placement/compute position/.append code=
- \pgfkeysgetvalue{/tikz/graphs/placement/element count}{\mynum}]
-{
- a -> b -> c,
- d -> {e, f->h} -> j
-};
-\end{codeexample}
- %
- As can be seen, each group resets the element counter.
-\end{key}
-
-The second value that is computed is more complicated to explain, but it also
-gives more interesting information:
-%
-\begin{key}{/tikz/graphs/placement/width}
- This key stores the ``logical width'' of the nodes parsed up to now in the
- current group or chain (more precisely, parsed since the last call of
- |place| in an enclosing group). This is not necessarily the ``total
- physical width'' of the nodes, but rather a number representing how ``big''
- the elements prior to the current element were. This \emph{may} be their
- width, but it may also be their height or even their number (which,
- incidentally, is the default). You can use the |width| to perform shifts or
- rotations of to-be-created nodes (to be explained later).
-
- The logical width is defined recursively as follows. First, the width of a
- single node is computed by calling the following key:
- %
- \begin{key}{/tikz/graphs/placement/logical node width=\meta{full node name}}
- This key is called to compute a physical or logical width of the node
- \meta{full node name}. You can change the code of this key. The code
- should return the computed value in the macro |\pgfmathresult|. By
- default, this key returns |1|.
- \end{key}
- %
- The width of a chain is the sum of the widths of its elements. The width of
- a group is the maximum of the widths of its elements.
-
- To get a feeling what the above rules imply in practice, let us first have
- a look at an example where each node has logical width and height |1|
- (which is the default). The arcane options at the beginning of the code
- just setup things so that the computed width and depth of each node is
- displayed at the bottom of each node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz
- \graph [nodes={align=center, inner sep=1pt}, grow right=7mm,
- typeset={\tikzgraphnodetext\\[-4pt]
- \tiny\mywidth\\[-6pt]\tiny\mydepth},
- placement/compute position/.append code=
- \pgfkeysgetvalue{/tikz/graphs/placement/width}{\mywidth}
- \pgfkeysgetvalue{/tikz/graphs/placement/depth}{\mydepth}]
-{
- a,
- b,
- c -> d -> {
- e -> f -> g,
- h -> i
- } -> j,
- k -> l
-};
-\end{codeexample}
- %
- In the next example the ``logical'' width and depth actually match the
- ``physical'' width and height. This is caused by the |grow right sep|
- option, which internally sets the |logical node width| key so that it
- returns the width of its parameter in points.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz
- \graph [grow right sep, branch down sep, nodes={align=left, inner sep=1pt},
- typeset={\tikzgraphnodetext\\[-4pt] \tiny Width: \mywidth\\[-6pt] \tiny Depth: \mydepth},
- placement/compute position/.append code=
- \pgfkeysgetvalue{/tikz/graphs/placement/width}{\mywidth}
- \pgfkeysgetvalue{/tikz/graphs/placement/depth}{\mydepth}]
-{
- a,
- b,
- c -> d -> {
- e -> f -> g,
- h -> i
- } -> j,
- k -> l
-};
-\end{codeexample}
- %
-\end{key}
-
-Symmetrically to chains, as a group is being constructed, counters are
-available for the number of chains encountered so far in the current group and
-for the logical depth of the current group:
-%
-\begin{key}{/tikz/graphs/placement/chain count}
- This key stores a number that tells us the sequence number of the
- chain in the current group.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [
- grow right sep, branch down=5mm, typeset=\tikzgraphnodetext:\mynum,
- placement/compute position/.append code=
- \pgfkeysgetvalue{/tikz/graphs/placement/chain count}{\mynum}]
-{
- a -> b -> {c,d,e},
- f,
- g -> h
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/placement/depth}
- Similarly to the |width| key, this key stores the ``logical depth'' of the
- nodes parsed up to now in the current group or chain and, also similarly,
- this key may or may not be related to the actual depth/height of the
- current node. As for the |width|, the exact definition is as follows: For a
- single node, the depth is computed by the following key:
- %
- \begin{key}{/tikz/graphs/placement/logical node depth=\meta{full node name}}
- The code behind this key should return the ``logical height'' of the
- node \meta{full node name} in the macro |\pgfmathresult|.
- \end{key}
- %
- Second, the depth of a group is the sum of the depths of its elements.
- Third, the depth of a chain is the maximum of the depth of its elements.
-\end{key}
-
-The |width|, |depth|, |element count|, and |chain count| keys get updated
-automatically, but do not have an effect by themselves. This is to the
-following two keys:
-
-\begin{key}{/tikz/graphs/placement/compute position=\meta{code}}
- The \meta{code} is called by the |graph| command just prior to creating a
- new node (the exact moment when this key is called is detailed in the
- description of the |place| key). When the \meta{code} is called, all of the
- keys described above will hold numbers computed in the way described above.
-
- The job of the \meta{code} is to setup node options appropriately so that
- the to-be-created node will be placed correctly. Thus, the \meta{code}
- should typically set the key |nodes={shift=|\meta{coordinate}|}| where
- \meta{coordinate} is the computed position for the node. The \meta{code}
- could also set other options like, say, the color of a node depending on
- its depth.
-
- The following example appends some code to the standard code of
- |compute position| so that ``deeper'' nodes of a tree are lighter.
- (Naturally, the same effect could be achieved much more easily using the
- |level| key.)
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\newcount\mycount
-\def\lightendeepernodes{
- \pgfmathsetcount{\mycount}{
- 100-20*\pgfkeysvalueof{/tikz/graphs/placement/width}
- }
- \edef\mydepth{\the\mycount}
- \tikzset{nodes={fill=red!\mydepth,circle,text=white}}
-}
-\tikz
- \graph [placement/compute position/.append code=\lightendeepernodes]
- {
- a -> {
- b -> c -> d,
- e -> {
- f,
- g
- },
- h
- }
- };
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/placement/place}
- Executing this key has two effects: First, the key |compute position| is
- called to compute a good position for future nodes (usually, these ``future
- nodes'' are just a single node that is created immediately). Second, all of
- the above counters like |depth| or |width| are reset (but not |level|).
-
- There are two places where this key is sensibly called: First, just prior
- to creating a node, which happens automatically. Second, when you change
- the online strategy. In this case, the computed width and depth values from
- one strategy typically make no sense in the other strategy, which is why
- the new strategy should proceed ``from a fresh start''. In this case, the
- implicit call of |compute position| ensures that the new strategy gets the
- last place the old strategy would have used as its starting point, while
- the computation of its positions is now relative to this new starting
- point.
-
- For these reasons, when an online strategy like |Cartesian placement| is
- called, this key gets called implicitly. You will rarely need to call this
- key directly, except when you define a new online strategy.
-\end{key}
-
-
-\subsection{Reference: Predefined Elements}
-\label{section-library-graphs-reference}
-
-\subsubsection{Graph Macros}
-\label{section-library-graphs-reference-macros}
-
-\begin{tikzlibrary}{graphs.standard}
- This library defines a number of graph macros that are often used in the
- literature. When new graphs are added to this collection, they will follow
- the definitions in the Mathematica program, see
- \url{mathworld.wolfram.com/topics/SimpleGraphs.html}.
-\end{tikzlibrary}
-
-\begin{graph}{subgraph I\_n}
- This graph consists just of $n$ unconnected vertices. The following key is
- used to specify the set of these vertices:
- %
- \begin{key}{/tikz/graphs/V=\marg{list of vertices}}
- Sets a list of vertex names for use with graphs like |subgraph I_n| and
- also other graphs. This list is available in the macro |\tikzgraphV|.
- The number of elements of this list is available in |\tikzgraphVnum|.
- \end{key}
- %
- \begin{key}{/tikz/graphs/n=\meta{number}}
- This is an abbreviation for
- |V={1,...,|\meta{number}|}, name shore V/.style={name=V}|.
- \end{key}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [branch right, nodes={draw, circle}]
- { subgraph I_n [V={a,b,c}] };
-\end{codeexample}
- %
- This graph is not particularly exciting by itself. However, it is often
- used to introduce nodes into a graph that are then connected as in the
- following example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [clockwise, clique] { subgraph I_n [n=4] };
-\end{codeexample}
- %
-\end{graph}
-
-\begin{graph}{subgraph I\_nm}
- This graph consists of two sets of once $n$ unconnected vertices and then
- $m$ unconnected vertices. The first set consists of the vertices set by the
- key |V|, the other set consists of the vertices set by the key |W|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph { subgraph I_nm [V={1,2,3}, W={a,b,c}] };
-\end{codeexample}
- %
- In order to set the graph path name of the two sets, the following keys get
- executed:
- %
- \begin{stylekey}{/tikz/graphs/name shore V (initially \normalfont empty)}
- Set this style to, say, |name=my V set| in order to set a name for the
- |V| set.
- \end{stylekey}
- %
- \begin{stylekey}{/tikz/graphs/name shore W (initially \normalfont empty)}
- Same as for |name shore V|.
- \end{stylekey}
- %
- \begin{key}{/tikz/graphs/W=\marg{list of vertices}}
- Sets the list of vertices for the |W| set. The elements and their
- number are available in the macros |\tikzgraphW| and |\tikzgraphWnum|,
- respectively.
- \end{key}
- %
- \begin{key}{/tikz/graphs/m=\meta{number}}
- This is an abbreviation for
- |W={1,...,|\meta{number}|}, name shore W/.style={name=W}|.
- \end{key}
- %
- The main purpose of this subgraph is to setup the nodes in a bipartite
- graph:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph {
- subgraph I_nm [n=3, m=4];
-
- V 1 -- { W 2, W 3 };
- V 2 -- { W 1, W 3 };
- V 3 -- { W 1, W 4 };
-};
-\end{codeexample}
- %
-\end{graph}
-
-\begin{graph}{subgraph K\_n}
- This graph is the complete clique on the vertices from the |V| key.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [clockwise] { subgraph K_n [n=7] };
-\end{codeexample}
- %
-\end{graph}
-
-\begin{graph}{subgraph K\_nm}
- This graph is the complete bipartite graph with the two shores |V| and |W|
- as in |subgraph I_nm|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [branch right, grow down]
- { subgraph K_nm [V={6,...,9}, W={b,...,e}] };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [simple, branch right, grow down]
-{
- subgraph K_nm [V={1,2,3}, W={a,b,c,d}, ->];
- subgraph K_nm [V={2,3}, W={b,c}, <-];
-};
-\end{codeexample}
- %
-\end{graph}
-
-\begin{graph}{subgraph P\_n}
- This graph is the path on the vertices in |V|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [branch right] { subgraph P_n [n=3] };
-\end{codeexample}
- %
-\end{graph}
-
-\begin{graph}{subgraph C\_n}
- This graph is the cycle on the vertices in |V|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [clockwise] { subgraph C_n [n=7, ->] };
-\end{codeexample}
- %
-\end{graph}
-
-\begin{graph}{subgraph Grid\_n}
- This graph is a grid of the vertices in |V|.
- %
- \begin{key}{/tikz/graphs/wrap after=\meta{number}}
- Defines the number of nodes placed in a single row of the grid. This
- value implicitly defines the number of grid columns as well. In the
- following example a |grid placement| is used to visualize the edges
- created between the nodes of a |Grid_n| |subgraph| using different
- values for |wrap after|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [grid placement] { subgraph Grid_n [n=3,wrap after=1] };
-\tikz \graph [grid placement] { subgraph Grid_n [n=3,wrap after=3] };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [grid placement] { subgraph Grid_n [n=4,wrap after=2] };
-\tikz \graph [grid placement] { subgraph Grid_n [n=4] };
-\end{codeexample}
- \end{key}
-\end{graph}
-
-% TODO: Implement the Grid_nm subgraph described here:
-%
-%\begin{graph}{subgraph Grid\_nm}
-% This graph is a grid built from the cartesian product of the two node
-% sets |V| and |W| which are either defined using the keys
-% |/tikz/graphs/V| and |/tikz/graphs/W| or |/tikz/graphs/n| and
-% |/tikz/graphs/m| or a mixture of both.
-%
-% The resulting |Grid_nm| subgraph has $n$ ``rows'' and $m$ ``columns'' and
-% the nodes are named |V i W j| with $1\le i\le n$ and $1\le j\le n$.
-% The names of the two shores |V| and |W| can be changed as described in
-% the documentation of the keys |/tikz/graphs/name shore V| and
-% |/tikz/graphs/name shore W|.
-% \begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-%\tikz \graph [grid placement] { subgraph Grid_nm [V={1,2,3}, W={4, 5, 6}] };
-% \end{codeexample}
-%\end{graph}
-
-
-\subsubsection{Group Operators}
-
-The following keys use the |operator| key to setup operators that connect the
-vertices of the current group having a certain color in a specific way.
-
-\begin{key}{/tikz/graphs/clique=\meta{color} (default all)}
- Adds an edge between all vertices of the current group having the (logical)
- color \meta{color}. Since, by default, this color is set to |all|, which is
- a color that all nodes get by default, when you do not specify anything,
- all nodes will be connected.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [clockwise, n=5] {
- a,
- b,
- {
- [clique]
- c, d, e
- }
-};
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [color class=red, clockwise, n=5] {
- [clique=red, ->]
- a, b[red], c[red], d, e[red]
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/induced independent set=\meta{color} (default all)}
- This key is the ``opposite'' of a |clique|: It removes all edges in the
- current group having belonging to color class \meta{color}. More precisely,
- an edge of kind |-!-| is added for each pair of vertices. This means that
- edge only get removed if you specify the |simple| option.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [simple] {
- subgraph K_n [<->, n=7, clockwise]; % create lots of edges
-
- { [induced independent set] 1, 3, 4, 5, 6 }
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/cycle=\meta{color} (default all)}
- Connects the nodes colored \meta{color} is a cyclic fashion. The ordering
- is the ordering in which they appear in the whole graph specification.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [clockwise, n=6, phase=60] {
- { [cycle, ->] a, b, c },
- { [cycle, <-] d, e, f }
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/induced cycle=\meta{color} (default all)}
- While the |cycle| command will only add edges, this key will also remove
- all other edges between the nodes of the cycle, provided we are
- constructing a |simple| graph.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [simple] {
- subgraph K_n [n=7, clockwise]; % create lots of edges
-
- { [induced cycle, ->, edge=red] 2, 3, 4, 6, 7 },
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/path=\meta{color} (default all)}
- Works like |cycle|, only there is no edge from the last to the first
- vertex.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [clockwise, n=6] {
- { [path, ->] a, b, c },
- { [path, <-] d, e, f }
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/induced path=\meta{color} (default all)}
- Works like |induced cycle|, only there is no edge from the last to the
- first vertex.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [simple] {
- subgraph K_n [n=7, clockwise]; % create lots of edges
-
- { [induced path, ->, edges=red] 2, 3, 4, 6, 7 },
-};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Joining Operators}
-
-The following keys are typically used as options of an \meta{edge
-specification}, but can also be called in a group specification (however, then,
-the colors need to be set explicitly).
-
-\begin{key}{/tikz/graphs/complete bipartite=\meta{from color}\meta{to color} (default \char`\{source'\char`\}\char`\{target'\char`\})}
- Adds all possible edges from every node having color \meta{from color} to
- every node having color \meta{to color}:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph { {a, b} ->[complete bipartite]
- {c, d, e} --[complete bipartite]
- {g, h, i, j} --[complete bipartite]
- k };
-\end{codeexample}
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [color class=red, color class=green, clockwise, n=6] {
- [complete bipartite={red}{green}, ->]
- a [red], b[red], c[red], d[green], e[green], f[green]
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/induced complete bipartite}
- Works like the |complete bipartite| operator, but in a |simple| graph any
- edges between the vertices in either shore are removed (more precisely,
- they get replaced by |-!-| edges).
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [simple] {
- subgraph K_n [n=5, clockwise]; % Lots of edges
-
- {2, 3} ->[induced complete bipartite] {4, 5}
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/matching=\meta{from color}\meta{to color} (default \char`\{source'\char`\}\char`\{target'\char`\})}
- This joining operator forms a maximum \emph{matching} between the nodes of
- the two sets of nodes having colors \meta{from color} and \meta{to color},
- respectively. The first node of the from set is connected to the first node
- of to set, the second node of the from set is connected to the second node
- of the to set, and so on. If the sets have the same size, what results is
- what graph theoreticians call a \emph{perfect matching}, otherwise only a
- maximum, but not perfect matching results.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph {
- {a, b, c} ->[matching]
- {d, e, f} --[matching]
- {g, h} --[matching]
- {i, j, k}
-};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/graphs/matching and star=\meta{from color}\meta{to color} (default \char`\{source'\char`\}\char`\{target'\char`\})}
- The |matching and star| connector works like the |matching| connector, only
- it behaves differently when the two to-be-connected sets have different
- size. In this case, all the surplus nodes get connected to the last node of
- the other set, resulting in what is known as a \emph{star} in graph theory.
- This simple rule allows for some powerful effects (since this connector is
- the one initially set, there is no need to add it here):
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph { a -> {b, c} -> {d, e} -- f};
-\end{codeexample}
- %
- The |matching and star| connector also makes it easy to create trees and
- series-parallel graphs.
-\end{key}
-
-\begin{key}{/tikz/graphs/butterfly=\opt{\meta{options}}}
- The |butterfly| connector is used to create the kind of connections present
- between layers of a so-called \emph{butterfly network}. As for other
- connectors, two sets of nodes are connected, which are the nodes having
- color |target'| and |source'| by default. In a \emph{level $l$} connection,
- the first $l$ nodes of the first set are connected to the second $l$ nodes
- of the second set, while the second $l$ nodes of the first set get
- connected to the first $l$ nodes of the second set. Then, for next $2l$
- nodes of both sets a similar kind of connection is installed. Additionally,
- each node gets connected to the corresponding node in the other set with
- the same index (as in a |matching|):
- %
-\begin{codeexample}[preamble={\usetikzlibrary{graphs.standard}}]
-\tikz \graph [left anchor=east, right anchor=west,
- branch down=4mm, grow right=15mm] {
- subgraph I_n [n=12, name=A] --[butterfly={level=3}]
- subgraph I_n [n=12, name=B] --[butterfly={level=2}]
- subgraph I_n [n=12, name=C]
-};
-\end{codeexample}
- %
- Unlike most joining operators, the colors of the nodes in the first and the
- second set are not passed as parameters to the |butterfly| key. Rather,
- they can be set using the \meta{options}, which are executed with the path
- prefix |/tikz/graphs/butterfly|.
- %
- \begin{key}{/tikz/graphs/butterfly/level=\meta{level} (initially 1)}
- Sets the level $l$ for the connections.
- \end{key}
- %
- \begin{key}{/tikz/graphs/butterfly/from=\meta{color} (initially target')}
- Sets the color class of the from nodes.
- \end{key}
- %
- \begin{key}{/tikz/graphs/butterfly/to=\meta{color} (initially source')}
- Sets the color class of the to nodes.
- \end{key}
-\end{key}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-matrices.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-matrices.tex
deleted file mode 100644
index f46ad79b7b..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-matrices.tex
+++ /dev/null
@@ -1,865 +0,0 @@
-% 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{Matrices and Alignment}
-\label{section-matrices}
-
-\subsection{Overview}
-
-When creating pictures, one often faces the problem of correctly aligning parts
-of the picture. For example, you might wish that the |baseline|s of certain
-nodes should be on the same line and some further nodes should be below these
-nodes with, say, their centers on a vertical lines. There are different ways of
-solving such problems. For example, by making clever use of anchors, nearly all
-such alignment problems can be solved. However, this often leads to complicated
-code. An often simpler way is to use \emph{matrices}, the use of which is
-explained in the current section.
-
-A \tikzname\ matrix is similar to \LaTeX's |{tabular}| or |{array}|
-environment, only instead of text each cell contains a little picture or a
-node. The sizes of the cells are automatically adjusted such that they are
-large enough to contain all the cell contents.
-
-Matrices are a powerful tool and they need to be handled with some care. For
-impatient readers who skip the rest of this section: you \emph{must} end
-\emph{every} row with |\\|. In particular, the last row \emph{must} be ended
-with |\\|.
-
-Many of the ideas implemented in \tikzname's matrix support are due to Mark
-Wibrow -- many thanks to Mark at this point!
-
-
-\subsection{Matrices are Nodes}
-
-Matrices are special in many ways, but for most purposes matrices are treated
-like nodes. This means, that you use the |node| path command to create a matrix
-and you only use a special option, namely the |matrix| option, to signal that
-the node will contain a matrix. Instead of the usual \TeX-box that makes up the
-|text| part of the node's shape, the matrix is used. Thus, in particular, a
-matrix can have a shape, this shape can be drawn or filled, it can be used in a
-tree, and so on. Also, you can refer to the different anchors of a matrix.
-
-\begin{key}{/tikz/matrix=\meta{true or false} (default true)}
- This option can be passed to a |node| path command. It signals that the
- node will contain a matrix.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (4,2);
- \node [matrix,fill=red!20,draw=blue,very thick] (my matrix) at (2,1)
- {
- \draw (0,0) circle (4mm); & \node[rotate=10] {Hello}; \\
- \draw (0.2,0) circle (2mm); & \fill[red] (0,0) circle (3mm); \\
- };
-
- \draw [very thick,->] (0,0) |- (my matrix.west);
-\end{tikzpicture}
-\end{codeexample}
- %
- The exact syntax of the matrix is explained in the course of this section.
- %
- \begin{stylekey}{/tikz/every matrix (initially \normalfont empty)}
- This style is used in every matrix.
- \end{stylekey}
- %
- \begin{stylekey}{/tikz/every outer matrix (initially \normalfont empty)}
- While the |every matrix| key also applies to the matrix contents, this
- only applies to the outer node which holds the matrix.
- \end{stylekey}
-\end{key}
-
-Even more so than nodes, matrices will often be the only object on a path.
-Because of this, there is a special abbreviation for creating matrices:
-
-\begin{command}{\matrix}
- Inside |{tikzpicture}| this is an abbreviation for |\path node[matrix]|.
-\end{command}
-
-Even though matrices are nodes, some options do not have the same effect as for
-normal nodes:
-%
-\begin{enumerate}
- \item Rotations and scaling have no effect on a matrix as a whole (however,
- you can still transform the contents of the cells normally). Before the
- matrix is typeset, the rotational and scaling part of the
- transformation matrix is reset.
- \item For multi-part shapes you can only set the |text| part of the node.
- \item All options starting with |text| such as |text width| have no effect.
- \item If you place a matrix on a path, the matrix contents will be
- collected into a macro, which tokenizes them. This means that |&| will
- lose its meaning as an alignment character, resulting in an error. If
- you need to place a matrix on a path, use |ampersand replacement| to
- work around that problem.
-\end{enumerate}
-
-
-\subsection{Cell Pictures}
-\label{section-tikz-cell-pictures}
-
-A matrix consists of rows of \emph{cells}. Each row (including the last one!)
-is ended by the command |\\|. The character |&| is used to separate cells.
-Inside each cell, you must place commands for drawing a picture, called the
-\emph{cell picture} in the following. (However, cell pictures are not enclosed
-in a complete |{pgfpicture}| environment, they are a bit more light-weight. The
-main difference is that cell pictures cannot have layers.) It is not necessary
-to specify beforehand how many rows or columns there are going to be and if a
-row contains less cell pictures than another line, empty cells are
-automatically added as needed.
-
-
-\subsubsection{Alignment of Cell Pictures}
-
-For each cell picture a bounding box is computed. These bounding boxes and the
-origins of the cell pictures determine how the cells are aligned. Let us start
-with the rows: Consider the cell pictures on the first row. Each has a bounding
-box and somewhere inside this bounding box the origin of the cell picture can
-be found (the origin might even lie outside the bounding box, but let us ignore
-this problem for the moment). The cell pictures are then shifted around such
-that all origins lie on the same horizontal line. This may make it necessary to
-shift some cell pictures upwards and others downwards, but it can be done and
-this yields the vertical alignment of the cell pictures this row. The top of
-the row is then given by the top of the ``highest'' cell picture in the row,
-the bottom of the row is given by the bottom of the lowest cell picture. (To be
-more precise, the height of the row is the maximum $y$-value of any of the
-bounding boxes and the depth of the row is the negated minimum $y$-value of the
-bounding boxes).
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- [every node/.style={draw=black,anchor=base,font=\huge}]
-
- \matrix [draw=red]
- {
- \node {a}; \fill[blue] (0,0) circle (2pt); &
- \node {X}; \fill[blue] (0,0) circle (2pt); &
- \node {g}; \fill[blue] (0,0) circle (2pt); \\
- };
-\end{tikzpicture}
-\end{codeexample}
-
-Each row is aligned in this fashion: For each row the cell pictures
-are vertically aligned such that the origins lie on the same
-line. Then the second row is placed below the first row such that the
-bottom of the first row touches the top of the second row (unless a
-|row sep| is used to add a bit of space). Then the bottom of the
-second row touches the top of the third row, and so on. Typically,
-each row will have an individual height and depth.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- [every node/.style={draw=black,anchor=base}]
-
- \matrix [draw=red]
- {
- \node {a}; & \node {X}; & \node {g}; \\
- \node {a}; & \node {X}; & \node {g}; \\
- };
-
- \matrix [row sep=3mm,draw=red] at (0,-2)
- {
- \node {a}; & \node {X}; & \node {g}; \\
- \node {a}; & \node {X}; & \node {g}; \\
- };
-\end{tikzpicture}
-\end{codeexample}
-
-Let us now have a look at the columns. The rules for how the pictures on any
-given column are aligned are very similar to the row alignment: Consider all
-cell pictures in the first column. Each is shifted horizontally such that the
-origins lie on the same vertical line. Then, the left end of the column is at
-the left end of the bounding box that protrudes furthest to the left. The right
-end of the column is at the right end of the bounding box that protrudes
-furthest to the right. This fixes the horizontal alignment of the cell pictures
-in the first column and the same happens the cell pictures in the other
-columns. Then, the right end of the first column touches the left end of the
-second column (unless |column sep| is used). The right end of the second column
-touches the left end of the third column, and so on. (Internally, two columns
-are actually used to achieve the desired horizontal alignment, but that is only
-an implementation detail.)
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[every node/.style={draw}]
- \matrix [draw=red]
- {
- \node[left] {Hallo}; \fill[blue] (0,0) circle (2pt); \\
- \node {X}; \fill[blue] (0,0) circle (2pt); \\
- \node[right] {g}; \fill[blue] (0,0) circle (2pt); \\
- };
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[every node/.style={draw}]
- \matrix [draw=red,column sep=1cm]
- {
- \node {8}; & \node{1}; & \node {6}; \\
- \node {3}; & \node{5}; & \node {7}; \\
- \node {4}; & \node{9}; & \node {2}; \\
- };
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{Setting and Adjusting Column and Row Spacing}
-
-There are different ways of setting and adjusting the spacing between columns
-and rows. First, you can use the options |column sep| and |row sep| to set a
-default spacing for all rows and all columns. Second, you can add options to
-the |&| character and the |\\| command to adjust the spacing between two
-specific columns or rows. Additionally, you can specify whether the space
-between two columns or rows should be considered between the origins of cells
-in the column or row or between their borders.
-
-\begin{key}{/tikz/column sep=\meta{spacing list}}
- This option sets a default space that is added between every two columns.
- This space can be positive or negative and is zero by default. The
- \meta{spacing list} normally contains a single dimension like |2pt|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \matrix [draw,column sep=1cm,nodes=draw]
- {
- \node(a) {123}; & \node (b) {1}; & \node {1}; \\
- \node {12}; & \node {12}; & \node {1}; \\
- \node(c) {1}; & \node (d) {123}; & \node {1}; \\
- };
- \draw [red,thick] (a.east) -- (a.east |- c)
- (d.west) -- (d.west |- b);
- \draw [<->,red,thick] (a.east) -- (d.west |- b)
- node [above,midway] {1cm};
-\end{tikzpicture}
-\end{codeexample}
- %
- More generally, the \meta{spacing list} may contain a whole list of
- numbers, separated by commas, and occurrences of the two key words
- |between origins| and |between borders|. The effect of specifying such a
- list is the following: First, all numbers occurring in the list are simply
- added to compute the final spacing. Second, concerning the two keywords,
- the last occurrence of one of the keywords is important. If the last
- occurrence is |between borders| or if neither occurs, then the space is
- inserted between the two columns normally. However, if the last occurs is
- |between origins|, then the following happens: The distance between the
- columns is adjusted such that the difference between the origins of all the
- cells in the first column (remember that they all lie on straight line) and
- the origins of all the cells in the second column is exactly the given
- distance.
-
- \emph{The }|between origins|\emph{ option can only be used for columns
- mentioned in the first row, that is, you cannot specify this option for
- columns introduced only in later rows.}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \matrix [draw,column sep={1cm,between origins},nodes=draw]
- {
- \node(a) {123}; & \node (b) {1}; & \node {1}; \\
- \node {12}; & \node {12}; & \node {1}; \\
- \node {1}; & \node {123}; & \node {1}; \\
- };
- \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {1cm};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/row sep=\meta{spacing list}}
- This option works like |column sep|, only for rows. Here, too, you can
- specify whether the space is added between the lower end of the first row
- and the upper end of the second row, or whether the space is computed
- between the origins of the two rows.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \matrix [draw,row sep=1cm,nodes=draw]
- {
- \node (a) {123}; & \node {1}; & \node {1}; \\
- \node (b) {12}; & \node {12}; & \node {1}; \\
- \node {1}; & \node {123}; & \node {1}; \\
- };
- \draw [<->,red,thick] (a.south) -- (b.north) node [right,midway] {1cm};
-\end{tikzpicture}
-\end{codeexample}
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \matrix [draw,row sep={1cm,between origins},nodes=draw]
- {
- \node (a) {123}; & \node {1}; & \node {1}; \\
- \node (b) {12}; & \node {12}; & \node {1}; \\
- \node {1}; & \node {123}; & \node {1}; \\
- };
- \draw [<->,red,thick] (a.center) -- (b.center) node [right,midway] {1cm};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-The row-end command |\\| allows you to provide an optional argument, which must
-be a dimension. This dimension will be added to the list in |row sep|. This
-means that, firstly, any numbers you list in this argument will be added as an
-extra row separation between the line being ended and the next line and,
-secondly, you can use the keywords |between origins| and |between borders| to
-locally overrule the standard setting for this line pair.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \matrix [row sep=1mm]
- {
- \draw (0,0) circle (2mm); & \draw (0,0) circle (2mm); \\
- \draw (0,0) circle (2mm); & \draw (0,0) circle (2mm); \\[-1mm]
- \draw (0,0) coordinate (a) circle (2mm); &
- \draw (0,0) circle (2mm); \\[1cm,between origins]
- \draw (0,0) coordinate (b) circle (2mm); &
- \draw (0,0) circle (2mm); \\
- };
- \draw [<->,red,thick] (a.center) -- (b.center) node [right,midway] {1cm};
-\end{tikzpicture}
-\end{codeexample}
-
-The cell separation character |&| also takes an optional argument, which must
-also be a spacing list. This spacing list is added to the |column sep| having a
-similar effect as the option for the |\\| command for rows.
-
-This optional spacing list can only be given the first time a new column is
-started (usually in the first row), subsequent usages of this option in later
-rows have no effect.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \matrix [draw,nodes=draw,column sep=1mm]
- {
- \node {8}; &[2mm] \node{1}; &[-1mm] \node {6}; \\
- \node {3}; & \node{5}; & \node {7}; \\
- \node {4}; & \node{9}; & \node {2}; \\
- };
-\end{tikzpicture}
-\end{codeexample}
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \matrix [draw,nodes=draw,column sep=1mm]
- {
- \node {8}; &[2mm] \node(a){1}; &[1cm,between origins] \node(b){6}; \\
- \node {3}; & \node {5}; & \node {7}; \\
- \node {4}; & \node {9}; & \node {2}; \\
- };
- \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {11mm};
-\end{tikzpicture}
-\end{codeexample}
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \matrix [draw,nodes=draw,column sep={1cm,between origins}]
- {
- \node (a) {8}; & \node (b) {1}; &[between borders] \node (c) {6}; \\
- \node {3}; & \node {5}; & \node {7}; \\
- \node {4}; & \node {9}; & \node {2}; \\
- };
- \draw [<->,red,thick] (a.center) -- (b.center) node [above,midway] {10mm};
- \draw [<->,red,thick] (b.east) -- (c.west) node [above,midway] {10mm};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{Cell Styles and Options}
-
-The following styles and options are useful for changing the appearance of all
-cell pictures:
-
-\begin{stylekey}{/tikz/every cell=\marg{row}\marg{column} (initially \normalfont empty)}
- This style is installed at the beginning of each cell picture with the two
- parameters being the current \meta{row} and \meta{column} of the cell. Note
- that setting this style to |draw| will \emph{not} cause all nodes to be
- drawn since the |draw| option has to be passed to each node individually.
-
- Inside this style (and inside all cells), the current \meta{row} and
- \meta{column} number are also accessible via the counters
- |\pgfmatrixcurrentrow| and |\pgfmatrixcurrentcolumn|.
-\end{stylekey}
-
-\begin{key}{/tikz/cells=\meta{options}}
- This key adds the \meta{options} to the style |every cell|. It is mainly
- just a shorthand for the code |every cell/.append style=|\meta{options}.
-\end{key}
-
-\begin{key}{/tikz/nodes=\meta{options}}
- This key adds the \meta{options} to the style |every node|. It is mainly
- just a shorthand for the code |every node/.append style=|\meta{options}.
-
- The main use of this option is the install some options for the nodes
- \emph{inside} the matrix that should not apply to the matrix \emph{itself}.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \matrix [nodes={fill=blue!20,minimum size=5mm}]
- {
- \node {8}; & \node{1}; & \node {6}; \\
- \node {3}; & \node{5}; & \node {7}; \\
- \node {4}; & \node{9}; & \node {2}; \\
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-The next set of styles can be used to change the appearance of certain rows,
-columns, or cells. If more than one of these styles is defined, they are
-executed in the below order (the |every cell| style is executed before all of
-the below).
-%
-\begin{stylekey}{/tikz/column \meta{number}}
- This style is used for every cell in column \meta{number}.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/every odd column}
- This style is used for every cell in an odd column.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/every even column}
- This style is used for every cell in an even column.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/row \meta{number}}
- This style is used for every cell in row \meta{number}.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/every odd row}
- This style is used for every cell in an odd row.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/every even row}
- This style is used for every cell in an even row.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/row \meta{row number} column \meta{column number}}
- This style is used for the cell in row \meta{row number} and column
- \meta{column number}.
-\end{stylekey}
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- [row 1/.style={red},
- column 2/.style={green!50!black},
- row 3 column 3/.style={blue}]
-
- \matrix
- {
- \node {8}; & \node{1}; & \node {6}; \\
- \node {3}; & \node{5}; & \node {7}; \\
- \node {4}; & \node{9}; & \node {2}; \\
- };
-\end{tikzpicture}
-\end{codeexample}
-
-You can use the |column |\meta{number} option to change the alignment for
-different columns.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- [column 1/.style={anchor=base west},
- column 2/.style={anchor=base east},
- column 3/.style={anchor=base}]
- \matrix
- {
- \node {123}; & \node{456}; & \node {789}; \\
- \node {12}; & \node{45}; & \node {78}; \\
- \node {1}; & \node{4}; & \node {7}; \\
- };
-\end{tikzpicture}
-\end{codeexample}
-
-In some cases, it is desirable to include some automation in each column/row
-separately. A typical example is to apply stripe-pattern to almost all columns
-with exceptions. For these type of use-cases, nesting these keys can open up
-a lot of possibilities; in the following example a ``feature comparison'' table
-is demonstrated. It is intentionally made rather verbose and a bit redundant
-to show how the column and row settings can be progressively overwritten to
-create certain effects.
-
-\begin{codeexample}[preamble={\usetikzlibrary{matrix,fit}}]
-\begin{tikzpicture}[
- font=\sffamily,
- striped col/.style={column #1/.append style={
- every even row/.style={nodes={fill=olive!50}}}},
- head color/.style args={#1/#2}{column #1/.append style={
- row 1/.append style={nodes={fill=#2}}}}
-]
-
-\matrix [
- matrix of nodes, nodes in empty cells,
- nodes={text width=2cm, align=center,
- minimum height=1.5em, anchor=center},
- striped col/.list={1,...,5}, % add striped col style to all cols
- column 1/.style={ % Override stripes and modify the feature column
- row 1 column 1/.style={nodes={fill=none, draw=none}},
- nodes={fill=olive, inner ysep=0},
- },
- % modify headers first via common styles and then specific colors
- row 1/.style={nodes={text depth=0.2ex, text width=2cm, text=white}},
- head color/.list={2/orange,3/teal,4/cyan,5/magenta}
- ] (m)
- {
- & Basic & Standard & Professional & Enterprise \\
- Feature A & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
- Feature B & $\bullet$ & $\bullet$ & $\bullet$ & $\bullet$ \\
- Feature C & & & & $\bullet$ \\
- Feature D & & $\bullet$ & $\bullet$ & $\bullet$ \\
- Feature E & & & $\bullet$ & $\bullet$ \\
- };
-% Add emphasis on selection by the use of "fit" library
-\node[fit={(m-1-4.north west) (m-6-4.south east)},
- ultra thick, inner sep=0, rounded corners=1mm,
- draw=cyan, label={[cyan,align=center]270:Popular\\Choice!}]{};
-\end{tikzpicture}
-\end{codeexample}
-
-The order in which these styles are applied is configurable. You can also
-install your own styles. The following styles (in fact, internally they are
-|/.code| keys) wrap the styles introduced in the previous paragraph passing the
-correct argument and ensuring that they are only called for even or odd rows.
-However, it is not recommended to override these.
-
-\begin{stylekey}{/tikz/matrix/inner style/every cell}
- Wraps |/tikz/every cell|.
-\end{stylekey}
-\begin{stylekey}{/tikz/matrix/inner style/column}
- Wraps |/tikz/column |\meta{number}.
-\end{stylekey}
-\begin{stylekey}{/tikz/matrix/inner style/even odd column}
- Wraps |/tikz/every even column| and |/tikz/every odd column|.
-\end{stylekey}
-\begin{stylekey}{/tikz/matrix/inner style/row}
- Wraps |/tikz/row |\meta{number}.
-\end{stylekey}
-\begin{stylekey}{/tikz/matrix/inner style/even odd row}
- Wraps |/tikz/every even row| and |/tikz/every odd row|.
-\end{stylekey}
-\begin{stylekey}{/tikz/matrix/inner style/cell}
- Wraps |/tikz/row |\meta{number}| column |\meta{number}.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/matrix/inner style order}
- The order in which these styles are applied to the matrix cells is
- specified by this key. By default it is
- %
-\begin{codeexample}[code only]
-\tikzset{
- matrix/inner style order={
- every cell,
- column,
- even odd column,
- row,
- even odd row,
- cell,
- },
-}
-\end{codeexample}
- %
- You can use this to install your own styles here, but only \emph{names} of
- styles are permitted here. The style specification has to be placed
- outside of |matrix/inner style order| and unless it is installed inside
- |/tikz/matrix/inner style/|, it has to be fully qualified.
- %
-\begin{codeexample}[code only]
-\tikzset{
- my style/.code={%
- \ifnum\pgfmatrixcurrentcolumn=2
- \tikzset{font=\itshape}%
- \fi
- },
- matrix/inner style order={
- every cell,
- even odd column,
- even odd row,
- column,
- row,
- cell,
- /tikz/my style,
- },
-}
-\end{codeexample}
- %
-\end{stylekey}
-
-In many matrices all cell pictures have nearly the same code. For example,
-cells typically start with |\node{| and end |};|. The following options allow
-you to execute such code in all cells:
-
-\begin{key}{/tikz/execute at begin cell=\meta{code}}
- The code will be executed at the beginning of each nonempty cell.
-\end{key}
-%
-\begin{key}{/tikz/execute at end cell=\meta{code}}
- The code will be executed at the end of each nonempty cell.
-\end{key}
-%
-\begin{key}{/tikz/execute at empty cell=\meta{code}}
- The code will be executed inside each empty cell.
-\end{key}
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- [matrix of nodes/.style={
- execute at begin cell=\node\bgroup,
- execute at end cell=\egroup;%
- }]
- \matrix [matrix of nodes]
- {
- 8 & 1 & 6 \\
- 3 & 5 & 7 \\
- 4 & 9 & 2 \\
- };
-\end{tikzpicture}
-\end{codeexample}
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- [matrix of nodes/.style={
- execute at begin cell=\node\bgroup,
- execute at end cell=\egroup;,%
- execute at empty cell=\node{--};%
- }]
- \matrix [matrix of nodes]
- {
- 8 & 1 & \\
- 3 & & 7 \\
- & & 2 \\
- };
-\end{tikzpicture}
-\end{codeexample}
-
-The |matrix| library defines a number of styles that make use of the above
-options.
-
-
-\subsection{Anchoring a Matrix}
-
-Since matrices are nodes, they can be anchored in the usual fashion using the
-|anchor| option. However, there are two ways to influence this placement
-further. First, the following option is often useful:
-
-\begin{key}{/tikz/matrix anchor=\meta{anchor}}
- This option has the same effect as |anchor|, but the option applies only to
- the matrix itself, not to the cells inside. If you just say |anchor=north|
- as an option to the matrix node, all nodes inside matrix will also have
- this anchor, unless it is explicitly set differently for each node. By
- comparison, |matrix anchor| sets the anchor for the matrix, but for the
- nodes inside the value of |anchor| remain unchanged.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \matrix [matrix anchor=west] at (0,0)
- {
- \node {123}; \\ % still center anchor
- \node {12}; \\
- \node {1}; \\
- };
- \matrix [anchor=west] at (0,-2)
- {
- \node {123}; \\ % inherited west anchor
- \node {12}; \\
- \node {1}; \\
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-The second way to anchor a matrix is to use \emph{an anchor of a node inside
-the matrix}. For this, the |anchor| option has a special effect when given as
-an argument to a matrix:
-
-\begin{key}{/tikz/anchor=\meta{anchor or node.anchor}}
- Normally, the argument of this option refers to anchor of the matrix node,
- which is the node that includes all of the stuff of the matrix. However,
- you can also provide an argument of the form \meta{node}|.|\meta{anchor}
- where \meta{node} must be node defined inside the matrix and \meta{anchor}
- is an anchor of this node. In this case, the whole matrix is shifted around
- in such a way that this particular anchor of this particular node lies at
- the |at| position of the matrix. The same is true for |matrix anchor|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \matrix[matrix anchor=inner node.south,anchor=base,row sep=3mm] at (1,1)
- {
- \node {a}; & \node {b}; & \node {c}; & \node {d}; \\
- \node {a}; & \node(inner node) {b}; & \node {c}; & \node {d}; \\
- \node {a}; & \node {b}; & \node {c}; & \node {d}; \\
- };
- \draw (inner node.south) circle (1pt);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Considerations Concerning Active Characters}
-
-Even though \tikzname\ seems to use |&| to separate cells, \pgfname\ actually
-uses a different command to separate cells, namely the command
-|\pgfmatrixnextcell| and using a normal |&| character will normally fail. What
-happens is that, \tikzname\ makes |&| an active character and then defines this
-character to be equal to |\pgfmatrixnextcell|. In most situations this will
-work nicely, but sometimes |&| cannot be made active; for instance because the
-matrix is used in an argument of some macro or the matrix contains nodes that
-contain normal |{tabular}| environments. In this case you can use the following
-option to avoid having to type |\pgfmatrixnextcell| each time:
-
-\begin{key}{/tikz/ampersand replacement=\meta{macro name or empty}}
- If a macro name is provided, this macro will be defined to be equal to
- |\pgfmatrixnextcell| inside matrices and |&| will not be made active. For
- instance, you could say |ampersand replacement=\&| and then use |\&| to
- separate columns as in the following example:
- %
-\begin{codeexample}[]
-\tikz
- \matrix [ampersand replacement=\&]
- {
- \draw (0,0) circle (4mm); \& \node[rotate=10] {Hello}; \\
- \draw (0.2,0) circle (2mm); \& \fill[red] (0,0) circle (3mm); \\
- };
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Examples}
-
-The following examples are adapted from code by Mark Wibrow. The first two
-redraw pictures from Timothy van Zandt's PStricks documentation:
-%
-{\catcode`\|=12
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix [matrix of math nodes,row sep=1cm]
- {
- |(U)| U &[2mm] &[8mm] \\
- & |(XZY)| X \times_Z Y & |(X)| X \\
- & |(Y)| Y & |(Z)| Z \\
- };
- \begin{scope}[every node/.style={midway,auto,font=\scriptsize}]
- \draw [double, dashed] (U) -- node {$x$} (X);
- \draw (X) -- node {$p$} (X -| XZY.east)
- (X) -- node {$f$} (Z)
- -- node {$g$} (Y)
- -- node {$q$} (XZY)
- -- node {$y$} (U);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[
- preamble={\usetikzlibrary{matrix}},
- pre={\definecolor{graphicbackground}{rgb}{0.96,0.96,0.8}},
-]
-\begin{tikzpicture}[>=stealth,->,shorten >=2pt,looseness=.5,auto]
- \matrix [matrix of math nodes,
- column sep={2cm,between origins},
- row sep={3cm,between origins},
- nodes={circle, draw, minimum size=7.5mm}]
- {
- & |(A)| A & \\
- |(B)| B & |(E)| E & |(C)| C \\
- & |(D)| D \\
- };
- \begin{scope}[every node/.style={font=\small\itshape}]
- \draw (A) to [bend left] node [midway] {g} (B);
- \draw (B) to [bend left] node [midway] {f} (A);
- \draw (D) -- node [midway] {c} (B);
- \draw (E) -- node [midway] {b} (B);
- \draw (E) -- node [near end] {a} (C);
- \draw [-,line width=8pt,draw=graphicbackground]
- (D) to [bend right, looseness=1] (A);
- \draw (D) to [bend right, looseness=1]
- node [near start] {b} node [near end] {e} (A);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{matrix}}]
-\begin{tikzpicture}
- \matrix (network)
- [matrix of nodes,%
- nodes in empty cells,
- nodes={outer sep=0pt,circle,minimum size=4pt,draw},
- column sep={1cm,between origins},
- row sep={1cm,between origins}]
- {
- & & & \\
- & & & \\
- |[draw=none]| & |[xshift=1mm]| & |[xshift=-1mm]| \\
- };
- \foreach \a in {1,...,4}{
- \draw (network-3-2) -- (network-2-\a);
- \draw (network-3-3) -- (network-2-\a);
- \draw [-stealth] ([yshift=5mm]network-1-\a.north) -- (network-1-\a);
- \foreach \b in {1,...,4}
- \draw (network-1-\a) -- (network-2-\b);
- }
- \draw [stealth-] ([yshift=-5mm]network-3-2.south) -- (network-3-2);
- \draw [stealth-] ([yshift=-5mm]network-3-3.south) -- (network-3-3);
-\end{tikzpicture}
-\end{codeexample}
-
-The following example is adapted from code written by Kjell Magne Fauske, which
-is based on the following paper: K.~Bossley, M.~Brown, and C.~Harris,
-Neurofuzzy identification of an autonomous underwater vehicle,
-\emph{International Journal of Systems Science}, 1999, 30, 901--913.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{arrows,shapes.geometric}}]
-\begin{tikzpicture}
- [auto,
- decision/.style={diamond, draw=blue, thick, fill=blue!20,
- text width=4.5em,align=flush center,
- inner sep=1pt},
- block/.style ={rectangle, draw=blue, thick, fill=blue!20,
- text width=5em,align=center, rounded corners,
- minimum height=4em},
- line/.style ={draw, thick, -latex',shorten >=2pt},
- cloud/.style ={draw=red, thick, ellipse,fill=red!20,
- minimum height=2em}]
-
- \matrix [column sep=5mm,row sep=7mm]
- {
- % row 1
- \node [cloud] (expert) {expert}; &
- \node [block] (init) {initialize model}; &
- \node [cloud] (system) {system}; \\
- % row 2
- & \node [block] (identify) {identify candidate model}; & \\
- % row 3
- \node [block] (update) {update model}; &
- \node [block] (evaluate) {evaluate candidate models}; & \\
- % row 4
- & \node [decision] (decide) {is best candidate}; & \\
- % row 5
- & \node [block] (stop) {stop}; & \\
- };
- \begin{scope}[every path/.style=line]
- \path (init) -- (identify);
- \path (identify) -- (evaluate);
- \path (evaluate) -- (decide);
- \path (update) |- (identify);
- \path (decide) -| node [near start] {yes} (update);
- \path (decide) -- node [midway] {no} (stop);
- \path [dashed] (expert) -- (init);
- \path [dashed] (system) -- (init);
- \path [dashed] (system) |- (evaluate);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-paths.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-paths.tex
deleted file mode 100644
index 7e0cae5108..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-paths.tex
+++ /dev/null
@@ -1,1426 +0,0 @@
-% 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{Syntax for Path Specifications}
-\label{section-paths}
-
-A \emph{path} is a series of straight and curved line segments. It is specified
-following a |\path| command and the specification must follow a special syntax,
-which is described in the subsections of the present section.
-
-\begin{command}{\path\meta{specification}|;|}
- This command is available only inside a |{tikzpicture}| environment.
-
- The \meta{specification} is a long stream of \emph{path operations}. Most
- of these path operations tell \tikzname\ how the path is built. For
- example, when you write |--(0,0)|, you use a \emph{line-to operation} and
- it means ``continue the path from wherever you are to the origin''.
-
- At any point where \tikzname\ expects a path operation, you can also give
- some graphic options, which is a list of options in brackets, such as
- |[rounded corners]|. These options can have different effects:
- %
- \begin{enumerate}
- \item Some options take ``immediate'' effect and apply to all
- subsequent path operations on the path. For example, the
- |rounded corners| option will round all following corners, but not
- the corners ``before'' and if the |sharp corners| is given later on
- the path (in a new set of brackets), the rounding effect will end.
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) -- (1,1)
- [rounded corners] -- (2,0) -- (3,1)
- [sharp corners] -- (3,0) -- (2,1);
-\end{codeexample}
- %
- Another example are the transformation options, which also apply
- only to subsequent coordinates.
- \item The options that have immediate effect can be ``scoped'' by
- putting part of a path in curly braces. For example, the above
- example could also be written as follows:
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) -- (1,1)
- {[rounded corners] -- (2,0) -- (3,1)}
- -- (3,0) -- (2,1);
-\end{codeexample}
- %
- \item Some options only apply to the path as a whole. For example,
- the |color=| option for determining the color used for, say,
- drawing the path always applies to all parts of the path. If
- several different colors are given for different parts of the
- path, only the last one (on the outermost scope) ``wins'':
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) -- (1,1)
- [color=red] -- (2,0) -- (3,1)
- [color=blue] -- (3,0) -- (2,1);
-\end{codeexample}
-
- Most options are of this type. In the above example, we would
- have had to ``split up'' the path into several |\path| commands:
- %
-\begin{codeexample}[]
-\tikz{\draw (0,0) -- (1,1);
- \draw [color=red] (1,1) -- (2,0) -- (3,1);
- \draw [color=blue] (3,1) -- (3,0) -- (2,1);}
-\end{codeexample}
- \end{enumerate}
-
- By default, the |\path| command does ``nothing'' with the path, it just
- ``throws it away''. Thus, if you write |\path(0,0)--(1,1);|, nothing is
- drawn in your picture. The only effect is that the area occupied by the
- picture is (possibly) enlarged so that the path fits inside the area. To
- actually ``do'' something with the path, an option like |draw| or |fill|
- must be given somewhere on the path. Commands like |\draw| do this
- implicitly.
-
- Finally, it is also possible to give \emph{node specifications} on a path.
- Such specifications can come at different locations, but they are always
- allowed when a normal path operation could follow. A node specification
- starts with |node|. Basically, the effect is to typeset the node's text as
- normal \TeX\ text and to place it at the ``current location'' on the path.
- The details are explained in Section~\ref{section-nodes}.
-
- Note, however, that the nodes are \emph{not} part of the path in any way.
- Rather, after everything has been done with the path what is specified by
- the path options (like filling and drawing the path due to a |fill| and a
- |draw| option somewhere in the \meta{specification}), the nodes are added
- in a post-processing step.
-
- \emph{Note:} When scanning for path operations \tikzname\ expands tokens
- looking for valid path operations. This however implies that these tokens
- has to be fully expandable up to the point where it results in a valid path
- operation.
-\end{command}
-
-\begin{key}{/tikz/name=\meta{path name}}
- Assigns a name to the path for reference (specifically, for reference
- in animations; for reference in intersections, use the |name path|
- command, which has a different purpose, see the |intersections| library
- for details). Since the name is a ``high-level'' name (drivers never
- know of it), you can use spaces, number, letters, or whatever you like
- when naming a path, but the name may \emph{not} contain any punctuation
- like a dot, a comma, or a colon.
-\end{key}
-
-The following style influences scopes:
-%
-\begin{stylekey}{/tikz/every path (initially \normalfont empty)}
- This style is installed at the beginning of every path. This can be
- useful for (temporarily) adding, say, the |draw| option to everything
- in a scope.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- [fill=yellow!80!black, % only sets the color
- every path/.style={draw}] % all paths are drawn
- \fill (0,0) rectangle +(1,1);
- \shade (2,0) rectangle +(1,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{key}{/tikz/insert path=\meta{path}}
- This key can be used inside an option to add something to the current path.
- This is mostly useful for defining styles that create graphic contents.
- This option should be used with care, for instance it should not be used as
- an argument of, say, a |node|. In the following example, we use a style to
- add little circles to a path.
- %
-\begin{codeexample}[]
-\tikz [c/.style={insert path={circle[radius=2pt]}}]
- \draw (0,0) -- (1,1) [c] -- (3,2) [c];
-\end{codeexample}
- %
- The effect is the same as of
- |(0,0) -- (1,1) circle[radius=2pt] -- (3,2) circle[radius=2pt]|.
-\end{key}
-
-The following options are for experts only:
-
-\begin{key}{/tikz/append after command=\meta{path}}
- Some of the path commands described in the following sections take optional
- arguments. For these commands, when you use this key inside these options,
- the \meta{path} will be inserted \emph{after} the path command is done. For
- instance, when you give this command in the option list of a node, the
- \meta{path} will be added after the node. This is used by, for instance,
- the |label| option to allow you to specify a label in the option list of a
- node, but have this |label| cause a node to be added after another node.
- %
-\begin{codeexample}[]
-\tikz \draw node [append after command={(foo)--(1,1)},draw] (foo){foo};
-\end{codeexample}
- %
- If this key is called multiple times, the effects accumulate, that is, all
- of the paths are added in the order to keys were found.
-\end{key}
-
-\begin{key}{/tikz/prefix after command=\meta{path}}
- Works like |append after command|, only the accumulation order is inverse:
- The \meta{path} is added before any earlier paths added using either
- |append after command| or |prefix after command|.
-\end{key}
-
-
-\subsection{The Move-To Operation}
-
-The perhaps simplest operation is the move-to operation, which is specified by
-just giving a coordinate where a path operation is expected.
-
-\begin{pathoperation}[noindex]{}{\meta{coordinate}}
- \index{empty@\protect\meta{empty} path operation}%
- \index{Path operations!empty@\protect\texttt{\meta{empty}}}%
- The move-to operation normally starts a path at a certain point. This does
- not cause a line segment to be created, but it specifies the starting point
- of the next segment. If a path is already under construction, that is, if
- several segments have already been created, a move-to operation will start
- a new part of the path that is not connected to any of the previous
- segments.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) --(2,0) (0,1) --(2,1);
-\end{tikzpicture}
-\end{codeexample}
-
- In the specification |(0,0) --(2,0) (0,1) --(2,1)| two move-to operations
- are specified: |(0,0)| and |(0,1)|. The other two operations, namely
- |--(2,0)| and |--(2,1)| are line-to operations, described next.
-\end{pathoperation}
-
-There is special coordinate called |current subpath start| that is always at
-the position of the last move-to operation on the current path.
-%
-\begin{codeexample}[]
-\tikz [line width=2mm]
- \draw (0,0) -- (1,0) -- (1,1)
- -- (0,1) -- (current subpath start);
-\end{codeexample}
-
-Note how in the above example the path is not closed (as |--cycle| would do).
-Rather, the line just starts and ends at the origin without being a closed
-path.
-
-
-\subsection{The Line-To Operation}
-
-\subsubsection{Straight Lines}
-
-\begin{pathoperation}{--}{\meta{coordinate or cycle}}
- The line-to operation extends the current path from the current point in a
- straight line to the given \meta{coordinate} (the ``or cycle'' part is
- explained in a moment). The ``current point'' is the endpoint of the
- previous drawing operation or the point specified by a prior move-to
- operation.
-
- When a line-to operation is used and some path segment has just been
- constructed, for example by another line-to operation, the two line
- segments become joined. This means that if they are drawn, the point where
- they meet is ``joined'' smoothly. To appreciate the difference, consider
- the following two examples: In the left example, the path consists of two
- path segments that are not joined, but they happen to share a point, while
- in the right example a smooth join is shown.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[line width=10pt]
- \draw (0,0) --(1,1) (1,1) --(2,0);
- \draw (3,0) -- (4,1) -- (5,0);
- \useasboundingbox (0,1.5); % make bounding box higher
-\end{tikzpicture}
-\end{codeexample}
-
- Instead of a coordinate following the two minus signs, you can also use the
- text |cycle|. This causes the straight line from the current point to go to
- the last point specified by a move-to operation. Note that this need not be
- the beginning of the path. Furthermore, a smooth join is created between
- the first segment created after the last move-to operation and the straight
- line appended by the cycle operation.
-
- Consider the following example. In the left example, two triangles are
- created using three straight lines, but they are not joined at the ends. In
- the second example cycle operations are used.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[line width=10pt]
- \draw (0,0) -- (1,1) -- (1,0) -- (0,0) (2,0) -- (3,1) -- (3,0) -- (2,0);
- \draw (5,0) -- (6,1) -- (6,0) -- cycle (7,0) -- (8,1) -- (8,0) -- cycle;
- \useasboundingbox (0,1.5); % make bounding box higher
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{pathoperation}
-
-Writing |cycle| instead of a coordinate at the end of a path operation is
-possible with all path operations that end with a coordinate (such as |--| or
-|..| or |sin| or |grid|, but not |graph| or |plot|). In all cases, the effect
-is that the coordinate of the last moveto is used as the coordinate expected by
-the path operation and that a smooth join is added. (What actually happens that
-the text |cycle| used with any path operation other than |--| gets replaced by
-|(current subpath start)--cycle|.)
-
-
-\subsubsection{Horizontal and Vertical Lines}
-
-Sometimes you want to connect two points via straight lines that are only
-horizontal and vertical. For this, you can use two path construction
-operations.
-
-{\catcode`\|=12
-\begin{pathoperation}[noindex]{-|}{\meta{coordinate or cycle}}
- \index{--1@\protect\texttt{-\protect\pgfmanualbar} path operation}%
- \index{Path operations!--1@\protect\texttt{-\protect\pgfmanualbar}}%
- \pgfmanualpdflabel[\catcode`\|=12 ]{-|}{}%
- This operation means ``first horizontal, then vertical''.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) node(a) [draw] {A} (1,1) node(b) [draw] {B};
- \draw (a.north) |- (b.west);
- \draw[color=red] (a.east) -| (2,1.5) -| (b.north);
-\end{tikzpicture}
-\end{codeexample}
- %
- Instead of a coordinate you can also write \verb!cycle! to close the path:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[ultra thick]
- \draw (0,0) -- (1,1) -| cycle;
-\end{tikzpicture}
-\end{codeexample}
-\end{pathoperation}
-
-\begin{pathoperation}[noindex]{|-}{\meta{coordinate or cycle}}
- \index{--2@\protect\texttt{\protect\pgfmanualbar-} path operation}%
- \index{Path operations!--2@\protect\texttt{\protect\pgfmanualbar-}}%
- \pgfmanualpdflabel[\catcode`\|=12 ]{|-}{}%
- This operations means ``first vertical, then horizontal''.
-\end{pathoperation}
-}
-
-
-\subsection{The Curve-To Operation}
-
-The curve-to operation allows you to extend a path using a Bézier curve.
-
-\begin{pathoperation}{..}{\declare{|controls|}\meta{c}\opt{|and|\meta{d}}\declare{|..|\meta{y or cycle}}}
- This operation extends the current path from the current point, let us call
- it $x$, via a curve to a point~$y$ (if, instead of a coordinate you say
- |cycle| at the end, $y$ will be the coordinate of the last move-to
- operation). The curve is a cubic Bézier curve. For such a curve, apart
- from $y$, you also specify two control points $c$ and $d$. The idea is that
- the curve starts at $x$, ``heading'' in the direction of~$c$.
- Mathematically spoken, the tangent of the curve at $x$ goes through $c$.
- Similarly, the curve ends at $y$, ``coming from'' the other control
- point,~$d$. The larger the distance between $x$ and~$c$ and between $d$
- and~$y$, the larger the curve will be.
-
- If the ``|and|\meta{d}'' part is not given, $d$ is assumed to be equal to
- $c$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[line width=10pt] (0,0) .. controls (1,1) .. (4,0)
- .. controls (5,0) and (5,1) .. (4,1);
- \draw[color=gray] (0,0) -- (1,1) -- (4,0) -- (5,0) -- (5,1) -- (4,1);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[line width=10pt] (0,0) -- (2,0) .. controls (1,1) .. cycle;
-\end{tikzpicture}
-\end{codeexample}
-
- As with the line-to operation, it makes a difference whether two curves are
- joined because they resulted from consecutive curve-to or line-to
- operations, or whether they just happen to have a common (end) point:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[line width=10pt]
- \draw (0,0) -- (1,1) (1,1) .. controls (1,0) and (2,0) .. (2,0);
- \draw [yshift=-1.5cm]
- (0,0) -- (1,1) .. controls (1,0) and (2,0) .. (2,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{pathoperation}
-
-
-\subsection{The Rectangle Operation}
-
-A rectangle can obviously be created using four straight lines and a cycle
-operation. However, since rectangles are needed so often, a special syntax is
-available for them.
-
-\begin{pathoperation}{rectangle}{\meta{corner or cycle}}
- When this operation is used, one corner will be the current point, another
- corner is given by \meta{corner}, which becomes the new current point.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) rectangle (1,1);
- \draw (.5,1) rectangle (2,0.5) (3,0) rectangle (3.5,1.5) -- (2,0);
-\end{tikzpicture}
-\end{codeexample}
-
- Just for consistency, you can also use |cycle| instead of a coordinate, but
- it is a bit unclear what use this might have.
-\end{pathoperation}
-
-
-\subsection{Rounding Corners}
-
-All of the path construction operations mentioned up to now are influenced by
-the following option:
-
-\begin{key}{/tikz/rounded corners=\meta{inset} (default 4pt)}
- When this option is in force, all corners (places where a line is continued
- either via line-to or a curve-to operation) are replaced by little arcs so
- that the corner becomes smooth.
- %
-\begin{codeexample}[]
-\tikz \draw [rounded corners] (0,0) -- (1,1)
- -- (2,0) .. controls (3,1) .. (4,0);
-\end{codeexample}
-
- The \meta{inset} describes how big the corner is. Note that the
- \meta{inset} is \emph{not} scaled along if you use a scaling option like
- |scale=2|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[color=gray,very thin] (10pt,15pt) circle[radius=10pt];
- \draw[rounded corners=10pt] (0,0) -- (0pt,25pt) -- (40pt,25pt);
-\end{tikzpicture}
-\end{codeexample}
-
- You can switch the rounded corners on and off ``in the middle of path'' and
- different corners in the same path can have different corner radii:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) [rounded corners=10pt] -- (1,1) -- (2,1)
- [sharp corners] -- (2,0)
- [rounded corners=5pt] -- cycle;
-\end{tikzpicture}
-\end{codeexample}
-
- Here is a rectangle with rounded corners:
- %
-\begin{codeexample}[]
-\tikz \draw[rounded corners=1ex] (0,0) rectangle (20pt,2ex);
-\end{codeexample}
-
- You should be aware, that there are several pitfalls when using this
- option. First, the rounded corner will only be an arc (part of a circle) if
- the angle is $90^\circ$. In other cases, the rounded corner will still be
- round, but ``not as nice''.
-
- Second, if there are very short line segments in a path, the ``rounding''
- may cause inadvertent effects. In such case it may be necessary to
- temporarily switch off the rounding using |sharp corners|.
-\end{key}
-
-\begin{key}{/tikz/sharp corners}
- This options switches off any rounding on subsequent corners of the path.
-\end{key}
-
-
-\subsection{The Circle and Ellipse Operations}
-
-Circles and ellipses are common path elements for which there is a special path
-operation.
-
-\begin{pathoperation}{circle}{\opt{|[|\meta{options}|]|}}
- This command adds a circle to the current path where the center of the
- circle is the current point by default, but you can use the |at| option to
- change this. The new current point of the path will be (typically just
- remain) the center of the circle.
-
- The radius of the circle is specified using the following options:
- %
- \begin{key}{/tikz/x radius=\meta{value}}
- Sets the horizontal radius of the circle (which, when this value is
- different form the vertical radius, is actually an ellipse). The
- \meta{value} may either be a dimension or a dimensionless number. In
- the latter case, the number is interpreted in the $xy$-coordinate
- system (if the $x$-unit is set to, say, |2cm|, then |x radius=3| will
- have the same effect as |x radius=6cm|).
- \end{key}
- %
- \begin{key}{/tikz/y radius=\meta{value}}
- Works like the |x radius|.
- \end{key}
- %
- \begin{key}{/tikz/radius=\meta{value}}
- Sets the |x radius| and |y radius| simultaneously.
- \end{key}
- %
- \begin{key}{/tikz/at=\meta{coordinate}}
- If this option is explicitly set inside the \meta{options} (or
- indirectly via the |every circle| style), the \meta{coordinate} is used
- as the center of the circle instead of the current point. Setting |at|
- to some value in an enclosing scope has no effect.
- \end{key}
- The \meta{options} may also contain additional options like, say, a
- |rotate| or |scale|, that will only have an effect on the circle.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (1,0) circle [radius=1.5];
- \fill (1,0) circle [x radius=1cm, y radius=5mm, rotate=30];
-\end{tikzpicture}
-\end{codeexample}
-
- It is possible to set the |radius| also in some enclosing scope, in this
- case the options can be left out (but see the note below on what may
- follow):
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[radius=2pt]
- \draw (0,0) circle -- (1,1) circle -- ++(0,1) circle;
-\end{tikzpicture}
-\end{codeexample}
-
- The following style is used with every circle:
- %
- \begin{stylekey}{/tikz/every circle}
- You can use this key to set up, say, a default radius for every circle.
- The key will also be used with the |ellipse| operation.
- \end{stylekey}
-
- In case you feel that the names |radius| and |x radius| are too long for
- your taste, you can easily created shorter aliases:
- %
-\begin{codeexample}[code only]
-\tikzset{r/.style={radius=#1},rx/.style={x radius=#1},ry/.style={y radius=#1}}
-\end{codeexample}
- %
- You can then say |circle [r=1cm]| or |circle [rx=1,ry=1.5]|. The reason
- \tikzname\ uses the longer names by default is that it encourages people to
- write more readable code.
-
- \emph{Note:} There also exists an older syntax for circles, where the
- radius of the circle is given in parentheses right after the |circle|
- command as in |circle (1pt)|. Although this syntax is a bit more succinct,
- it is harder to understand for readers of the code and the use of
- parentheses for something other than a coordinate is ill-chosen.
-
- \tikzname\ will use the following rule to determine whether the old or the
- normal syntax is used: If |circle| is directly followed by something that
- (expands to) an opening parenthesis, then the old syntax is used and inside
- these following parentheses there must be a single number or dimension
- representing a radius. In all other cases the new syntax is used.
-\end{pathoperation}
-
-\begin{pathoperation}{ellipse}{|[|\meta{options}|]|}
- This command has exactly the same effect as |circle|. The older syntax for
- this command is |ellipse (|\meta{x radius} |and| \meta{y radius}|)|. As for
- the |circle| command, this syntax is not as good as the standard syntax.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
- \draw (1,1) ellipse [x radius=1cm,y radius=.5cm];
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{pathoperation}
-
-
-\subsection{The Arc Operation}
-
-The \emph{arc operation} allows you to add an arc to the current path.
-%
-\begin{pathoperation}{arc}{\oarg{options}}
- The |arc| operation adds a part of an ellipse to the current path. The
- radii of the ellipse are given by the values of |x radius| and |y radius|,
- which should be set in the \meta{options}. The arc will start at the
- current point and will end at the end of the arc. The arc will start and
- end at angles computed from the three keys |start angle|, |end angle|, and
- |delta angle|. Normally, the first two keys specify the start and end
- angle. However, in case one of them is empty, it is computed from the other
- key plus or minus the |delta angle|. In detail, if |end angle| is empty, it
- is set to the start angle plus the delta angle. If the start angle is
- missing, it is set to the end angle minus the delta angle. If all three
- keys are set, the delta angle is ignored.
- %
- \begin{key}{/tikz/start angle=\meta{degrees}}
- Sets the start angle.
- \end{key}
- %
- \begin{key}{/tikz/end angle=\meta{degrees}}
- Sets the end angle.
- \end{key}
- %
- \begin{key}{/tikz/delta angle=\meta{degrees}}
- Sets the delta angle.
- \end{key}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[radius=1cm]
- \draw (0,0) arc[start angle=180, end angle=90]
- -- (2,.5) arc[start angle=90, delta angle=-90];
- \draw (4,0) -- +(30:1cm)
- arc [start angle=30, delta angle=30] -- cycle;
- \draw (8,0) arc [start angle=0, end angle=270,
- x radius=1cm, y radius=5mm] -- cycle;
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[radius=1cm,delta angle=30]
- \draw (-1,0) -- +(3.5,0);
- \draw (1,0) ++(210:2cm) -- +(30:4cm);
- \draw (1,0) +(0:1cm) arc [start angle=0];
- \draw (1,0) +(180:1cm) arc [start angle=180];
- \path (1,0) ++(15:.75cm) node{$\alpha$};
- \path (1,0) ++(15:-.75cm) node{$\beta$};
-\end{tikzpicture}
-\end{codeexample}
-
- There also exists a shorter syntax for the arc operation, namely |arc|
- begin directly followed by
- |(|\meta{start angle}|:|\meta{end angle}|:|\meta{radius}). However, this
- syntax is harder to read, so the normal syntax should be preferred in
- general.
-\end{pathoperation}
-
-
-\subsection{The Grid Operation}
-
-You can add a grid to the current path using the |grid| path operation.
-
-\begin{pathoperation}{grid}{\opt{\oarg{options}}\meta{corner or cycle}}
- This operations adds a grid filling a rectangle whose two corners are given
- by \meta{corner} and by the previous coordinate. (Instead of a coordinate
- you can also say |cycle| to use the position of the last move-to as the
- corner coordinate, but it not very natural to do so.) Thus, the
- typical way in which a grid is drawn is |\draw (1,1) grid (3,3);|, which
- yields a grid filling the rectangle whose corners are at $(1,1)$ and
- $(3,3)$. All coordinate transformations apply to the grid.
- %
-\begin{codeexample}[]
-\tikz[rotate=30] \draw[step=1mm] (0,0) grid (2,2);
-\end{codeexample}
-
- The \meta{options}, which are local to the |grid| operation, can be used to
- influence the appearance of the grid. The stepping of the grid is governed
- by the following options:
- %
- \begin{key}{/tikz/step=\meta{number or dimension or coordinate} (initially 1cm)}
- Sets the stepping in both the $x$ and $y$-direction. If a dimension is
- provided, this is used directly. If a number is provided, this number
- is interpreted in the $xy$-coordinate system. For example, if you
- provide the number |2|, then the $x$-step is twice the $x$-vector and
- the $y$-step is twice the $y$-vector set by the |x=| and |y=| options.
- Finally, if you provide a coordinate, then the $x$-part of this
- coordinate will be used as the $x$-step and the $y$-part will be used
- as the $y$-coordinate.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[x=.5cm]
- \draw[thick] (0,0) grid [step=1] (3,2);
- \draw[red] (0,0) grid [step=.75cm] (3,2);
-\end{tikzpicture}
-\begin{tikzpicture}
- \draw (0,0) circle [radius=1];
- \draw[blue] (0,0) grid [step=(45:1)] (3,2);
-\end{tikzpicture}
-\end{codeexample}
-
- A complication arises when the $x$- and/or $y$-vector do not point
- along the axes. Because of this, the actual rule for computing the
- $x$-step and the $y$-step is the following: As the $x$- and $y$-steps
- we use the $x$- and $y$-components or the following two vectors: The
- first vector is either $(\meta{x-grid-step-number},0)$ or
- $(\meta{x-grid-step-dimension},0\mathrm{pt})$, the second vector is
- $(0,\meta{y-grid-step-number})$ or
- $(0\mathrm{pt},\meta{y-grid-step-dimension})$.
-
- If the $x$-step or $y$-step is $0$ or negative the corresponding lines
- are not drawn.
- \end{key}
-
- \begin{key}{/tikz/xstep=\meta{dimension or number} (initially 1cm)}
- Sets the stepping in the $x$-direction.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) grid [xstep=.5,ystep=.75] (3,2);
- \draw[ultra thick] (0,0) grid [ystep=0] (3,2);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/ystep=\meta{dimension or number} (initially 1cm)}
- Sets the stepping in the $y$-direction.
- \end{key}
-
- It is important to note that the grid is always ``phased'' such that it
- contains the point $(0,0)$ if that point happens to be inside the
- rectangle. Thus, the grid does \emph{not} always have an intersection at
- the corner points; this occurs only if the corner points are multiples of
- the stepping. Note that due to rounding errors, the ``last'' lines of a
- grid may be omitted. In this case, you have to add an epsilon to the corner
- points.
-
- The following style is useful for drawing grids:
- %
- \begin{stylekey}{/tikz/help lines (initially {line width=0.2pt,gray})}
- This style makes lines ``subdued'' by using thin gray lines for them.
- However, this style is not installed automatically and you have to say
- for example:
- %
-\begin{codeexample}[]
-\tikz \draw[help lines] (0,0) grid (3,3);
-\end{codeexample}
- \end{stylekey}
-\end{pathoperation}
-
-
-\subsection{The Parabola Operation}
-
-The |parabola| path operation continues the current path with a parabola. A
-parabola is a (shifted and scaled) curve defined by the equation $f(x) = x^2$
-and looks like this: \tikz \draw (-1ex,1.5ex) parabola[parabola height=-1.5ex]
-+(2ex,0ex);.
-
-\begin{pathoperation}{parabola}{\opt{\oarg{options}|bend|\meta{bend
- coordinate}}\meta{coordinate or cycle}}
- This operation adds a parabola through the current point and the given
- \meta{coordinate} or, if |cycle| is used instead of coordinate at the end,
- the \meta{coordinate} is set to the position of the last move-to and the
- path gets closed after the parabola. If the |bend| is given, it specifies
- where the bend should go; the \meta{options} can also be used to specify
- where the bend is. By default, the bend is at the old current point.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) rectangle (1,1.5)
- (0,0) parabola (1,1.5);
- \draw[xshift=1.5cm] (0,0) rectangle (1,1.5)
- (0,0) parabola[bend at end] (1,1.5);
- \draw[xshift=3cm] (0,0) rectangle (1,1.5)
- (0,0) parabola bend (.75,1.75) (1,1.5);
-
- \draw[yshift=-2cm] (1,1.5) --
- (0,0) parabola cycle;
-\end{tikzpicture}
-\end{codeexample}
-
- The following options influence parabolas:
- %
- \begin{key}{/tikz/bend=\meta{coordinate}}
- Has the same effect as saying |bend|\meta{coordinate} outside the
- \meta{options}. The option specifies that the bend of the parabola
- should be at the given \meta{coordinate}. You have to take care
- yourself that the bend position is a ``valid'' position; which means
- that if there is no parabola of the form $f(x) = a x^2 + b x + c$ that
- goes through the old current point, the given bend, and the new current
- point, the result will not be a parabola.
-
- There is one special property of the \meta{coordinate}: When a relative
- coordinate is given like |+(0,0)|, the position relative to this
- coordinate is ``flexible''. More precisely, this position lies
- somewhere on a line from the old current point to the new current
- point. The exact position depends on the next option.
- \end{key}
-
- \begin{key}{/tikz/bend pos=\meta{fraction}}
- Specifies where the ``previous'' point is relative to which the bend is
- calculated. The previous point will be at the \meta{fraction}th part of
- the line from the old current point to the new current point.
-
- The idea is the following: If you say |bend pos=0| and |bend +(0,0)|,
- the bend will be at the old current point. If you say |bend pos=1| and
- |bend +(0,0)|, the bend will be at the new current point. If you say
- |bend pos=0.5| and |bend +(0,2cm)| the bend will be 2cm above the
- middle of the line between the start and end point. This is most useful
- in situations such as the following:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (-1,0) parabola[bend pos=0.5] bend +(0,2) +(3,0);
-\end{tikzpicture}
-\end{codeexample}
-
- In the above example, the |bend +(0,2)| essentially means ``a parabola
- that is 2cm high'' and |+(3,0)| means ``and 3cm wide''. Since this
- situation arises often, there is a special shortcut option:
- %
- \begin{key}{/tikz/parabola height=\meta{dimension}}
- This option has the same effect as
- |[bend pos=0.5,bend={+(0pt,|\meta{dimension}|)}]|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (-1,0) parabola[parabola height=2cm] +(3,0);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
- \end{key}
-
- The following styles are useful shortcuts:
- %
- \begin{stylekey}{/tikz/bend at start}
- This places the bend at the start of a parabola. It is a shortcut for
- the following options: |bend pos=0,bend={+(0,0)}|.
- \end{stylekey}
-
- \begin{stylekey}{/tikz/bend at end}
- This places the bend at the end of a parabola.
- \end{stylekey}
-\end{pathoperation}
-
-
-\subsection{The Sine and Cosine Operation}
-
-The |sin| and |cos| operations are similar to the |parabola| operation. They,
-too, can be used to draw (parts of) a sine or cosine curve.
-
-\begin{pathoperation}{sin}{\meta{coordinate or cycle}}
- The effect of |sin| is to draw a scaled and shifted version of a sine curve
- in the interval $[0,\pi/2]$. The scaling and shifting is done in such a way
- that the start of the sine curve in the interval is at the old current
- point and that the end of the curve in the interval is at
- \meta{coordinate}. Here is an example that should clarify this:
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) rectangle (1,1) (0,0) sin (1,1)
- (2,0) rectangle +(1.57,1) (2,0) sin +(1.57,1);
-\end{codeexample}
- %
-\end{pathoperation}
-
-\begin{pathoperation}{cos}{\meta{coordinate or cycle}}
- This operation works similarly, only a cosine in the interval $[0,\pi/2]$
- is drawn. By correctly alternating |sin| and |cos| operations, you can
- create a complete sine or cosine curve:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[xscale=1.57]
- \draw (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0) sin (5,1);
- \draw[color=red] (0,1.5) cos (1,0) sin (2,-1.5) cos (3,0) sin (4,1.5) cos (5,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{pathoperation}
-
-Note that there is no way to (conveniently) draw an interval on a sine or
-cosine curve whose end points are not multiples of $\pi/2$.
-
-
-\subsection{The SVG Operation}
-
-The |svg| operation can be used to extend the current path by a path given in
-the \textsc{svg} path data syntax. This syntax is described in detail in
-Section~8.3 of the \textsc{svg 1.1} specification, please consult this
-specification for details.
-
-\begin{pathoperation}{svg}{\opt{\oarg{options}}\marg{path data}}
- This operation adds the path specified in the \meta{path data} in
- \textsc{svg 1.1 path data} syntax to the current path. Unlike the
- \textsc{svg}-specification, it \emph{is} permissible that the path data
- does not start with a move-to command (|m| or |M|), in which case the last
- point of the current path is used as start point. The optional
- \meta{options} apply locally to this path operation, typically you will use
- them to set up, say, some transformations.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{svg.path}}]
-\begin{tikzpicture}
- \filldraw [fill=red!20] (0,1) svg[scale=2] {h 10 v 10 h -10}
- node [above left] {upper left} -- cycle;
-
- \draw svg {M 0 0 L 20 20 h 10 a 10 10 0 0 0 -20 0};
-\end{tikzpicture}
-\end{codeexample}
-
- An \textsc{svg} coordinate like |10 20| is always interpreted as
- |(10pt,20pt)|, so the basic unit is always points (|pt|). The
- $xy$-coordinate system is not used. However, you can use scaling to
- (locally) change the basic unit. For instance, |svg[scale=1cm]| (yes, this
- works, although some rather evil magic is involved) will cause 1cm to be
- the basic unit.
-
- Instead of curly braces, you can also use quotation marks to indicate the
- start and end of the \textsc{svg} path.
-
- \emph{Warning:} The arc operations (|a| and |A|) are numerically instable.
- This means that they will be quite imprecise, except when the angle is a
- multiple of $90^\circ$ (as is, fortunately, most often the case).
-\end{pathoperation}
-
-
-\subsection{The Plot Operation}
-
-The |plot| operation can be used to append a line or curve to the path that
-goes through a large number of coordinates. These coordinates are either given
-in a simple list of coordinates, read from some file, or they are computed on
-the fly.
-
-Since the syntax and the behavior of this command are a bit complex, they are
-described in the separated Section~\ref{section-tikz-plots}.
-
-
-\subsection{The To Path Operation}
-
-The |to| operation is used to add a user-defined path from the previous
-coordinate to the following coordinate. When you write |(a) to (b)|, a straight
-line is added from |a| to |b|, exactly as if you had written |(a) -- (b)|.
-However, if you write |(a) to [out=135,in=45] (b)| a curve is added to the
-path, which leaves at an angle of 135$^\circ$ at |a| and arrives at an angle of
-45$^\circ$ at |b|. This is because the options |in| and |out| trigger a special
-path to be used instead of the straight line.
-
-\begin{pathoperation}{to}{\opt{|[|\meta{options}|]|}
- \opt{\meta{nodes}} \meta{coordinate or cycle}}
- This path operation inserts the path currently set via the |to path| option
- at the current position. The \meta{options} can be used to modify (perhaps
- implicitly) the |to path| and to set up how the path will be rendered.
-
- Before the |to path| is inserted, a number of macros are set up that can
- ``help'' the |to path|. These are |\tikztostart|, |\tikztotarget|, and
- |\tikztonodes|; they are explained in the following.
-
- \medskip
- \textbf{Start and Target Coordinates.}\ \
- The |to| operation is always followed by a \meta{coordinate}, called the
- target coordinate, or the text |cycle|, in which case the last move-to is
- used as a coordinate and the path gets closed. The macro |\tikztotarget| is
- set to this coordinate (without its parentheses). There is also a
- \emph{start coordinate}, which is the coordinate preceding the |to|
- operation. This coordinate can be accessed via the macro |\tikztostart|. In
- the following example, for the first |to|, the macro |\tikztostart| is
- |0pt,0pt| and the |\tikztotarget| is |0,2|. For the second |to|, the macro
- |\tikztostart| is |10pt,10pt| and |\tikztotarget| is |a|. For the third,
- they are set to |a| and |current subpath start|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \node (a) at (2,2) {a};
-
- \draw (0,0) to (0,2);
- \draw[red] (10pt,10pt) to (a);
- \draw[blue] (3,0) -- (3,2) -- (a) to cycle;
-\end{tikzpicture}
-\end{codeexample}
-
- \medskip
- \textbf{Nodes on to--paths.}\ \
- It is possible to add nodes to the paths constructed by a |to| operation.
- To do so, you specify the nodes between the |to| keyword and the coordinate
- (if there are options to the |to| operation, these come first). The effect
- of |(a) to node {x} (b)| (typically) is the same as if you had written
- |(a) -- node {x} (b)|, namely that the node is placed on the |to|. This can
- be used to add labels to |to|s:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) to node [sloped,above] {x} (3,2);
-
- \draw (0,0) to[out=90,in=180] node [sloped,above] {x} (3,2);
-\end{tikzpicture}
-\end{codeexample}
-
- Instead of writing the node between the |to| keyword and the target
- coordinate, you may also use the following keys to create such nodes:
- %
- \begin{key}{/tikz/edge node=\meta{node specification}}
- This key can be used inside the \meta{options} of a |to| path command.
- It will add the \meta{node specification} to the list of nodes to be
- placed on the connecting line, just as if you had written the
- \meta{node specification} directly after the |to| keyword:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) to [edge node={node [sloped,above] {x}}] (3,2);
-
- \draw (0,0) to [out=90,in=180,
- edge node={node [sloped,above] {x}}] (3,2);
-\end{tikzpicture}
-\end{codeexample}
- %
- This key is mostly useful to create labels automatically using other
- keys.
- \end{key}
- %
- \begin{key}{/tikz/edge label=\meta{text}}
- A shorthand for |edge node={node[auto]{|\meta{text}|}}|.
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) to [edge label=x] (3,2);
-\end{codeexample}
- \end{key}
- %
- \begin{key}{/tikz/edge label'=\meta{text}}
- A shorthand for |edge node={node[auto,swap]{|\meta{text}|}}|.
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) to [edge label=x, edge label'=y] (3,2);
-\end{codeexample}
- \end{key}
-
- When the |quotes| library is loaded, additional ways of specifying nodes on
- to--paths become available, see Section~\ref{section-edge-quotes}.
-
- \medskip
- \textbf{Styles for to-paths.}\ \
- In addition to the \meta{options} given after the |to| operation, the
- following style is also set at the beginning of the to path:
- %
- \begin{stylekey}{/tikz/every to (initially \normalfont empty)}
- This style is installed at the beginning of every to.
- %
-\begin{codeexample}[]
-\tikz[every to/.style={bend left}]
- \draw (0,0) to (3,2);
-\end{codeexample}
- %
- Note that, as explained below, every to path is implicitly surrounded
- by curly braces. This means that options like |draw| given in an
- |every to| do not actually influence the path. You can fix this by
- using the |append after command| option:
- %
-\begin{codeexample}[]
-\tikz[every to/.style={append after command={[draw,dashed]}}]
- \draw (0,0) to (3,2);
-\end{codeexample}
- \end{stylekey}
-
- \medskip
- \textbf{Options.}\ \
- The \meta{options} given with the |to| allow you to influence the
- appearance of the |to path|. Mostly, these options are used to change the
- |to path|. This can be used to change the path from a straight line to,
- say, a curve.
-
- The path used is set using the following option:
- %
- \begin{key}{/tikz/to path=\meta{path}}
- Whenever a |to| operation is used, the \meta{path} is inserted. More
- precisely, the following path is added:
- %
- \begin{quote}
- |{[every to,|\meta{options}|] |\meta{path} |}|
- \end{quote}
-
- The \meta{options} are the options given to the |to| operation, the
- \meta{path} is the path set by this option |to path|.
-
- Inside the \meta{path}, different macros are used to reference the
- from- and to-coordinates. In detail, these are:
- %
- \begin{itemize}
- \item \declareandlabel{\tikztostart} will expand to the
- from-coordinate (without the parentheses).
- \item \declareandlabel{\tikztotarget} will expand to the
- to-coordinate.
- \item \declareandlabel{\tikztonodes} will expand to the nodes
- between the |to| operation and the coordinate. Furthermore,
- these nodes will have the |pos| option set implicitly.
- \end{itemize}
-
- Let us have a look at a simple example. The standard straight line for
- a |to| is achieved by the following \meta{path}:
- %
- \begin{quote}
- |-- (\tikztotarget) \tikztonodes|
- \end{quote}
-
- Indeed, this is the default setting for the path. When we write
- |(a) to (b)|, the \meta{path} will expand to |(a) -- (b)|, when we
- write
- %
- \begin{quote}
- |(a) to[red] node {x} (b)|
- \end{quote}
- %
- the \meta{path} will expand to
- %
- \begin{quote}
- |(a) -- (b) node[red] {x}|
- \end{quote}
-
- It is not possible to specify the path
- %
- \begin{quote}
- |-- \tikztonodes (\tikztotarget)|
- \end{quote}
- %
- since \tikzname\ does not allow one to have a macro after |--| that
- expands to a node.
-
- Now let us have a look at how we can modify the \meta{path} sensibly.
- The simplest way is to use a curve.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[to path={
- .. controls +(1,0) and +(1,0) .. (\tikztotarget) \tikztonodes}]
-
- \node (a) at (0,0) {a};
- \node (b) at (2,1) {b};
- \node (c) at (1,2) {c};
-
- \draw (a) to node {x} (b)
- (a) to (c);
-\end{tikzpicture}
-\end{codeexample}
-
- Here is another example:
- %
-\begin{codeexample}[]
-\tikzset{
- my loop/.style={to path={
- .. controls +(80:1) and +(100:1) .. (\tikztotarget) \tikztonodes}},
- my state/.style={circle,draw}}
-
-\begin{tikzpicture}[shorten >=2pt]
- \node [my state] (a) at (210:1) {$q_a$};
- \node [my state] (b) at (330:1) {$q_b$};
-
- \draw[->] (a) to node[below] {1} (b)
- to [my loop] node[above right] {0} (b);
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{key}{/tikz/execute at begin to=\meta{code}}
- The \meta{code} is executed prior to the |to|. This can be used to
- draw one or more additional paths or to do additional computations.
- \end{key}
-
- \begin{key}{/tikz/execute at end to=\meta{code}}
- Works like the previous option, only this code is executed after
- the to path has been added.
- % FIXME : provide examples...
- \end{key}
-
- \begin{stylekey}{/tikz/every to (initially \normalfont empty)}
- This style is installed at the beginning of every to.
- \end{stylekey}
- \end{key}
-\end{pathoperation}
-
-There are a number of predefined |to path|s, see Section~\ref{library-to-paths}
-for a reference.
-
-
-\subsection{The Foreach Operation}
-
-\begin{pathoperation}{foreach}{\meta{variables}\opt{\oarg{options}} |in|
- \marg{path commands}}
- The |foreach| operation can be used to repeatedly insert the \meta{path
- commands} into the current path. Naturally, the \meta{path commands} should
- internally reference some of the \meta{variables} so that you do not insert
- exactly the same path repeatedly, but rather variations. For historical
- reasons, you can also write |\foreach| instead of |foreach|.
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) foreach \x in {1,...,3} { -- (\x,1) -- (\x,0) };
-\end{codeexample}
- %
- See Section~\ref{section-foreach} for more details on the for-each-command.
-\end{pathoperation}
-
-
-\subsection{The Let Operation}
-
-The \emph{let operation} is the first of a number of path operations that do
-not actually extend that path, but have different, mostly local, effects.
-It requires the |calc| library, see Section~\ref{tikz-lib-calc}.
-
-\begin{pathoperation}{let}{\meta{assignment}
- \opt{|,|\meta{assignment}}%
- \opt{|,|\meta{assignment}\dots}\declare{| in |}}
- When this path operation is encountered, the \meta{assignment}s are
- evaluated, one by one. This will store coordinate and number in
- special \emph{registers} (which are local to \tikzname, they have
- nothing to do with \TeX\ registers). Subsequently, one can access the
- contents of these registers using the macros |\p|, |\x|, |\y|, and
- |\n|.
-
- The first kind of permissible \meta{assignment}s have the following form:
- %
- \begin{quote}
- |\n|\meta{number register}|={|\meta{formula}|}|
- \end{quote}
- %
- When an assignment has this form, the \meta{formula} is evaluated using the
- |\pgfmathparse| operation. The result is stored in the \meta{number
- register}. If the \meta{formula} involves a dimension anywhere (as in
- |2*3cm/2|), then the \meta{number register} stores the resulting dimension
- with a trailing |pt|. A \meta{number register} can be named arbitrarily
- and is a normal \TeX\ parameter to the |\n| macro. Possible names are
- |{left corner}|, but also just a single digit like~|5|.
-
- Let us call the path that follows a let operation its \emph{body}. Inside
- the body, the |\n| macro can be used to access the register.
- %
- \begin{command}{\n\marg{number register}}
- When this macro is used on the left-hand side of an |=|-sign in a let
- operation, it has no effect and is just there for readability. When the
- macro is used on the right-hand side of an |=|-sign or in the body of
- the let operation, then it expands to the value stored in the
- \meta{number register}. This will either be a dimensionless number like
- |2.0| or a dimension like |5.6pt|.
-
- For instance, if we say |let \n1={1pt+2pt}, \n2={1+2} in ...|, then
- inside the |...| part the macro |\n1| will expand to |3pt| and |\n2|
- expands to |3|.
- \end{command}
-
- The second kind of \meta{assignments} have the following form:
- %
- \begin{quote}
- |\p|\meta{point register}|=|\meta{coordinate}
- \end{quote}
- %
- Point position registers store a single point, consisting of an $x$-part
- and a $y$-part measured in \TeX\ points (|pt|). In particular, point
- registers do not store nodes or node names. Here is an example:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \draw let \p{foo} = (1,1), \p2 = (2,0) in
- (0,0) -- (\p2) -- (\p{foo});
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{command}{\p\marg{point register}}
- When this macro is used on the left-hand side of an |=|-sign in a let
- operation, it has no effect and is just there for readability. When the
- macro is used on the right-hand side of an |=|-sign or in the body of
- the let operation, then it expands to the $x$-part (measured in \TeX\
- points) of the coordinate stored in the \meta{register}, followed, by a
- comma, followed by the $y$-part.
-
- For instance, if we say |let \p1=(1pt,1pt+2pt) in ...|, then inside the
- |...| part the macro |\p1| will expand to exactly the seven characters
- ``1pt,3pt''. This means that you when you write |(\p1)|, this expands
- to |(1pt,3pt)|, which is presumably exactly what you intended.
- \end{command}
- %
- \begin{command}{\x\marg{point register}}
- This macro expands just to the $x$-part of the point register. If we
- say as above, as we did above, |let \p1=(1pt,1pt+2pt) in ...|, then
- inside the |...| part the macro |\x1| expands to |1pt|.
- \end{command}
- %
- \begin{command}{\y\marg{point register}}
- Works like |\x|, only for the $y$-part.
- \end{command}
- %
- Note that the above macros are available only inside a let operation.
-
- Here is an example where let clauses are used to assemble a coordinate from
- the $x$-coordinate of a first point and the $y$-coordinate of a second
- point. Naturally, using the \verb!|-! notation, this could be written much
- more compactly.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \draw (1,0) coordinate (first point)
- -- (3,2) coordinate (second point);
-
- \fill[red] let \p1 = (first point),
- \p2 = (second point) in
- (\x1,\y2) circle [radius=2pt];
-\end{tikzpicture}
-\end{codeexample}
-
- Note that the effect of a let operation is local to the body of the let
- operation. If you wish to access a computed coordinate outside the body,
- you must use a |coordinate| path operation:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,2);
-
- \path % let's define some points:
- let
- \p1 = (1,0),
- \p2 = (3,2),
- \p{center} = ($ (\p1) !.5! (\p2) $) % center
- in
- coordinate (p1) at (\p1)
- coordinate (p2) at (\p2)
- coordinate (center) at (\p{center});
-
- \draw (p1) -- (p2);
- \fill[red] (center) circle [radius=2pt];
-\end{tikzpicture}
-\end{codeexample}
-
- For a more useful application of the let operation, let us draw a circle
- that touches a given line:
- %
-\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \draw [help lines] (0,0) grid (3,3);
-
- \coordinate (a) at (rnd,rnd);
- \coordinate (b) at (3-rnd,3-rnd);
- \draw (a) -- (b);
-
- \node (c) at (1,2) {x};
-
- \draw let \p1 = ($ (a)!(c)!(b) - (c) $),
- \n1 = {veclen(\x1,\y1)}
- in circle [at=(c), radius=\n1];
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{pathoperation}
-
-
-\subsection{The Scoping Operation}
-
-When \tikzname\ encounters and opening or a closing brace (|{| or~|}|) at some
-point where a path operation should come, it will open or close a scope. All
-options that can be applied ``locally'' will be scoped inside the scope. For
-example, if you apply a transformation like |[xshift=1cm]| inside the scoped
-area, the shifting only applies to the scope. On the other hand, an option like
-|color=red| does not have any effect inside a scope since it can only be
-applied to the path as a whole.
-
-Concerning the effect of scopes on relative coordinates, please see
-Section~\ref{section-scopes-relative}.
-
-
-\subsection{The Node and Edge Operations}
-
-The |node| operation adds a so-called node to a path. This operation is special
-in the following sense: It does not change the current path in any way. In
-other words, this operation is not really a path operation, but has an effect
-that is ``external'' to the path. The |edge| operation has similar effect in
-that it adds something \emph{after} the main path has been drawn. However, it
-works like the |to| operation, that is, it adds a |to| path to the picture
-after the main path has been drawn.
-
-Since these operations are quite complex, they are described in the separate
-Section~\ref{section-nodes}.
-
-
-\subsection{The Graph Operation}
-
-The |graph| operation can be used to specify easily how a large number of nodes
-are connected. This operation is documented in a separate section, see
-Section~\ref{section-library-graphs}.
-
-
-\subsection{The Pic Operation}
-
-The |pic| operation is used to insert a ``short picture'' (hence the ``short''
-name) at the current position of the path. This operation is somewhat similar
-to the |node| operation and discussed in detail in Section~\ref{section-pics}.
-
-
-\subsection{The Attribute Animation Operation}
-
-\begin{pathoperation}{:}{\meta{animation attribute}|=|\marg{options}}
- This path operation has the same effect as if you had said:
- %
- \begin{quote}
- |[animate = { myself:|\meta{animate attribute}|=|\marg{options}|} ]|
- \end{quote}
- %
- This causes an animation of \meta{animate attribute} to be added to the
- current path, see Section~\ref{section-tikz-animations} for details.
- %
-\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{animations}}]
-\tikz \draw :xshift = {0s = "0cm", 30s = "-3cm", repeats} (0,0) circle (5mm);
-\end{codeexample}
- %
-\end{pathoperation}
-
-
-\subsection{The PGF-Extra Operation}
-
-In some cases you may need to ``do some calculations or some other stuff''
-while a path is constructed. For this, you would like to suspend the
-construction of the path and suspend \tikzname's parsing of the path, you would
-then like to have some \TeX\ code executed, and would then like to resume the
-parsing of the path. This effect can be achieved using the following path
-operation |\pgfextra|. Note that this operation should only be used by real
-experts and should only be used deep inside clever macros, not on normal paths.
-
-\begin{command}{\pgfextra\marg{code}}
- This command may only be used inside a \tikzname\ path. There it is used
- like a normal path operation. The construction of the path is temporarily
- suspended and the \meta{code} is executed. Then, the path construction is
- resumed.
- %
-\begin{codeexample}[]
-\newdimen\mydim
-\begin{tikzpicture}
- \mydim=1cm
- \draw (0pt,\mydim) \pgfextra{\mydim=2cm} -- (0pt,\mydim);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-\begin{command}{\pgfextra \meta{code} \texttt{\char`\\endpgfextra}}
- This is an alternative syntax for the |\pgfextra| command. If the code
- following |\pgfextra| does not start with a brace, the \meta{code} is
- executed until |\endpgfextra| is encountered. What actually happens is that
- when |\pgfextra| is not followed by a brace, this completely shuts down the
- \tikzname\ parser and |\endpgfextra| is a normal macro that restarts the
- parser.
- %
-\begin{codeexample}[]
-\newdimen\mydim
-\begin{tikzpicture}
- \mydim=1cm
- \draw (0pt,\mydim)
- \pgfextra \mydim=2cm \endpgfextra -- (0pt,\mydim);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsection{Interacting with the Soft Path subsystem}
-
-During construction \tikzname\ stores the path internally as a \emph{soft
-path}. Sometimes it is desirable to save a path during the stage of
-construction, restore it elsewhere and continue using it. There are two keys to
-facilitate this operation, which are explained below. To learn more about the
-soft path subsystem, refer to section~\ref{section-soft-paths}.
-
-\begin{key}{/tikz/save path=\meta{macro}}
- Save the current soft path into \meta{macro}.
-\end{key}
-
-\begin{key}{/tikz/use path=\meta{macro}}
- Set the current path to the soft path stored in \meta{macro}.
-\end{key}
-
-\begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
-\begin{tikzpicture}
- \path[save path=\pathA,name path=A] (0,1) to [bend left] (1,0);
- \path[save path=\pathB,name path=B]
- (0,0) .. controls (.33,.1) and (.66,.9) .. (1,1);
-
- \fill[name intersections={of=A and B}] (intersection-1) circle (1pt);
-
- \draw[blue][use path=\pathA];
- \draw[red] [use path=\pathB];
-\end{tikzpicture}
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-pics.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-pics.tex
deleted file mode 100644
index 1e3645ab73..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-pics.tex
+++ /dev/null
@@ -1,645 +0,0 @@
-% 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{Pics: Small Pictures on Paths}
-\label{section-pics}
-
-\subsection{Overview}
-
-A ``pic'' is a ``short picture'' (hence the short name\dots) that can be
-inserted anywhere in \tikzname\ picture where you could also insert a node.
-Similarly to nodes, pics have a ``shape'' (called \emph{type} to avoid
-confusion) that someone has defined. Each time a pic of a specified type is
-used, the type's code is executed, resulting in some drawings to be added to
-the current picture. The syntax for adding nodes and adding pics to a picture
-are also very similar. The core difference is that pics are typically more
-complex than nodes and may consist of a whole bunch of nodes themselves
-together with complex paths joining them.
-
-As a very simple example, suppose we want to define a pic type |seagull| that
-just draw ``two bumps''. The code for this definition is quite easy:
-%
-\begin{codeexample}[code only]
-\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
- }
-}
-\end{codeexample}
-
-The first line just tells \TeX\ that you set some \tikzname\ options for the
-current scope (which is the whole document); you could put |seagull/.pic=...|
-anywhere else where \tikzname\ options are allowed (which is just about
-anywhere). We have now defined a |seagull| pic type and can use it as follows:
-%
-\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
- }
-}
-\begin{codeexample}[
- pre={\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
- },
-}}]
-\tikz \fill [fill=blue!20]
- (1,1)
- -- (2,2) pic {seagull}
- -- (3,2) pic {seagull}
- -- (3,1) pic [rotate=30] {seagull}
- -- (2,1) pic [red] {seagull};
-\end{codeexample}
-
-As can be see, defining new types of pics is much easier than defining new
-shapes for nodes; but see Section~\ref{section-new-pic-types} for the fine
-details.
-
-Since defining new pics types is easier than defining new node shapes and since
-using pics is as easy as using nodes, why should you use nodes at all? There
-are chiefly two reasons:
-%
-\begin{enumerate}
- \item Unlike nodes, pics cannot be referenced later on. You \emph{can}
- reference nodes that are inside a pic, but not ``the pic itself''. In
- particular, you cannot draw lines between pics the way you can draw
- them between nodes. In general, whenever it makes sense that some
- drawing could conceivably be connected to other node-like-things, then
- a node is better than a pic.
- \item If pics are used to emulate the full power of a node (which is
- possible, in principle), they will be slower to construct and take up
- more memory than a node achieving the same effect.
-\end{enumerate}
-
-Despite these drawbacks, pics are an excellent choice for creating highly
-configurable reusable pieces of drawings that can be inserted into larger
-contexts.
-
-
-\subsection{The Pic Syntax}
-
-\begin{command}{\pic}
- Inside |{tikzpicture}| this is an abbreviation for |\path pic|.
-\end{command}
-
-The syntax for adding a pic to a picture is very similar to the syntax used for
-nodes (indeed, internally the same parser code is used). The main difference is
-that instead of a node contents you provide the picture's type between the
-braces:
-
-\begin{pathoperation}{pic}{
- \opt{\meta{foreach statements}}
- \opt{|[|\meta{options}|]|}
- \opt{|(|\meta{prefix}|)|}
- \opt{|at(|\meta{coordinate}|)|}
- \opt{|:|\meta{animation attribute}|=|\marg{options}}
- \opt{\marg{pic type}}%
-}
- Adds a pic to the current \tikzname\ picture of the specified \meta{pic
- type}. The effect is, basically, that some code associated with the
- \meta{pic type} is executed (how this works, exactly, is explained later).
- This code can consist of arbitrary \tikzname\ code. As for nodes, the
- current path will not be modified by this path command, all drawings
- produced by the code are ``external'' to the path the same way neither a
- node nor its border are part of the path on which they are specified.
-
- Just like the |node| command, this path operation is somewhat complex and
- we go over it step by step.
-
- \medskip
- \textbf{Order of the parts of the specification.}
- Just like for nodes, everything between ``|pic|'' and the opening brace of
- the \meta{pic type} is optional and can be given in any order. If there are
- \meta{foreach statements}, they must come first, directly following
- ``|pic|''. As for nodes, the ``end'' of the pic specification is normally
- detected by the presence of the opening brace. You can, however, use the
- |pic type| option to specify the pic type as an option.
-
- \begin{key}{/tikz/pic type=\meta{pic type}}
- This key sets the pic type of the current~|pic|. When this option is
- used inside an option block of a |pic|, the parsing of the |pic| ends
- immediately and no pic type in braces is expected. (In other words,
- this option behaves exactly like the |node contents| option and,
- indeed, the two are interchangeable.)
- %
-\begin{codeexample}[
- pre={\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
- },
-}}]
-\tikz {
- \path (0,0) pic [pic type = seagull]
- (1,0) pic {seagull};
-}
-\end{codeexample}
- \end{key}
-
- \medskip
- \textbf{The location of a pic.}
- Just like nodes, pics are placed at the last position mentioned on the path
- or, when |at| is used, at a specified position. ``Placing'' a pic somewhere
- actually means that the coordinate system is translated (shifted) to this
- last position. This means that inside of the pic type's code any mentioning
- of the origin refers to the last position used on the path or to the
- specified |at|.
- %
-\begin{codeexample}[
- pre={\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
- },
-}}]
-\tikz { % different ways of placing pics
- \draw [help lines] (0,0) grid (3,2);
- \pic at (1,0) {seagull};
- \path (2,1) pic {seagull};
- \pic [at={(3,2)}] {seagull};
-}
-\end{codeexample}
-
- As for nodes, except for the described shifting, the coordinate system of a
- pic is reset prior to executing the pic type's code. This can be changed
- using the |transform shape| option, which has the same effect as for nodes:
- The ``outer'' transformation gets applied to the node:
- %
-\begin{codeexample}[
- pre={\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
- },
-}}]
-\tikz [scale=2] {
- \pic at (0,0) {seagull};
- \pic at (1,0) [transform shape] {seagull};
-}
-\end{codeexample}
-
- When the \meta{options} contain transformation commands like |scale| or
- |rotate|, these transformations always apply to the pic:
- %
-\begin{codeexample}[
- pre={\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
- },
-}}]
-\tikz [rotate=30] {
- \pic at (0,0) {seagull};
- \pic at (1,0) [rotate=90] {seagull};
-}
-\end{codeexample}
-
- Just like nodes, pics can also be positioned implicitly and, somewhat
- unsurprisingly, the same rules concerning positioning and sloping apply:
- %
-\begin{codeexample}[
- pre={\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
- },
-}}]
-\tikz \draw
- (0,0) to [bend left]
- pic [near start] {seagull}
- pic {seagull}
- pic [sloped, near end] {seagull} (4,0);
-\end{codeexample}
-
- \medskip
- \textbf{The options of a node.}
- As always, any given \meta{options} apply only to the pic and have no
- effect outside. As for nodes, most ``outside'' options also apply to the
- pics, but not the ``action'' options like |draw| or |fill|. These must be
- given in the \meta{options} of the pic.
-
- \medskip
- \textbf{The code of a pic.}
- As stated earlier, the main job of a pic is to execute some code in a scope
- that is shifted according to the last point on the path or to the |at|
- position specified in the pic. It was also claimed that this code is
- specified by the \meta{pic type}. However, this specification is somewhat
- indirect. What really happens is the following: When a |pic| is
- encountered, the current path is suspended and a new internal scope is
- started. The \meta{options} are executed and also the \meta{pic type} (as
- explained in a moment). After all this is done, the code stored in the
- following key gets executed:
-
- \begin{key}{/tikz/pics/code=\meta{code}}
- This key stores the \meta{code} that should be drawn in the current
- pic. Normally, setting this key is done by the \meta{pic type}, but you
- can also set it in the \meta{options} and leave the \meta{pic type}
- empty:
- %
-\begin{codeexample}[]
-\tikz \pic [pics/code={\draw (-3mm,0) to[bend left] (0,0)
- to[bend left] (3mm,0);}]
- {}; % no pic type specified
-\end{codeexample}
- \end{key}
-
- Now, how does the \meta{pic type} set |pics/code|? It turns out that the
- \meta{pic type} is actually just a list of keys that are executed with the
- prefix |/tikz/pics/|. In the above examples, this ``list of keys'' just
- consisted of the single key ``|seagull|'' that did not take any arguments,
- but, in principle, you could provide any arbitrary text understood by
- |\pgfkeys| here. This means that when we write |pic{seagull}|, \tikzname\
- will execute the key |/tikz/pics/seagull|. It turns out, see
- Section~\ref{section-new-pic-types}, that this key is just a style set to
- |code={\draw(-3mm,0)...;}|. Thus, |pic{seagull}| will cause the |pics/code|
- key to be set to the text needed to draw the
- seagull.
-
- Indeed, you can also use the \meta{pic type} simply to set the |code| of
- the pic. This is useful for cases when you have some code that you ``just
- want to execute, but do not want to define a new pic type''. Here is a
- typical example where we use pics to add some markings to a path:
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) .. controls(1,0) and (2,1) .. (3,1)
- foreach \t in {0, 0.1, ..., 1} {
- pic [pos=\t] {code={\draw circle [radius=2pt];}}
- };
-\end{codeexample}
-
- In our seagull example, we always explicitly used |\draw| to draw the
- seagull. This implies that when a user writes something
- |pic[fill]{seagull}| in the hope of having a ``filled'' seagull, nothing
- special will happen: The |\draw| inside the pic explicitly states that the
- path should be drawn, not filled, and the fact that in the surrounding
- scope the |fill| option is set has no effect. The following key can be used
- to change this:
- %
- \begin{key}{/tikz/pic actions}
- This key is a style that can be used (only) inside the code of a pic.
- There, it will set the ``action'' keys set inside the \meta{options} of
- the pic (``actions'' are drawing, filling, shading, and clipping or any
- combination thereof).
-
- To see how this key works, let us define the following pic:
- %
-\begin{codeexample}[code only]
-\tikzset{
- my pic/.pic = {
- \path [pic actions] (0,0) circle[radius=3mm];
- \draw (-3mm,-3mm) rectangle (3mm,3mm);
- }
-}
-\end{codeexample}
- %
- In the code, whether or not the circle gets drawn/filled/shaded
- depends on which options where given to the |pic| command when it
- is used. In contrast, the rectangle will always (just) be drawn.
- %
-\tikzset{
- my pic/.pic = {
- \path [pic actions] (0,0) circle[radius=3mm];
- \draw (-3mm,-3mm) rectangle (3mm,3mm);
- }
-}
-\begin{codeexample}[
- width=6cm,
- pre={\tikzset{
- my pic/.pic = {
- \path [pic actions] (0,0) circle[radius=3mm];
- \draw (-3mm,-3mm) rectangle (3mm,3mm);
- }
-}}]
-\tikz \pic {my pic}; \space
-\tikz \pic [red] {my pic}; \space
-\tikz \pic [draw] {my pic}; \space
-\tikz \pic [draw=red] {my pic}; \space
-\tikz \pic [draw, shading=ball] {my pic}; \space
-\tikz \pic [fill=red!50] {my pic};
-\end{codeexample}
- \end{key}
-
- \medskip
- \textbf{Code executed behind or in front of the path.}
- As for nodes, a pic can be ``behind'' the current path or ``in front of
- it'' and, just as for nodes, the two options |behind path| and
- |in front of path| are used to specify which is meant. In detail, if |node|
- and |pic| are both used repeatedly on a path, in the resulting picture we
- first see all nodes and pics with the |behind path| option set in the order
- they appear on the path (nodes and pics are interchangeable in this
- regard), then comes the path, and then come all nodes and pics that are in
- front of the path in the order they appeared.
- %
-\begin{codeexample}[
- pre={\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
- },
-}}]
-\tikz \fill [fill=blue!20]
- (1,1)
- -- (2,2) pic [behind path] {seagull}
- -- (3,2) pic {seagull}
- -- (3,1) pic [rotate=30] {seagull}
- -- (2,1) pic [red, behind path] {seagull};
-\end{codeexample}
- %
- In contrast to nodes, a pic need not only be completely behind the path or
- in front of the path as specified by the user. Instead, a pic type may also
- specify that a certain part of the drawing should always be behind the path
- and it may specify that a certain other part should always be before the
- path. For this, the values of the following keys are relevant:
-
- \begin{key}{/tikz/pics/foreground code=\meta{code}}
- This key stores \meta{code} that will always be drawn in front of the
- current path, even when |behind path| is used. If |behind path| is not
- used and |code| is (also) set, the code of |code| is drawn first,
- following by the foreground \meta{code}.
- \end{key}
-
- \begin{key}{/tikz/pics/background code=\meta{code}}
- Like |foreground code|, only that the \meta{code} is always put behind
- the path, except when the |behind path| option is applied to the pic,
- then the background code is drawn in front of the ``behind path'' code.
- \end{key}
-
- \medskip
- \textbf{The foreach statement for pics.}
- As for nodes, a pic specification may start with |foreach|. The effect and
- semantics are the same as for nodes.
- %
-\begin{codeexample}[
- pre={\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
- },
-}}]
-\tikz \pic foreach \x in {1,2,3} at (\x,0) {seagull};
-\end{codeexample}
-
- \medskip
- \textbf{Styles for pics.}
- The following styles influence how nodes are rendered:
- %
- \begin{stylekey}{/tikz/every pic (initially \normalfont empty)}
- This style is installed at the beginning of every pic.
- %
-\begin{codeexample}[
- pre={\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \draw (-3mm,0) to [bend left] (0,0) to [bend left] (3mm,0);
- },
-}}]
-\begin{tikzpicture}[every pic/.style={scale=2,transform shape}]
- \pic foreach \x in {1,2,3} at (\x,0) {seagull};
-\end{tikzpicture}
-\end{codeexample}
- \end{stylekey}
-
- \medskip
- \textbf{Name scopes.}
- You can specify a \meta{name} for a pic using the key |name=|\meta{name} or
- by giving the name in parenthesis inside the pic's specification. The
- effect of this is, for once, quite different from what happens for nodes:
- All that happens is that |name prefix| is set to \meta{name} at the
- beginning of the pic.
-
- The |name prefix| key was already introduced in the description of the
- |node| command: It allows you to set some text that is prefixed to all
- nodes in a scope. For pics this makes particular sense: All nodes defined
- by a pic's code can be referenced from outside the pic with the prefix
- provided.
-
- To see how this works, let us add some nodes to the code of the seagull:
- %
-\begin{codeexample}[code only]
-\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \coordinate (-left wing) at (-3mm,0);
- \coordinate (-head) at (0,0);
- \coordinate (-right wing) at (3mm,0);
-
- \draw (-left wing) to [bend left] (0,0) (-head) to [bend left] (-right wing);
- }
-}
-\end{codeexample}
- %
-\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \coordinate (-left wing) at (-3mm,0);
- \coordinate (-head) at (0,0);
- \coordinate (-right wing) at (3mm,0);
-
- \draw (-left wing) to [bend left] (0,0) (-head) to [bend left] (-right wing);
- }
-}
-
- Now, we can use it as follows:
- %
-\begin{codeexample}[code only]
-\tikz {
- \pic (Emma) {seagull};
- \pic (Alexandra) at (0,1) {seagull};
-
- \draw (Emma-left wing) -- (Alexandra-right wing);
-}
-\end{codeexample}
-
- Sometimes, you may also wish your pic to access nodes outside the pic
- (typically, because they are given as parameters). In this case, the name
- prefix gets in the way since the nodes outside the picture do not have this
- prefix. The trick is to locally reset the name prefix to the value it had
- outside the picture, which is achieved using the following style:
-
- \begin{key}{/tikz/name prefix ..}
- This key is available only inside the code of a pic. There, it
- (locally) changes the name prefix to the value it had outside the pic.
- This allows you to access nodes outside the current pic.
- \end{key}
-
- \medskip
- \textbf{Animations for pics.}
- Just as for nodes, you can use the attribute--colon syntax to add an
- animation to a pic:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
- pre={\tikzset{
- seagull/.pic={
- % Code for a "seagull". Do you see it?...
- \coordinate (-left wing) at (-3mm,0);
- \coordinate (-head) at (0,0);
- \coordinate (-right wing) at (3mm,0);
- %
- \draw (-left wing) to [bend left] (0,0) (-head) to [bend left] (-right wing);
- }
-}},
-]
-\tikz {
- \pic :rotate={0s="0", 20s="90"} {seagull};
- \pic at (1.5,1.5) {seagull};
-}
-\end{codeexample}
- %
- Naturally, you can also use animations in the code of a picture:
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{animations}},
- animation list={0.5,1,1.5,2},
- width=3cm,
-]
-\begin{tikzpicture} [flapping seagull/.pic={
- \draw (0,0) :path={
- 0s= {"{(180:3mm) to [bend left] (0,0) to [bend left] (0:3mm)}"=base},
- 1s= "{(160:3mm) to [bend left] (0,0) to [bend left] (20:3mm)}",
- 2s= "{(180:3mm) to [bend left] (0,0) to [bend left] (0:3mm)}",
- repeats };
- }]
- \pic :rotate={0s="0", 20s="90"} {flapping seagull};
- \pic at (1.5,1.5) {flapping seagull};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{pathoperation}
-
-There are two general purpose keys that pics may find useful:
-
-\begin{key}{/tikz/pic text=\meta{text}}
- This macro stores the \meta{text} in the macro |\tikzpictext|, which is
- |\let| to |\relax| by default. Setting the |pic text| to some value is the
- ``preferred'' way of communicating a (single) piece of text that should
- become part of a pic (typically of a node). In particular, the |quotes|
- library maps quoted parameters to this key.
-\end{key}
-
-\begin{key}{/tikz/pic text options=\meta{options}}
- This macro stores the \meta{options} in the macro |\tikzpictextoptions|,
- which is |\let| to the empty string by default. The |quotes| library maps
- options for quoted parameters to this key.
-\end{key}
-
-
-\subsubsection{The Quotes Syntax}
-\label{section-pic-quotes}
-
-When you load the |quotes| library, you can use the ``quotes syntax'' inside
-the options of a pic. Recall that for nodes this syntax is used to add a label
-to a node. For pics, the quotes syntax is used to set the |pic text| key.
-Whether or not the pic type's code takes this key into consideration is,
-however, up to the key.
-
-In detail, when the |quotes| library is loaded, each time a key--value pair in
-a list of options passed to an |pic| 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}
- |every pic quotes/.try,pic text=|\meta{text}|, pic text options={|\meta{options}|}|
-\end{quote}
-
-As example of a pic type that takes these values into account is the |angle|
-pic type:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{angles,quotes}}]
-\tikz \draw (3,0) coordinate (A)
- -- (0,1) coordinate (B)
- -- (1,2) coordinate (C)
- pic [draw, "$\alpha$"] {angle};
-\end{codeexample}
-
-As described in Section~\ref{section-label-quotes}, the apostrophe becomes part
-of the \meta{options}, when present. As can be seen above, the following style
-is executed:
-%
-\begin{stylekey}{/tikz/every pic quotes (initially \normalfont empty)}
-\end{stylekey}
-
-
-\subsection{Defining New Pic Types}
-\label{section-new-pic-types}
-
-As explained in the description of the |pic| command, in order to define a new
-pic type you need to
-%
-\begin{enumerate}
- \item define a key with the path prefix |/tikz/pics| that
- \item sets the key |/tikz/pics/code| to the code of the pic.
-\end{enumerate}
-
-It turns out that this is easy enough to achieve using styles:
-
-\begin{codeexample}[code only]
-\tikzset{
- pics/seagull/.style ={
- % Ok, this is the key that should, when
- % executed, set the code key:
- code = { %
- \draw (...) ... ;
- }
- }
-}
-\end{codeexample}
-
-Even though the above pattern is easy enough, there is a special so-called key
-handler that allows us to write even simpler code, namely:
-%
-\begin{codeexample}[code only]
-\tikzset{
- seagull/.pic = {
- \draw (...) ... ;
- }
-}
-\end{codeexample}
-
-\begin{handler}{{.pic}|=|\meta{some code}}
- This handler can only be used with a key with the prefix |/tikz/|, so you
- should normally use it only as an option to a \tikzname\ command or to the
- |\tikzset| command. It takes the \meta{key}'s path and, inside that path,
- it replaces |/tikz/| by |/tikz/pics/| (so, basically, it adds the
- ``missing'' |pics| part of the path). Then, it sets up things so that the
- resulting name to key is a style that executes |code=some code|.
-\end{handler}
-
-In almost all cases, the |.pic| key handler will suffice to setup keys.
-However, there are cases where you really need to use the first version using
-|.style| and |code=|:
-%
-\begin{itemize}
- \item Whenever your pic type needs to set the foreground or the background
- code.
- \item In case of complicated arguments given to the keys.
-\end{itemize}
-
-As an example, let us define a simple pic that draws a filled circle behind the
-path. Furthermore, we make the circle's radius a parameter of the pic:
-%
-\begin{codeexample}[]
-\tikzset{
- pics/my circle/.style = {
- background code = { \fill circle [radius=#1]; }
- }
-}
-\tikz [fill=blue!30]
- \draw (0,0) pic {my circle=2mm} -- (1,1) pic {my circle=5mm};
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-plots.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-plots.tex
deleted file mode 100644
index c069c1a44b..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-plots.tex
+++ /dev/null
@@ -1,776 +0,0 @@
-% 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{Plots of Functions}
-\label{section-tikz-plots}
-
-A warning before we get started: \emph{If you are looking for an easy way to
-create a normal plot of a function with scientific axes, ignore this section
-and instead look at the |pgfplots| package or at the |datavisualization|
-command from Part~\ref{part-dv}.}
-
-
-\subsection{Overview}
-\label{section-why-pgname-for-plots}
-
-\tikzname\ can be used to create plots of functions, a job that is normally
-handled by powerful programs like \textsc{gnuplot} or \textsc{mathematica}.
-These programs can produce two different kinds of output: First, they can
-output a complete plot picture in a certain format (like \pdf) that includes
-all low-level commands necessary for drawing the complete plot (including axes
-and labels). Second, they can usually also produce ``just plain data'' in the
-form of a long list of coordinates. Most of the powerful programs consider it a
-to be ``a bit boring'' to just output tabled data and very much prefer to
-produce fancy pictures. Nevertheless, when coaxed, they can also provide the
-plain data.
-
-The advantage of creating plots directly using \tikzname\ is
-\emph{consistency:} Plots created using \tikzname\ will automatically have the
-same styling and fonts as those used in the rest of a document -- something
-that is hard to do right when an external program gets involved. Other problems
-people encounter with external programs include: Formulas will look different,
-if they can be rendered at all; line widths will usually be too thick or too
-thin; scaling effects upon inclusion can create a mismatch between sizes in the
-plot and sizes in the text; the automatic grid generated by most programs is
-mostly distracting; the automatic ticks generated by most programs are cryptic
-numerics (try adding a tick reading ``$\pi$'' at the right point); most
-programs make it very easy to create ``chart junk'' in a most convenient
-fashion; arrows and plot marks will almost never match the arrows used in the
-rest of the document. This list is not exhaustive, unfortunately.
-
-There are basically three ways of creating plots using \tikzname:
-%
-\begin{enumerate}
- \item Use the |plot| path operation. How this works is explained in the
- present section. This is the most ``basic'' of the three options and
- forces you to do a lot of things ``by hand'' like adding axes or ticks.
- \item Use the |datavisualization| path command, which is documented in
- Part~\ref{part-dv}. This command is much more powerful than the |plot|
- path operation and produces complete plots including axes and ticks.
- The downside is that you cannot use it to ``just'' quickly plot a
- simple curve (or, more precisely, it is hard to use it in this way).
- \item Use the |pgfplots| package, which is basically an alternative to the
- |datavisualization| command. While the underlying philosophy of this
- package is not as ``ambitious'' as that of the command
- |datavisualization|, it is somewhat more mature, has a simpler design,
- and wider support base.
-\end{enumerate}
-
-
-\subsection{The Plot Path Operation}
-
-The |plot| path operation can be used to append a line or curve to the path
-that goes through a large number of coordinates. These coordinates are either
-given in a simple list of coordinates, read from some file, or they are
-computed on the fly.
-
-The syntax of the |plot| comes in different versions.
-
-\begin{pathoperation}{--plot}{\meta{further arguments}}
- This operation plots the curve through the coordinates specified in the
- \meta{further arguments}. The current (sub)path is simply continued, that
- is, a line-to operation to the first point of the curve is implicitly
- added. The details of the \meta{further arguments} will be explained in a
- moment.
-\end{pathoperation}
-
-\begin{pathoperation}{plot}{\meta{further arguments}}
- This operation plots the curve through the coordinates specified in the
- \meta{further arguments} by first ``moving'' to the first coordinate of the
- curve.
-\end{pathoperation}
-
-The \meta{further arguments} are used in different ways to specifying the
-coordinates of the points to be plotted:
-%
-\begin{enumerate}
- \item \opt{|--|}|plot|\oarg{local
- options}\declare{|coordinates{|\meta{coordinate 1}\meta{coordinate
- 2}\dots\meta{coordinate $n$}|}|}
- \item \opt{|--|}|plot|\oarg{local
- options}\declare{|file{|\meta{filename}|}|}
- \item \opt{|--|}|plot|\oarg{local options}\declare{\meta{coordinate
- expression}}
- \item \opt{|--|}|plot|\oarg{local options}\declare{|function{|\meta{gnuplot
- formula}|}|}
-\end{enumerate}
-
-These different ways are explained in the following.
-
-
-\subsection{Plotting Points Given Inline}
-
-Points can be given directly in the \TeX-file as in the following example:
-%
-\begin{codeexample}[]
-\tikz \draw plot coordinates {(0,0) (1,1) (2,0) (3,1) (2,1) (10:2cm)};
-\end{codeexample}
-
-Here is an example showing the difference between |plot| and |--plot|:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) -- (1,1) plot coordinates {(2,0) (4,0)};
- \draw[color=red,xshift=5cm]
- (0,0) -- (1,1) -- plot coordinates {(2,0) (4,0)};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Plotting Points Read From an External File}
-
-The second way of specifying points is to put them in an external file named
-\meta{filename}. Currently, the only file format that \tikzname\ allows is the
-following: Each line of the \meta{filename} should contain one line starting
-with two numbers, separated by a space. A line may also be empty or, if it
-starts with |#| or |%| it is considered empty. For such lines, a ``new data
-set'' is started, typically resulting in a new subpath being started in the
-plot (see Section~\ref{section-plot-jumps} on how to change this behavior, if
-necessary). For lines containing two numbers, they must be separated by a
-space. They may be following by arbitrary text, which is ignored, \emph{except}
-if it is |o| or |u|. In the first case, the point is considered to be an
-\emph{outlier} and normally also results in a new subpath being started. In the
-second case, the point is considered to be \emph{undefined}, which also results
-in a new subpath being started. Again, see Section~\ref{section-plot-jumps} on
-how to change this, if necessary. (This is exactly the format that
-\textsc{gnuplot} produces when you say |set table|.)
-%
-\begin{codeexample}[]
-\tikz \draw plot[mark=x,smooth] file {plots/pgfmanual-sine.table};
-\end{codeexample}
-
-The file |plots/pgfmanual-sine.table| reads:
-%
-\begin{codeexample}[code only]
-#Curve 0, 20 points
-#x y type
-0.00000 0.00000 i
-0.52632 0.50235 i
-1.05263 0.86873 i
-1.57895 0.99997 i
-...
-9.47368 -0.04889 i
-10.00000 -0.54402 i
-\end{codeexample}
-%
-It was produced from the following source, using |gnuplot|:
-%
-\begin{codeexample}[code only]
-set table "../plots/pgfmanual-sine.table"
-set format "%.5f"
-set samples 20
-plot [x=0:10] sin(x)
-\end{codeexample}
-
-The \meta{local options} of the |plot| operation are local to each plot and do
-not affect other plots ``on the same path''. For example, |plot[yshift=1cm]|
-will locally shift the plot 1cm upward. Remember, however, that most options
-can only be applied to paths as a whole. For example, |plot[red]| does not have
-the effect of making the plot red. After all, you are trying to ``locally''
-make part of the path red, which is not possible.
-
-
-\subsection{Plotting a Function}
-\label{section-tikz-plot}
-
-When you plot a function, the coordinates of the plot data can be computed by
-evaluating a mathematical expression. Since \pgfname\ comes with a mathematical
-engine, you can specify this expression and then have \tikzname\ produce the
-desired coordinates for you, automatically.
-
-Since this case is quite common when plotting a function, the syntax is easy:
-Following the |plot| command and its local options, you directly provide a
-\meta{coordinate expression}. It looks like a normal coordinate, but inside you
-may use a special macro, which is |\x| by default, but this can be changed
-using the |variable| option. The \meta{coordinate expression} is then evaluated
-for different values for |\x| and the resulting coordinates are plotted.
-
-Note that you will often have to put the $x$- or $y$-coordinate inside braces,
-namely whenever you use an expression involving a parenthesis.
-
-The following options influence how the \meta{coordinate expression} is
-evaluated:
-%
-\begin{key}{/tikz/variable=\meta{macro} (initially \string\x)}
- Sets the macro whose value is set to the different values when
- \meta{coordinate expression} is evaluated.
-\end{key}
-
-\begin{key}{/tikz/samples=\meta{number} (initially 25)}
- Sets the number of samples used in the plot.
-\end{key}
-
-\begin{key}{/tikz/domain=\meta{start}|:|\meta{end} (initially -5:5)}
- Sets the domain from which the samples are taken.
-\end{key}
-
-\begin{key}{/tikz/samples at=\meta{sample list}}
- This option specifies a list of positions for which the variable should be
- evaluated. For instance, you can say |samples at={1,2,8,9,10}| to have the
- variable evaluated exactly for values $1$, $2$, $8$, $9$, and $10$. You can
- use the |\foreach| syntax, so you can use |...| inside the \meta{sample
- list}.
-
- When this option is used, the |samples| and |domain| option are overruled.
- The other way round, setting either |samples| or |domain| will overrule
- this option.
-\end{key}
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[domain=0:4]
- \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
-
- \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
- \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
-
- \draw[color=red] plot (\x,\x) node[right] {$f(x) =x$};
- % \x r means to convert '\x' from degrees to _r_adians:
- \draw[color=blue] plot (\x,{sin(\x r)}) node[right] {$f(x) = \sin x$};
- \draw[color=orange] plot (\x,{0.05*exp(\x)}) node[right] {$f(x) = \frac{1}{20} \mathrm e^x$};
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth,variable=\t]
- plot ({\t*sin(\t r)},{\t*cos(\t r)});
-\end{codeexample}
-
-\begin{codeexample}[]
-\tikz \draw[domain=0:360,smooth,variable=\t]
- plot ({sin(\t)},\t/360,{cos(\t)});
-\end{codeexample}
-
-
-\subsection{Plotting a Function Using Gnuplot}
-\label{section-tikz-gnuplot}
-
-Often, you will want to plot points that are given via a function like $f(x) =
-x \sin x$. Unfortunately, \TeX\ does not really have enough computational power
-to generate the points of such a function efficiently (it is a text processing
-program, after all). However, if you allow it, \TeX\ can try to call external
-programs that can easily produce the necessary points. Currently, \tikzname\
-knows how to call \textsc{gnuplot}.
-
-When \tikzname\ encounters your operation
-|plot[id=|\meta{id}|] function{x*sin(x)}| for the first time, it will create a
-file called \meta{prefix}\meta{id}|.gnuplot|, where \meta{prefix} is
-|\jobname.| by default, that is, the name of your main |.tex| file. If no
-\meta{id} is given, it will be empty, which is alright, but it is better when
-each plot has a unique \meta{id} for reasons explained in a moment. Next,
-\tikzname\ writes some initialization code into this file followed by
-|plot x*sin(x)|. The initialization code sets up things such that the |plot|
-operation will write the coordinates into another file called
-\meta{prefix}\meta{id}|.table|. Finally, this table file is read as if you had
-said |plot file{|\meta{prefix}\meta{id}|.table}|.
-
-For the plotting mechanism to work, two conditions must be met:
-%
-\begin{enumerate}
- \item You must have allowed \TeX\ to call external programs. This is often
- switched off by default since this is a security risk (you might,
- without knowing, run a \TeX\ file that calls all sorts of ``bad''
- commands). To enable this ``calling external programs'' a command line
- option must be given to the \TeX\ program. Usually, it is called
- something like |shell-escape| or |enable-write18|. For example, for my
- |pdflatex| the option |--shell-escape| can be given.
- \item You must have installed the |gnuplot| program and \TeX\ must find it
- when compiling your file.
-\end{enumerate}
-
-Unfortunately, these conditions will not always be met. Especially if you pass
-some source to a coauthor and the coauthor does not have \textsc{gnuplot}
-installed, he or she will have trouble compiling your files.
-
-For this reason, \tikzname\ behaves differently when you compile your graphic
-for the second time: If upon reaching |plot[id=|\meta{id}|] function{...}| the
-file \meta{prefix}\meta{id}|.table| already exists \emph{and} if the
-\meta{prefix}\meta{id}|.gnuplot| file contains what \tikzname\ thinks that it
-``should'' contain, the |.table| file is immediately read without trying to
-call a |gnuplot| program. This approach has the following advantages:
-%
-\begin{enumerate}
- \item If you pass a bundle of your |.tex| file and all |.gnuplot| and
- |.table| files to someone else, that person can \TeX\ the |.tex| file
- without having to have |gnuplot| installed.
- \item If the |\write18| feature is switched off for security reasons (a
- good idea), then, upon the first compilation of the |.tex| file, the
- |.gnuplot| will still be generated, but not the |.table| file. You can
- then simply call |gnuplot| ``by hand'' for each |.gnuplot| file, which
- will produce all necessary |.table| files.
- \item If you change the function that you wish to plot or its domain,
- \tikzname\ will automatically try to regenerate the |.table| file.
- \item If, out of laziness, you do not provide an |id|, the same |.gnuplot|
- will be used for different plots, but this is not a problem since the
- |.table| will automatically be regenerated for each plot on-the-fly.
- \emph{Note: If you intend to share your files with someone else, always
- use an id, so that the file can by typeset without having
- \textsc{gnuplot} installed.} Also, having unique ids for each plot will
- improve compilation speed since no external programs need to be called,
- unless it is really necessary.
-\end{enumerate}
-
-When you use |plot function{|\meta{gnuplot formula}|}|, the \meta{gnuplot
-formula} must be given in the |gnuplot| syntax, whose details are beyond the
-scope of this manual. Here is the ultra-condensed essence: Use |x| as the
-variable and use the C-syntax for normal plots, use |t| as the variable for
-parametric plots. Here are some examples:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[domain=0:4]
- \draw[very thin,color=gray] (-0.1,-1.1) grid (3.9,3.9);
-
- \draw[->] (-0.2,0) -- (4.2,0) node[right] {$x$};
- \draw[->] (0,-1.2) -- (0,4.2) node[above] {$f(x)$};
-
- \draw[color=red] plot[id=x] function{x} node[right] {$f(x) =x$};
- \draw[color=blue] plot[id=sin] function{sin(x)} node[right] {$f(x) = \sin x$};
- \draw[color=orange] plot[id=exp] function{0.05*exp(x)} node[right] {$f(x) = \frac{1}{20} \mathrm e^x$};
-\end{tikzpicture}
-\end{codeexample}
-
-The plot is influenced by the following options: First, the options |samples|
-and |domain| explained earlier. Second, there are some more specialized
-options.
-
-\begin{key}{/tikz/parametric=\meta{boolean} (default true)}
- Sets whether the plot is a parametric plot. If true, then |t| must be used
- instead of |x| as the parameter and two comma-separated functions must be
- given in the \meta{gnuplot formula}. An example is the following:
- %
-\begin{codeexample}[]
-\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth]
- plot[parametric,id=parametric-example] function{t*sin(t),t*cos(t)};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/range=\meta{start}|:|\meta{end}}
- This key sets the range of the plot. If set, all points whose
- $y$-coordinates lie outside this range will be considered to be outliers
- and will cause jumps in the plot, by default:
- %
-\begin{codeexample}[]
-\tikz \draw[scale=0.5,domain=-3.141:3.141, samples=100, smooth, range=-3:3]
- plot[id=tan-example] function{tan(x)};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/yrange=\meta{start}|:|\meta{end}}
- Same as |range|.
-\end{key}
-
-\begin{key}{/tikz/xrange=\meta{start}|:|\meta{end}}
- Set the $x$-range. This makes sense only for parametric plots.
- %
-\begin{codeexample}[]
-\tikz \draw[scale=0.5,domain=-3.141:3.141,smooth,xrange=0:1]
- plot[parametric,id=parametric-example-cut] function{t*sin(t),t*cos(t)};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/id=\meta{id}}
- Sets the identifier of the current plot. This should be a unique identifier
- for each plot (though things will also work if it is not, but not as well,
- see the explanations above). The \meta{id} will be part of a filename, so
- it should not contain anything fancy like |*| or |$|.%$
-\end{key}
-
-\begin{key}{/tikz/prefix=\meta{prefix}}
- The \meta{prefix} is put before each plot file name. The default is
- |\jobname.|, but if you have many plots, it might be better to use, say
- |plots/| and have all plots placed in a directory. You have to create the
- directory yourself.
-\end{key}
-
-\begin{key}{/tikz/raw gnuplot}
- This key causes the \meta{gnuplot formula} to be passed on to
- \textsc{gnuplot} without setting up the samples or the |plot| operation.
- Thus, you could write
- %
-\begin{codeexample}[code only]
-plot[raw gnuplot,id=raw-example] function{set samples 25; plot sin(x)}
-\end{codeexample}
- %
- This can be useful for complicated things that need to be passed to
- \textsc{gnuplot}. However, for really complicated situations you should
- create a special external generating \textsc{gnuplot} file and use the
- |file|-syntax to include the table ``by hand''.
-\end{key}
-
-The following styles influence the plot:
-%
-\begin{stylekey}{/tikz/every plot (initially \normalfont empty)}
- This style is installed in each plot, that is, as if you always said
- %
-\begin{codeexample}[code only]
- plot[every plot,...]
-\end{codeexample}
- %
- This is most useful for globally setting a prefix for all plots by saying:
- %
-\begin{codeexample}[code only]
-\tikzset{every plot/.style={prefix=plots/}}
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsection{Placing Marks on the Plot}
-
-As we saw already, it is possible to add \emph{marks} to a plot using the
-|mark| option. When this option is used, a copy of the plot mark is placed on
-each point of the plot. Note that the marks are placed \emph{after} the whole
-path has been drawn/filled/shaded. In this respect, they are handled like text
-nodes.
-
-In detail, the following options govern how marks are drawn:
-%
-\begin{key}{/tikz/mark=\meta{mark mnemonic}}
- Sets the mark to a mnemonic that has previously been defined using the
- |\pgfdeclareplotmark|. By default, |*|, |+|, and |x| are available, which
- draw a filled circle, a plus, and a cross as marks. Many more marks become
- available when the library |plotmarks| is loaded.
- Section~\ref{section-plot-marks} lists the available plot marks.
-
- One plot mark is special: the |ball| plot mark is available only in
- \tikzname. The |ball color| option determines the balls's color. Do not use
- this option with a large number of marks since it will take very long to
- render in PostScript.
-
- \begin{tabular}{lc}
- Option & Effect \\
- \hline
- \vrule height14pt width0pt \plotmarkentrytikz{ball}
- \end{tabular}
-\end{key}
-
-\begin{key}{/tikz/mark repeat=\meta{r}}
- This option tells \tikzname\ that only every $r$th mark should be drawn.
- %
-\begin{codeexample}[]
-\tikz \draw plot[mark=x,mark repeat=3,smooth] file {plots/pgfmanual-sine.table};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/mark phase=\meta{p}}
- This option tells \tikzname\ that the first mark to be draw should be the
- $p$th, followed by the $(p+r)$th, then the $(p+2r)$th, and so on.
- %
-\begin{codeexample}[]
-\tikz \draw plot[mark=x,mark repeat=3,mark phase=6,smooth] file {plots/pgfmanual-sine.table};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/mark indices=\meta{list}}
- This option allows you to specify explicitly the indices at which a mark
- should be placed. Counting starts with 1. You can use the |\foreach|
- syntax, that is, |...| can be used.
- %
-\begin{codeexample}[]
-\tikz \draw plot[mark=x,mark indices={1,4,...,10,11,12,...,16,20},smooth]
- file {plots/pgfmanual-sine.table};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/mark size=\meta{dimension}}
- Sets the size of the plot marks. For circular plot marks, \meta{dimension}
- is the radius, for other plot marks \meta{dimension} should be about half
- the width and height.
-
- This option is not really necessary, since you achieve the same effect by
- specifying |scale=|\meta{factor} as a local option, where \meta{factor} is
- the quotient of the desired size and the default size. However, using
- |mark size| is a bit faster and more natural.
-\end{key}
-
-\begin{stylekey}{/tikz/every mark}
- This style is installed before drawing plot marks. For example, you can
- scale (or otherwise transform) the plot mark or set its color.
-\end{stylekey}
-
-\begin{key}{/tikz/mark options=\meta{options}}
- Redefines |every mark| such that it sets \marg{options}.
- %
-\begin{codeexample}[]
-\tikz \fill[fill=blue!20]
- plot[mark=triangle*,mark options={color=blue,rotate=180}]
- file{plots/pgfmanual-sine.table} |- (0,0);
-\end{codeexample}
- %
-\end{key}
-
-\begin{stylekey}{/tikz/no marks}
- Disables markers (the same as |mark=none|).
-\end{stylekey}
-%
-\begin{stylekey}{/tikz/no markers}
- Disables markers (the same as |mark=none|).
-\end{stylekey}
-
-
-\subsection{Smooth Plots, Sharp Plots, Jump Plots, Comb Plots and Bar Plots}
-
-There are different things the |plot| operation can do with the points it reads
-from a file or from the inlined list of points. By default, it will connect
-these points by straight lines. However, you can also use options to change the
-behavior of |plot|.
-
-\begin{key}{/tikz/sharp plot}
- This is the default and causes the points to be connected by straight
- lines. This option is included only so that you can ``switch back'' if you
- ``globally'' install, say, |smooth|.
-\end{key}
-
-\begin{key}{/tikz/smooth}
- This option causes the points on the path to be connected using a smooth
- curve:
- %
-\begin{codeexample}[]
-\tikz\draw plot[smooth] file{plots/pgfmanual-sine.table};
-\end{codeexample}
-
- Note that the smoothing algorithm is not very intelligent. You will get the
- best results if the bending angles are small, that is, less than about
- $30^\circ$ and, even more importantly, if the distances between points are
- about the same all over the plotting path.
-\end{key}
-
-\begin{key}{/tikz/tension=\meta{value}}
- This option influences how ``tight'' the smoothing is. A lower value will
- result in sharper corners, a higher value in more ``round'' curves. A value
- of $1$ results in a circle if four points at quarter-positions on a circle
- are given. The default is $0.55$. The ``correct'' value depends on the
- details of plot.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[smooth cycle]
- \draw plot[tension=0.2]
- coordinates{(0,0) (1,1) (2,0) (1,-1)};
- \draw[yshift=-2.25cm] plot[tension=0.5]
- coordinates{(0,0) (1,1) (2,0) (1,-1)};
- \draw[yshift=-4.5cm] plot[tension=1]
- coordinates{(0,0) (1,1) (2,0) (1,-1)};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/smooth cycle}
- This option causes the points on the path to be connected using a closed
- smooth curve.
- %
-\begin{codeexample}[]
-\tikz[scale=0.5]
- \draw plot[smooth cycle] coordinates{(0,0) (1,0) (2,1) (1,2)}
- plot coordinates{(0,0) (1,0) (2,1) (1,2)} -- cycle;
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/const plot}
- This option causes the points on the path to be connected using piecewise
- constant series of lines:
- %
-\begin{codeexample}[]
-\tikz\draw plot[const plot] file{plots/pgfmanual-sine.table};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/const plot mark left}
- Just an alias for |/tikz/const plot|.
- %
-\begin{codeexample}[]
-\tikz\draw plot[const plot mark left,mark=*] file{plots/pgfmanual-sine.table};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/const plot mark right}
- A variant of |/tikz/const plot| which places its mark on the right ends:
- %
-\begin{codeexample}[]
-\tikz\draw plot[const plot mark right,mark=*] file{plots/pgfmanual-sine.table};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/const plot mark mid}
- A variant of |/tikz/const plot| which places its mark in the middle of the
- horizontal lines:
- %
-\begin{codeexample}[]
-\tikz\draw plot[const plot mark mid,mark=*] file{plots/pgfmanual-sine.table};
-\end{codeexample}
- %
- More precisely, it generates vertical lines in the middle between each pair
- of consecutive points. If the mesh width is constant, this leads to
- symmetrically placed marks (``middle'').
-\end{key}
-
-\begin{key}{/tikz/jump mark left}
- This option causes the points on the path to be drawn using piecewise
- constant, non-connected series of lines. If there are any marks, they will
- be placed on left open ends:
- %
-\begin{codeexample}[]
-\tikz\draw plot[jump mark left, mark=*] file{plots/pgfmanual-sine.table};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/jump mark right}
- This option causes the points on the path to be drawn using piecewise
- constant, non-connected series of lines. If there are any marks, they will
- be placed on right open ends:
- %
-\begin{codeexample}[]
-\tikz\draw plot[jump mark right, mark=*] file{plots/pgfmanual-sine.table};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/jump mark mid}
- This option causes the points on the path to be drawn using piecewise
- constant, non-connected series of lines. If there are any marks, they will
- be placed in the middle of the horizontal line segments:
- %
-\begin{codeexample}[]
-\tikz\draw plot[jump mark mid, mark=*] file{plots/pgfmanual-sine.table};
-\end{codeexample}
-
- In case of non-constant mesh widths, the same remarks as for
- |const plot mark mid| apply.
-\end{key}
-
-\begin{key}{/tikz/ycomb}
- This option causes the |plot| operation to interpret the plotting points
- differently. Instead of connecting them, for each point of the plot a
- straight line is added to the path from the $x$-axis to the point,
- resulting in a sort of ``comb'' or ``bar diagram''.
- %
-\begin{codeexample}[]
-\tikz\draw[ultra thick] plot[ycomb,thin,mark=*] file{plots/pgfmanual-sine.table};
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[ycomb]
- \draw[color=red,line width=6pt]
- plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)};
- \draw[color=red!50,line width=4pt,xshift=3pt]
- plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/xcomb}
- This option works like |ycomb| except that the bars are horizontal.
- %
-\begin{codeexample}[]
-\tikz \draw plot[xcomb,mark=x] coordinates{(1,0) (0.8,0.2) (0.6,0.4) (0.2,1)};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/polar comb}
- This option causes a line from the origin to the point to be added to the
- path for each plot point.
- %
-\begin{codeexample}[]
-\tikz \draw plot[polar comb,
- mark=pentagon*,mark options={fill=white,draw=red},mark size=4pt]
- coordinates {(0:1cm) (30:1.5cm) (160:.5cm) (250:2cm) (-60:.8cm)};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/ybar}
- This option produces fillable bar plots. It is thus very similar to
- |ycomb|, but it employs rectangular shapes instead of line-to operations.
- It thus allows to use any fill or pattern style.
- %
-\begin{codeexample}[]
-\tikz\draw[draw=blue,fill=blue!60!black] plot[ybar] file{plots/pgfmanual-sine.table};
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[ybar]
- \draw[color=red,fill=red!80,bar width=6pt]
- plot coordinates{(0,1) (.5,1.2) (1,.6) (1.5,.7) (2,.9)};
- \draw[color=red!50,fill=red!20,bar width=4pt,bar shift=3pt]
- plot coordinates{(0,1.2) (.5,1.3) (1,.5) (1.5,.2) (2,.5)};
-\end{tikzpicture}
-\end{codeexample}
- %
- The use of |bar width| and |bar shift| is explained in the |plothandlers|
- library documentation, section~\ref{section-plotlib-bar-handlers}. Please
- refer to page~\pageref{key-bar-width}.
-\end{key}
-
-\begin{key}{/tikz/xbar}
- This option works like |ybar| except that the bars are horizontal.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns}}]
-\tikz \draw[pattern=north west lines] plot[xbar]
- coordinates{(1,0) (0.4,1) (1.7,2) (1.6,3)};
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/ybar interval}
- As |/tikz/ybar|, this options produces vertical bars. However, bars are
- centered at coordinate \emph{intervals} instead of interval edges, and the
- bar's width is also determined relatively to the interval's length:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[ybar interval,x=10pt]
- \draw[color=red,fill=red!80]
- plot coordinates{(0,2) (2,1.2) (3,.3) (5,1.7) (8,.9) (9,.9)};
-\end{tikzpicture}
-\end{codeexample}
- %
- Since there are $N$ intervals $[x_i,x_{i+1}]$ for given $N+1$ coordinates,
- you will always have one coordinate more than bars. The last $y$ value will
- be ignored.
-
- You can configure relative shifts and relative bar widths, which is
- explained in the |plothandlers| library documentation,
- section~\ref{section-plotlib-bar-handlers}. Please refer to
- page~\pageref{key-bar-interval-width}.
-\end{key}
-
-\begin{key}{/tikz/xbar interval}
- Works like |ybar interval|, but for horizontal bar plots.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[xbar interval,x=0.5cm,y=0.5cm]
- \draw[color=red,fill=red!80]
- plot coordinates {(3,0) (2,1) (4,1.5) (1,4) (2,6) (2,7)};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/only marks}
- This option causes only marks to be shown; no path segments are added to
- the actual path. This can be useful for quickly adding some marks to a
- path.
- %
-\begin{codeexample}[]
-\tikz \draw (0,0) sin (1,1) cos (2,0)
- plot[only marks,mark=x] coordinates{(0,0) (1,1) (2,0) (3,-1)};
-\end{codeexample}
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-scopes.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-scopes.tex
deleted file mode 100644
index a8ffe644c8..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-scopes.tex
+++ /dev/null
@@ -1,582 +0,0 @@
-% Copyright 2019 by Till Tantau
-%
-% This file may be distributed and/or modified
-%
-% 1. under the LaTeX Project Public License and/or
-% 2. under the GNU Free Documentation License.
-%
-% See the file doc/generic/pgf/licenses/LICENSE for more details.
-
-
-\section[Hierarchical Structures: Package, Environments, Scopes, and Styles]
- {Hierarchical Structures:\\
- Package, Environments, Scopes, and Styles}
-
-The present section explains how your files should be structured when you use
-\tikzname. On the top level, you need to include the |tikz| package. In the
-main text, each graphic needs to be put in a |{tikzpicture}| environment.
-Inside these environments, you can use |{scope}| environments to create
-internal groups. Inside the scopes you use |\path| commands to actually draw
-something. On all levels (except for the package level), graphic options can be
-given that apply to everything within the environment.
-
-
-\subsection{Loading the Package and the Libraries}
-
-\begin{package}{tikz}
- This package does not have any options.
-
- This will automatically load the \pgfname\ and the |pgffor| package.
-
- \pgfname\ needs to know what \TeX\ driver you are intending to use. In most
- cases \pgfname\ is clever enough to determine the correct driver for you;
- this is true in particular if you use \LaTeX. One situation where \pgfname\
- cannot know the driver ``by itself'' is when you use plain \TeX\ or Con\TeX
- t together with |dvipdfm|. In this case, you have to write
- |\def\pgfsysdriver{pgfsys-dvipdfm.def}| \emph{before} you input |tikz.tex|.
-\end{package}
-
-\begin{command}{\usetikzlibrary\marg{list of libraries}}
- Once \tikzname\ has been loaded, you can use this command to load further
- libraries. The list of libraries should contain the names of libraries
- separated by commas. Instead of curly braces, you can also use square
- brackets, which is something Con\TeX t users will like. If you try to load
- a library a second time, nothing will happen.
-
- \example |\usetikzlibrary{arrows.meta}|
-
- The above command will load a whole bunch of extra arrow tip definitions.
-
- What this command does is to load the file
- |tikzlibrary|\meta{library}|.code.tex| for each \meta{library} in the
- \meta{list of libraries}. If this file does not exist, the file
- |pgflibrary|\meta{library}|.code.tex| is loaded instead. If this file also
- does not exist, an error message is printed. Thus, to write your own
- library file, all you need to do is to place a file of the appropriate name
- somewhere where \TeX\ can find it. \LaTeX, plain \TeX, and Con\TeX t users
- can then use your library.
-\end{command}
-
-
-\subsection{Creating a Picture}
-
-\subsubsection{Creating a Picture Using an Environment}
-
-The ``outermost'' scope of \tikzname\ is the |{tikzpicture}| environment. You
-may give drawing commands only inside this environment, giving them outside (as
-is possible in many other packages) will result in chaos.
-
-In \tikzname, the way graphics are rendered is strongly influenced by graphic
-options. For example, there is an option for setting the color used for
-drawing, another for setting the color used for filling, and also more obscure
-ones like the option for setting the prefix used in the filenames of temporary
-files written while plotting functions using an external program. The graphic
-options are specified in \emph{key lists}, see
-Section~\ref{section-graphic-options} below for details. All graphic options
-are local to the |{tikzpicture}| to which they apply.
-
-\begin{environment}{{tikzpicture}\opt{\meta{animations spec}}\opt{\oarg{options}}}
- All \tikzname\ commands should be given inside this environment, except for
- the |\tikzset| command. You cannot use graphics commands like the low-level
- command |\pgfpathmoveto| outside this environment and doing so will result
- in chaos. For \tikzname, commands like |\path| are only defined inside this
- environment, so there is little chance that you will do something wrong
- here.
-
- When this environment is encountered, the \meta{options} are parsed, see
- Section~\ref{section-graphic-options}. All options given here will apply to
- the whole picture. Before the options you can specify animation commands,
- provided that the |animations| library is loaded, see
- Section~\ref{section-tikz-animations} for details.
-
- Next, the contents of the environment is processed and the graphic commands
- therein are put into a box. Non-graphic text is suppressed as well as
- possible, but non-\pgfname\ commands inside a |{tikzpicture}| environment
- should not produce any ``output'' since this may totally scramble the
- positioning system of the backend drivers. The suppressing of normal text,
- by the way, is done by temporarily switching the font to |\nullfont|. You
- can, however, ``escape back'' to normal \TeX\ typesetting. This happens,
- for example, when you specify a node.
-
- At the end of the environment, \pgfname\ tries to make a good guess at the
- size of a bounding box of the graphic and then resizes the picture box such
- that the box has this size. To ``make its guess'', every time \pgfname\
- encounters a coordinate, it updates the bounding box's size such that it
- encompasses all these coordinates. This will usually give a good
- approximation of the bounding box, but will not always be accurate. First,
- the line thickness of diagonal lines is not taken into account correctly.
- Second, control points of a curve often lie far ``outside'' the curve and
- make the bounding box too large. In this case, you should use the
- |[use as bounding box]| option.
-
- The following key influences the baseline of the resulting picture:
- %
- \begin{key}{/tikz/baseline=\meta{dimension or coordinate or \texttt{default}} (default 0pt)}
- Normally, the lower end of the picture is put on the baseline of the
- surrounding text. For example, when you give the code
- |\tikz\draw(0,0)circle(.5ex);|, \pgfname\ will find out that the lower
- end of the picture is at $-.5\mathrm{ex} - 0.2\mathrm{pt}$ (the 0.2pt
- are half the line width, which is 0.4pt) and that the upper end is at
- $.5\mathrm{ex}+.5\mathrm{pt}$. Then, the lower end will be put on the
- baseline, resulting in the following: \tikz\draw(0,0)circle(.5ex);.
-
- Using this option, you can specify that the picture should be raised or
- lowered such that the height \meta{dimension} is on the baseline. For
- example, |\tikz[baseline=0pt]\draw(0,0)circle(.5ex);| yields
- \tikz[baseline=0pt]\draw(0,0)circle(.5ex); since, now, the baseline is
- on the height of the $x$-axis.
-
- This options is often useful for ``inlined'' graphics as in
- %
-\begin{codeexample}[]
-$A \mathbin{\tikz[baseline] \draw[->>] (0pt,.5ex) -- (3ex,.5ex);} B$
-\end{codeexample}
-
- Instead of a \meta{dimension} you can also provide a coordinate in
- parentheses. Then the effect is to put the baseline on the
- $y$-coordinate that the given \meta{coordinate} has \emph{at the end of
- the picture}. This means that, at the end of the picture, the
- \meta{coordinate} is evaluated and then the baseline is set to the
- $y$-coordinate of the resulting point. This makes it easy to reference
- the $y$-coordinate of, say, the baseline of nodes.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-Hello
-\tikz[baseline=(X.base)]
- \node [cross out,draw] (X) {world.};
-\end{codeexample}
-
-\begin{codeexample}[]
-Top align:
-\tikz[baseline=(current bounding box.north)]
- \draw (0,0) rectangle (1cm,1ex);
-\end{codeexample}
-
- Use |baseline=default| to reset the |baseline| option to its initial
- configuration.
- \end{key}
-
- \begin{key}{/tikz/execute at begin picture=\meta{code}}
- This option causes \meta{code} to be executed at the beginning of the
- picture. This option must be given in the argument of the
- |{tikzpicture}| environment itself since this option will not have an
- effect otherwise. After all, the picture has already ``started'' later
- on. The effect of multiply setting this option accumulates.
-
- This option is mainly used in styles like the |every picture| style to
- execute certain code at the start of a picture.
- \end{key}
-
- \begin{key}{/tikz/execute at end picture=\meta{code}}
- This option installs \meta{code} that will be executed at the end of
- the picture. Using this option multiple times will cause the code to
- accumulate. This option must also be given in the optional argument of
- the |{tikzpicture}| environment.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\begin{tikzpicture}[execute at end picture=%
- {
- \begin{pgfonlayer}{background}
- \path[fill=yellow,rounded corners]
- (current bounding box.south west) rectangle
- (current bounding box.north east);
- \end{pgfonlayer}
- }]
- \node at (0,0) {X};
- \node at (2,1) {Y};
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- All options ``end'' at the end of the picture. To set an option
- ``globally'' change the following style:
- %
- \begin{stylekey}{/tikz/every picture (initially \normalfont empty)}
- This style is installed at the beginning of each picture.
- %
-\begin{codeexample}[code only]
-\tikzset{every picture/.style=semithick}
-\end{codeexample}
- \end{stylekey}
-
- Note that you should not use |\tikzset| to set options directly. For
- instance, if you want to use a line width of |1pt| by default, do not try
- to say |\tikzset{line width=1pt}| at the beginning of your document. This
- will not work since the line width is changed in many places. Instead, say
- %
-\begin{codeexample}[code only]
-\tikzset{every picture/.style={line width=1pt}}
-\end{codeexample}
- %
- This will have the desired effect.
-\end{environment}
-
-In other \TeX\ formats, you should use the following commands instead:
-
-\begin{plainenvironment}{{tikzpicture}\opt{\oarg{options}}}
- This is the plain \TeX\ version of the environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{tikzpicture}\opt{\oarg{options}}}
- This is the Con\TeX t version of the environment.
-\end{contextenvironment}
-
-
-\subsubsection{Creating a Picture Using a Command}
-
-The following command is an alternative to |{tikzpicture}| that is particular
-useful for graphics consisting of a single or few commands.
-
-\begin{command}{\tikz\opt{\meta{animations spec}}\opt{\oarg{options}}\marg{path commands}}
- This command places the \meta{path commands} inside a |{tikzpicture}|
- environment. The \meta{path commands} may contain paragraphs and fragile
- material (like verbatim text).
-
- If there is only one path command, it need not be surrounded by curly
- braces, if there are several, you need to add them (this is similar to the
- |\foreach| statement and also to the rules in programming languages like
- Java or C concerning the placement of curly braces).
-
- \example |\tikz{\draw (0,0) rectangle (2ex,1ex);}| yields
- \tikz{\draw (0,0) rectangle (2ex,1ex);}
-
- \example |\tikz \draw (0,0) rectangle (2ex,1ex);| yields
- \tikz \draw (0,0) rectangle (2ex,1ex);
-\end{command}
-
-
-\subsubsection{Handling Catcodes and the Babel Package}
-
-Inside a \tikzname\ picture, most symbols need to have the category code 12
-(normal text) in order to ensure that the parser works properly. This is
-typically not the case when packages like |babel| are used, which change
-catcodes aggressively.
-
-To solve this problem, \tikzname\ provides a small library also called |babel|
-(which can, however, also be used together with any other package that globally
-changes category codes). What it does is to reset the category codes at the
-beginning of every |{tikzpicture}| and to restore them at the beginning of
-every node. In almost all cases, this is exactly what you would expect and
-need, so I recommend to always load this library by saying
-|\usetikzlibrary{babel}|. For details on what, exactly, happens with the
-category codes, see Section~\ref{section-library-babel}.
-
-
-\subsubsection{Adding a Background}
-
-By default, pictures do not have any background, that is, they are
-``transparent'' on all parts on which you do not draw anything. You may instead
-wish to have a colored background behind your picture or a black frame around
-it or lines above and below it or some other kind of decoration.
-
-Since backgrounds are often not needed at all, the definition of styles for
-adding backgrounds has been put in the library package |backgrounds|. This
-package is documented in Section~\ref{section-tikz-backgrounds}.
-
-
-\subsection{Using Scopes to Structure a Picture}
-
-Inside a |{tikzpicture}| environment you can create scopes using the |{scope}|
-environment. This environment is available only inside the |{tikzpicture}|
-environment, so once more, there is little chance of doing anything wrong.
-
-
-\subsubsection{The Scope Environment}
-
-\begin{environment}{{scope}\opt{\meta{animations spec}}\opt{\oarg{options}}}
- All \meta{options} are local to the \meta{environment contents}.
- Furthermore, the clipping path is also local to the environment, that is,
- any clipping done inside the environment ``ends'' at its end.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[ultra thick]
- \begin{scope}[red]
- \draw (0mm,10mm) -- (10mm,10mm);
- \draw (0mm,8mm) -- (10mm,8mm);
- \end{scope}
- \draw (0mm,6mm) -- (10mm,6mm);
- \begin{scope}[green]
- \draw (0mm,4mm) -- (10mm,4mm);
- \draw (0mm,2mm) -- (10mm,2mm);
- \draw[blue] (0mm,0mm) -- (10mm,0mm);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{key}{/tikz/name=\meta{scope name}}
- Assigns a name to a scope reference in animations. The name is a
- ``high-level'' name that drivers do not see, so you can use spaces,
- number, letters, in a name, but you should \emph{not} use any
- punctuation like a dot, a comma, or a colon.
- \end{key}
-
- The following style influences scopes:
- %
- \begin{stylekey}{/tikz/every scope (initially \normalfont empty)}
- This style is installed at the beginning of every scope.
- \end{stylekey}
-
- The following options are useful for scopes:
- %
- \begin{key}{/tikz/execute at begin scope=\meta{code}}
- This option install some code that will be executed at the beginning of
- the scope. This option must be given in the argument of the |{scope}|
- environment.
-
- The effect applies only to the current scope, not to subscopes.
- \end{key}
-
- \begin{key}{/tikz/execute at end scope=\meta{code}}
- This option installs some code that will be executed at the end of the
- current scope. Using this option multiple times will cause the code to
- accumulate. This option must also be given in the optional argument of
- the |{scope}| environment.
-
- Again, the effect applies only to the current scope, not to subscopes.
- \end{key}
-\end{environment}
-
-\begin{plainenvironment}{{scope}\opt{\meta{animations spec}}\opt{\oarg{options}}}
- Plain \TeX\ version of the environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{scope}\opt{\meta{animations spec}}\opt{\oarg{options}}}
- Con\TeX t version of the environment.
-\end{contextenvironment}
-
-
-\subsubsection{Shorthand for Scope Environments}
-
-There is a small library that makes using scopes a bit easier:
-%
-\begin{tikzlibrary}{scopes}
- This library defines a shorthand for starting and ending |{scope}|
- environments.
-\end{tikzlibrary}
-
-When this library is loaded, the following happens: At certain places inside a
-\tikzname\ picture, it is allowed to start a scope just using a single brace,
-provided the single brace is followed by options in square brackets:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{scopes}}]
-\begin{tikzpicture}
- { [ultra thick]
- { [red]
- \draw (0mm,10mm) -- (10mm,10mm);
- \draw (0mm,8mm) -- (10mm,8mm);
- }
- \draw (0mm,6mm) -- (10mm,6mm);
- }
- { [green]
- \draw (0mm,4mm) -- (10mm,4mm);
- \draw (0mm,2mm) -- (10mm,2mm);
- \draw[blue] (0mm,0mm) -- (10mm,0mm);
- }
-\end{tikzpicture}
-\end{codeexample}
-
-In the above example, |{ [ultra thick]| actually causes a
-|\begin{scope}[ultra thick]| to be inserted, and the corresponding closing |}|
-causes an |\end{scope}| to be inserted.
-
-The ``certain places'' where an opening brace has this special meaning are the
-following: First, right after the semicolon that ends a path. Second, right
-after the end of a scope. Third, right at the beginning of a scope, which
-includes the beginning of a picture. Also note that some square bracket must
-follow, otherwise the brace is treated as a normal \TeX\ scope.
-
-
-\subsubsection{Single Command Scopes}
-
-In some situations it is useful to create a scope for a single command. For
-instance, when you wish to use algorithm graph drawing in order to layout a
-tree, the path of the tree needs to be surrounded by a scope whose only purpose
-is to take a key that selects a layout for the scope. Similarly, in order to
-put something on a background layer, a scope needs to be created. In such
-cases, where it will cumbersome to create a |\begin{scope}| and |\end{scope}|
-pair just for a single command, the |\scoped| command may be useful:
-
-\begin{command}{\scoped\opt{\meta{animations spec}}\opt{\oarg{options}}\meta{path command}}
- This command works like |\tikz|, only you can use it inside a
- |{tikzpicture}|. It will take the following \meta{path command} and
- put it inside a |{scope}| with the \meta{options} set. The
- \meta{path command} may either be a single command ended by a
- semicolon or it may contain multiple commands, but then they must be
- surrounded by curly braces.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds}}]
-\begin{tikzpicture}
- \node [fill=white] at (1,1) {Hello world};
- \scoped [on background layer]
- \draw (0,0) grid (3,2);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Using Scopes Inside Paths}
-
-The |\path| command, which is described in much more detail in later sections,
-also takes graphic options. These options are local to the path. Furthermore,
-it is possible to create local scopes within a path simply by using curly
-braces as in
-%
-\begin{codeexample}[]
-\tikz \draw (0,0) -- (1,1)
- {[rounded corners] -- (2,0) -- (3,1)}
- -- (3,0) -- (2,1);
-\end{codeexample}
-
-Note that many options apply only to the path as a whole and cannot be scoped
-in this way. For example, it is not possible to scope the |color| of the path.
-See the explanations in the section on paths for more details.
-
-Finally, certain elements that you specify in the argument to the |\path|
-command also take local options. For example, a node specification takes
-options. In this case, the options apply only to the node, not to the
-surrounding path.
-
-
-\subsection{Using Graphic Options}
-\label{section-graphic-options}
-
-\subsubsection{How Graphic Options Are Processed}
-
-Many commands and environments of \tikzname\ accept \emph{options}. These
-options are so-called \emph{key lists}. To process the options, the following
-command is used, which you can also call yourself. Note that it is usually
-better not to call this command directly, since this will ensure that the
-effect of options are local to a well-defined scope.
-
-\begin{command}{\tikzset\marg{options}}
- This command will process the \meta{options} using the |\pgfkeys| command,
- documented in detail in Section~\ref{section-keys}, with the default path
- set to |/tikz|. Under normal circumstances, the \meta{options} will be
- lists of comma-separated pairs of the form \meta{key}|=|\meta{value}, but
- more fancy things can happen when you use the power of the |pgfkeys|
- mechanism, see Section~\ref{section-keys} once more.
-
- When a pair \meta{key}|=|\meta{value} is processed, the following happens:
- %
- \begin{enumerate}
- \item If the \meta{key} is a full key (starts with a slash) it is
- handled directly as described in Section~\ref{section-keys}.
- \item Otherwise (which is usually the case), it is checked whether
- |/tikz/|\meta{key} is a key and, if so, it is executed.
- \item Otherwise, it is checked whether |/pgf/|\meta{key} is a key
- and, if so, it is executed.
- \item Otherwise, it is checked whether \meta{key} is a color and, if
- so, |color=|\meta{key} is executed.
- \item Otherwise, it is checked whether \meta{key} contains a dash
- and, if so, |arrows=|\meta{key} is executed.
- \item Otherwise, it is checked whether \meta{key} is the name of a
- shape and, if so, |shape=|\meta{key} is executed.
- \item Otherwise, an error message is printed.
- \end{enumerate}
-
- Note that by the above description, all keys starting with |/tikz| and also
- all keys starting with |/pgf| can be used as \meta{key}s in an
- \meta{options} list.
-\end{command}
-
-
-\subsubsection{Using Styles to Manage How Pictures Look}
-
-There is a way of organizing sets of graphic options ``orthogonally'' to the
-normal scoping mechanism. For example, you might wish all your ``help lines''
-to be drawn in a certain way like, say, gray and thin (do \emph{not} dash them,
-that distracts). For this, you can use \emph{styles}.
-
-A style is a key that, when used, causes a set of graphic options to be
-processed. Once a style has been defined, it can be used like any other key.
-For example, the predefined |help lines| style, which you should use for lines
-in the background like grid lines or construction lines.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) grid +(2,2);
- \draw[help lines] (2,0) grid +(2,2);
-\end{tikzpicture}
-\end{codeexample}
-
-Defining styles is also done using options. Suppose we wish to define a style
-called |my style| and when this style is used, we want the draw color to be set
-to |red| and the fill color be set to |red!20|. To achieve this, we use the
-following option:
-%
-\begin{codeexample}[code only]
-my style/.style={draw=red,fill=red!20}
-\end{codeexample}
-
-The meaning of the curious |/.style| is the following: ``The key |my style|
-should not be used here but, rather, be defined. So, set up things such that
-using the key |my style| will, in the following, have the same effect as if we
-had written |draw=red,fill=red!20| instead.''
-
-Returning to the help lines example, suppose we prefer blue help lines. This
-could be achieved as follows:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[help lines/.style={blue!50,very thin}]
- \draw (0,0) grid +(2,2);
- \draw[help lines] (2,0) grid +(2,2);
-\end{tikzpicture}
-\end{codeexample}
-
-Naturally, one of the main ideas behind styles is that they can be used in
-different pictures. In this case, we have to use the |\tikzset| command
-somewhere at the beginning.
-%
-\begin{codeexample}[]
-\tikzset{help lines/.style={blue!50,very thin}}
-% ...
-\begin{tikzpicture}
- \draw (0,0) grid +(2,2);
- \draw[help lines] (2,0) grid +(2,2);
-\end{tikzpicture}
-\end{codeexample}
-
-Since styles are just special cases of |pgfkeys|'s general style facility, you
-can actually do quite a bit more. Let us start with adding options to an
-already existing style. This is done using |/.append style| instead of
-|/.style|:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[help lines/.append style=blue!50]
- \draw (0,0) grid +(2,2);
- \draw[help lines] (2,0) grid +(2,2);
-\end{tikzpicture}
-\end{codeexample}
-%
-In the above example, the option |blue!50| is appended to the style
-|help lines|, which now has the same effect as |black!50,very thin,blue!50|.
-Note that two colors are set, so the last one will ``win''. There also exists a
-handler called |/.prefix style| that adds something at the beginning of the
-style.
-
-Just as normal keys, styles can be parameterized. This means that you write
-\meta{style}|=|\meta{value} when you use the style instead of just
-\meta{style}. In this case, all occurrences of |#1| in \meta{style} are
-replaced by \meta{value}. Here is an example that shows how this can be used.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[outline/.style={draw=#1,thick,fill=#1!50}]
- \node [outline=red] at (0,1) {red};
- \node [outline=blue] at (0,0) {blue};
-\end{tikzpicture}
-\end{codeexample}
-
-For parameterized styles you can also set a \emph{default} value using the
-|/.default| handler:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[outline/.style={draw=#1,thick,fill=#1!50},
- outline/.default=black]
- \node [outline] at (0,1) {default};
- \node [outline=blue] at (0,0) {blue};
-\end{tikzpicture}
-\end{codeexample}
-
-For more details on using and setting styles, see also
-Section~\ref{section-keys}.
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-shapes.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-shapes.tex
deleted file mode 100644
index aa9b1a8962..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-shapes.tex
+++ /dev/null
@@ -1,3061 +0,0 @@
-% 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 slash 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 |\partname| 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:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-transformations.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-transformations.tex
deleted file mode 100644
index baa38cb438..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-transformations.tex
+++ /dev/null
@@ -1,499 +0,0 @@
-% Copyright 2018 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{Transformations}
-
-\pgfname\ has a powerful transformation mechanism that is similar to the
-transformation capabilities of \textsc{metafont}. The present section explains
-how you can access it in \tikzname.
-
-
-\subsection{The Different Coordinate Systems}
-
-It is a long process from a coordinate like, say, $(1,2)$ or
-$(1\mathrm{cm},5\mathrm{pt})$, to the position a point is finally placed on the
-display or paper. In order to find out where the point should go, it is
-constantly ``transformed'', which means that it is mostly shifted around and
-possibly rotated, slanted, scaled, and otherwise mutilated.
-
-In detail, (at least) the following transformations are applied to a coordinate
-like $(1,2)$ before a point on the screen is chosen:
-%
-\begin{enumerate}
- \item \pgfname\ interprets a coordinate like $(1,2)$ in its
- $xy$-coordinate system as ``add the current $x$-vector once and the
- current $y$-vector twice to obtain the new point''.
- \item \pgfname\ applies its coordinate transformation matrix to the
- resulting coordinate. This yields the final position of the point
- inside the picture.
- \item The backend driver (like |dvips| or |pdftex|) adds transformation
- commands such that the coordinate is shifted to the correct position in
- \TeX's page coordinate system.
- \item \textsc{pdf} (or PostScript) apply the canvas transformation matrix
- to the point, which can once more change the position on the page.
- \item The viewer application or the printer applies the device
- transformation matrix to transform the coordinate to its final pixel
- coordinate on the screen or paper.
-\end{enumerate}
-
-In reality, the process is even more involved, but the above should give the
-idea: A point is constantly transformed by changes of the coordinate system.
-
-In \tikzname, you only have access to the first two coordinate systems: The
-$xy$-coordinate system and the coordinate transformation matrix (these will be
-explained later). \pgfname\ also allows you to change the canvas transformation
-matrix, but you have to use commands of the core layer directly to do so and
-you ``better know what you are doing'' when you do this. The moment you start
-modifying the canvas matrix, \pgfname\ immediately loses track of all
-coordinates and shapes, anchors, and bounding box computations will no longer
-work.
-
-
-\subsection{The XY- and XYZ-Coordinate Systems}
-\label{section-xyz}
-
-The first and easiest coordinate systems are \pgfname's $xy$- and
-$xyz$-coordinate systems. The idea is very simple: Whenever you specify a
-coordinate like |(2,3)| this means $2v_x + 3v_y$, where $v_x$ is the current
-\emph{$x$-vector} and $v_y$ is the current \emph{$y$-vector}. Similarly, the
-coordinate |(1,2,3)| means $v_x + 2v_y + 3v_z$.
-
-Unlike other packages, \pgfname\ does not insist that $v_x$ actually has a
-$y$-component of $0$, that is, that it is a horizontal vector. Instead, the
-$x$-vector can point anywhere you want. Naturally, \emph{normally} you will
-want the $x$-vector to point horizontally.
-
-One undesirable effect of this flexibility is that it is not possible to
-provide mixed coordinates as in $(1,2\mathrm{pt})$. Life is hard.
-
-To change the $x$-, $y$-, and $z$-vectors, you can use the following options:
-
-\begin{key}{/tikz/x=\meta{value} (initially 1cm)}
- If \meta{value} is a dimension, the $x$-vector of \pgfname's
- $xyz$-coordinate system is set up to point \meta{value} to the right, that
- is, to $(\meta{value},0pt)$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) -- +(1,0);
- \draw[x=2cm,color=red] (0,0.1) -- +(1,0);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\tikz \draw[x=1.5cm] (0,0) grid (2,2);
-\end{codeexample}
-
- The last example shows that the size of steppings in grids, just like all
- other dimensions, are not affected by the $x$-vector. After all, the
- $x$-vector is only used to determine the coordinate of the upper right
- corner of the grid.
-
- If \meta{value} is a coordinate, the $x$-vector of \pgfname's
- $xyz$-coordinate system is set to the specified coordinate. If \meta{value}
- contains a comma, it must be put in braces.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) -- (1,0);
- \draw[x={(2cm,0.5cm)},color=red] (0,0) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
-
- You can use this, for example, to exchange the meaning of the $x$- and
- $y$-coordinate.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[smooth]
- \draw plot coordinates{(1,0) (2,0.5) (3,0) (3,1)};
- \draw[x={(0cm,1cm)},y={(1cm,0cm)},color=red]
- plot coordinates{(1,0) (2,0.5) (3,0) (3,1)};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/y=\meta{value} (initially 1cm)}
- Works like the |x=| option, only if \meta{value} is a dimension, the
- resulting vector points to $(0,\meta{value})$.
-\end{key}
-
-\begin{key}{/tikz/z=\meta{value} (initially \normalfont$-3.85$mm)}
- Works like the |y=| option, but now a dimension is the point
- $(\meta{value},\meta{value})$.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[z=-1cm,->,thick]
- \draw[color=red] (0,0,0) -- (1,0,0);
- \draw[color=blue] (0,0,0) -- (0,1,0);
- \draw[color=orange] (0,0,0) -- (0,0,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Coordinate Transformations}
-
-\pgfname\ and \tikzname\ allow you to specify \emph{coordinate
-transformations}. Whenever you specify a coordinate as in |(1,0)| or
-|(1cm,1pt)| or |(30:2cm)|, this coordinate is first ``reduced'' to a position
-of the form ``$x$ points to the right and $y$ points upwards''. For example,
-|(1in,5pt)| is reduced to ``$72\frac{72}{100}$ points to the right and 5 points
-upwards'' and |(90:100pt)| means ``0pt to the right and 100 points upwards''.
-
-The next step is to apply the current \emph{coordinate transformation matrix}
-to the coordinate. For example, the coordinate transformation matrix might
-currently be set such that it adds a certain constant to the $x$ value. Also,
-it might be set up such that it, say, exchanges the $x$ and $y$ value. In
-general, any ``standard'' transformation like translation, rotation, slanting,
-or scaling or any combination thereof is possible. (Internally, \pgfname\ keeps
-track of a coordinate transformation matrix very much like the concatenation
-matrix used by \textsc{pdf} or PostScript.)
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) rectangle (1,0.5);
- \begin{scope}[xshift=1cm]
- \draw [red] (0,0) rectangle (1,0.5);
- \draw[yshift=1cm] [blue] (0,0) rectangle (1,0.5);
- \draw[rotate=30] [orange] (0,0) rectangle (1,0.5);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-The most important aspect of the coordinate transformation matrix is \emph{that
-it applies to coordinates only!} In particular, the coordinate transformation
-has no effect on things like the line width or the dash pattern or the shading
-angle. In certain cases, it is not immediately clear whether the coordinate
-transformation matrix \emph{should} apply to a certain dimension. For example,
-should the coordinate transformation matrix apply to grids? (It does.) And what
-about the size of arced corners? (It does not.) The general rule is: ``If there
-is no `coordinate' involved, even `indirectly', the matrix is not applied.''.
-However, sometimes, you simply have to try or look it up in the documentation
-whether the matrix will be applied.
-
-Setting the matrix cannot be done directly. Rather, all you can do is to
-``add'' another transformation to the current matrix. However, all
-transformations are local to the current \TeX-group. All transformations are
-added using graphic options, which are described below.
-
-Transformations apply immediately when they are encountered ``in the middle of
-a path'' and they apply only to the coordinates on the path following the
-transformation option.
-%
-\begin{codeexample}[]
-\tikz \draw (0,0) rectangle (1,0.5) [xshift=2cm] (0,0) rectangle (1,0.5);
-\end{codeexample}
-
-A final word of warning: You should refrain from using ``aggressive''
-transformations like a scaling of a factor of 10\,000. The reason is that all
-transformations are done using \TeX, which has a fairly low accuracy.
-Furthermore, in certain situations it is necessary that \tikzname\
-\emph{inverts} the current transformation matrix and this will fail if the
-transformation matrix is badly conditioned or even singular (if you do not know
-what singular matrices are, you are blessed).
-
-\begin{key}{/tikz/shift={\ttfamily\char`\{}\meta{coordinate}{\ttfamily\char`\}}}
- Adds the \meta{coordinate} to all coordinates.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[shift={(1,1)},blue] (0,0) -- (1,1) -- (1,0);
- \draw[shift={(30:1cm)},red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/shift only}
- This option does not take any parameter. Its effect is to cancel all
- current transformations except for the shifting. This means that the origin
- will remain where it is, but any rotation around the origin or scaling
- relative to the origin or skewing will no longer have an effect.
-
- This option is useful in situations where a complicated transformation is
- used to ``get to a position'', but you then wish to draw something
- ``normal'' at this position.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[rotate=30,xshift=2cm,blue] (0,0) -- (1,1) -- (1,0);
- \draw[rotate=30,xshift=2cm,shift only,red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/xshift=\meta{dimension}}
- Adds \meta{dimension} to the $x$ value of all coordinates.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[xshift=2cm,blue] (0,0) -- (1,1) -- (1,0);
- \draw[xshift=-10pt,red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/yshift=\meta{dimension}}
- Adds \meta{dimension} to the $y$ value of all coordinates.
-\end{key}
-
-\begin{key}{/tikz/scale=\meta{factor}}
- Multiplies all coordinates by the given \meta{factor}. The \meta{factor}
- should not be excessively large in absolute terms or very close to zero.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[scale=2,blue] (0,0) -- (1,1) -- (1,0);
- \draw[scale=-1,red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/scale around={\ttfamily\char`\{}\meta{factor}|:|\meta{coordinate}{\ttfamily\char`\}}}
- Scales the coordinate system by \meta{factor}, with the ``origin of
- scaling'' centered on \meta{coordinate} rather than the origin.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[scale=2,blue] (0,0) -- (1,1) -- (1,0);
- \draw[scale around={2:(1,1)},red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/xscale=\meta{factor}}
- Multiplies only the $x$-value of all coordinates by the given
- \meta{factor}.
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[xscale=2,blue] (0,0) -- (1,1) -- (1,0);
- \draw[xscale=-1,red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/yscale=\meta{factor}}
- Multiplies only the $y$-value of all coordinates by \meta{factor}.
-\end{key}
-
-\begin{key}{/tikz/xslant=\meta{factor}}
- Slants the coordinate horizontally by the given \meta{factor}:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[xslant=2,blue] (0,0) -- (1,1) -- (1,0);
- \draw[xslant=-1,red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/yslant=\meta{factor}}
- Slants the coordinate vertically by the given \meta{factor}:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[yslant=2,blue] (0,0) -- (1,1) -- (1,0);
- \draw[yslant=-1,red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/rotate=\meta{degree}}
- Rotates the coordinate system by \meta{degree}:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[rotate=40,blue] (0,0) -- (1,1) -- (1,0);
- \draw[rotate=-20,red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/rotate around={\ttfamily\char`\{}\meta{degree}|:|\meta{coordinate}{\ttfamily\char`\}}}
- Rotates the coordinate system by \meta{degree} around the point
- \meta{coordinate}.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[rotate around={40:(1,1)},blue] (0,0) -- (1,1) -- (1,0);
- \draw[rotate around={-20:(1,1)},red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/rotate around x=\meta{angle}}
- This key sets the $x$, $y$ and $z$ vectors of the \pgfname\
- $xyz$-coordinate system so that they are rotated by \meta{angle} around the
- axis corresponding to the $x$-vector. The rotation is applied so that when
- looking towards the origin along this axis, positive angles result in an
- anticlockwise rotation.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[>=stealth]
- \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$};
- \draw [->] (0,0,0) -- (0,2,0) node [at end, left] {$y$};
- \draw [->] (0,0,0) -- (0,0,2) node [at end, left] {$z$};
-
- \draw [red, rotate around x=0] (0,0,0) -- (1,1,0) -- (1,0,0);
- \draw [green, rotate around x=45] (0,0,0) -- (1,1,0) -- (1,0,0);
- \draw [blue, rotate around x=90] (0,0,0) -- (1,1,0) -- (1,0,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/rotate around y=\meta{angle}}
- This key sets the $x$, $y$ and $z$ vectors of the \pgfname\
- $xyz$-coordinate system so that they are rotated by \meta{angle} around
- the axis corresponding to the $y$-vector. The rotation is applied so that
- when looking towards the origin along this axis, positive angles result in
- an anticlockwise rotation.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[>=stealth]
- \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$};
- \draw [->] (0,0,0) -- (0,2,0) node [at end, left] {$y$};
- \draw [->] (0,0,0) -- (0,0,2) node [at end, left] {$z$};
-
- \draw [red, rotate around y=0] (0,0,0) -- (1,1,0) -- (1,0,0);
- \draw [green, rotate around y=-45] (0,0,0) -- (1,1,0) -- (1,0,0);
- \draw [blue, rotate around y=-90] (0,0,0) -- (1,1,0) -- (1,0,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/rotate around z=\meta{angle}}
- This key sets the $x$, $y$ and $z$ vectors of the \pgfname\
- $xyz$-coordinate system so that they are rotated by \meta{angle} around the
- axis corresponding to the $z$-vector. The rotation is applied so that when
- looking towards the origin along this axis, positive angles result in an
- anticlockwise rotation.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[>=stealth]
- \draw [->] (0,0,0) -- (2,0,0) node [at end, right] {$x$};
- \draw [->] (0,0,0) -- (0,2,0) node [at end, left] {$y$};
- \draw [->] (0,0,0) -- (0,0,2) node [at end, left] {$z$};
-
- \draw [red, rotate around z=0] (0,0) -- (1,1) -- (1,0);
- \draw [green, rotate around z=45] (0,0) -- (1,1) -- (1,0);
- \draw [blue, rotate around z=90] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/cm={\ttfamily\char`\{}\meta{$a$}|,|\meta{$b$}|,|\meta{$c$}|,|\meta{$d$}|,|\meta{coordinate}{\ttfamily\char`\}}}
- applies the following transformation to all coordinates: Let $(x,y)$ be the
- coordinate to be transformed and let \meta{coordinate} specify the point
- $(t_x,t_y)$. Then the new coordinate is given by
- $\left(\begin{smallmatrix} a & c \\ b & d\end{smallmatrix}\right)
- \left(\begin{smallmatrix} x \\ y \end{smallmatrix}\right) +
- \left(\begin{smallmatrix} t_x \\ t_y \end{smallmatrix}\right)$.
- Usually, you do not use this option directly.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[cm={1,1,0,1,(0,0)},blue] (0,0) -- (1,1) -- (1,0);
- \draw[cm={0,1,1,0,(1cm,1cm)},red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/reset cm}
- Completely resets the coordinate transformation matrix to the identity
- matrix. This will destroy not only the transformations applied in the
- current scope, but also all transformations inherited from surrounding
- scopes. Do not use this option, unless you really, really know what you are
- doing.
-\end{key}
-
-
-\subsection{Canvas Transformations}
-
-A \emph{canvas transformation}, see
-Section~\ref{section-design-transformations} for details, is best thought of as
-a transformation in which the drawing canvas is stretched or rotated. Imaging
-writing something on a balloon (the canvas) and then blowing air into the
-balloon: Not only does the text become larger, the thin lines also become
-larger. In particular, if you scale the canvas by a factor of two, all lines
-are twice as thick.
-
-Canvas transformations should be used with great care. In most circumstances
-you do \emph{not} want line widths to change in a picture as this creates
-visual inconsistency.
-
-Just as important, when you use canvas transformations \emph{\pgfname\ loses
-track of positions of nodes and of picture sizes} since it does not take the
-effect of canvas transformations into account when it computes coordinates of
-nodes (do not, however, rely on this; it may change in the future).
-
-Finally, note that a canvas transformation always applies to a path as a whole,
-it is not possible (as for coordinate transformations) to use different
-transformations in different parts of a path.
-
-In short, you should not use canvas transformations unless you really know what
-you are doing.
-
-\begin{key}{/tikz/transform canvas=\meta{options}}
- The \meta{options} should contain coordinate transformations options like
- |scale| or |xshift|. Multiple options can be given, their effects
- accumulate in the usual manner. The effect of these \meta{options}
- (immediately) changes the current canvas transformation matrix. The
- coordinate transformation matrix is not changed. Tracking of the picture
- size is (locally) switched off and the node coordinate will no longer be
- correct.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[help lines] (0,0) grid (3,2);
- \draw (0,0) -- (1,1) -- (1,0);
- \draw[transform canvas={scale=2},blue] (0,0) -- (1,1) -- (1,0);
- \draw[transform canvas={rotate=180},red] (0,0) -- (1,1) -- (1,0);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-transparency.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-transparency.tex
deleted file mode 100644
index 1e2a20aba7..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-transparency.tex
+++ /dev/null
@@ -1,895 +0,0 @@
-% 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{Transparency}
-\label{section-tikz-transparency}
-
-\subsection{Overview}
-
-Normally, when you paint something using any of \tikzname's commands (this
-includes stroking, filling, shading, patterns, and images), the newly painted
-objects totally obscure whatever was painted earlier in the same area.
-
-You can change this behavior by using something that can be thought of as
-``(semi)transparent colors''. Such colors do not completely obscure the
-background, rather they blend the background with the new color. At first
-sight, using such semitransparent colors might seem quite straightforward, but
-the math going on in the background is quite involved and the correct handling
-of transparency fills some 64 pages in the PDF specification.
-
-In the present section, we start with the different ways of specifying ``how
-transparent'' newly drawn objects should be. The simplest way is to just
-specify a percentage like ``60\% transparent''. A much more general way is to
-use something that I call a \emph{fading}, also known as a soft mask or a mask.
-
-At the end of the section we address the problem of creating so-called
-\emph{transparency groups}. This problem arises when you paint over a position
-several times with a semitransparent color. Sometimes you want the effect to
-accumulate, sometimes you do not.
-
-\emph{Note:} Transparency (or Opacity, as it may be called as well) is best
-supported by the pdf\TeX\ driver. The \textsc{svg} driver also has some
-support. The PostScript file format does not know about transparency. In
-|dvips|-generated PostScript files, transparency of graphic objects is defined
-through special commands that need further processing to become visible in the
-\textsc{pdf} output. For this, a recent version of Ghostscript, preferably 9.52
-or newer, is required and its command line utility |ps2pdf| must be called with
-option |-dALLOWPSTRANSPARENCY|. Older versions may need option |-dNOSAFER|
-instead, but some advanced features, such as \emph{transparency groups} and
-\emph{fadings}, may not work at all. Printers and other programs will typically
-ignore opacity settings in PostScript files.
-
-
-\subsection{Specifying a Uniform Opacity}
-
-Specifying a stroke and/or fill opacity is quite easy using the following
-options.
-
-\begin{key}{/tikz/draw opacity=\meta{value}}
- This option sets ``how transparent'' lines should be. A value of |1| means
- ``fully opaque'' or ``not transparent at all'', a value of |0| means
- ``fully transparent'' or ``invisible''. A value of |0.5| yields lines that
- are semitransparent.
-
- Note that when you use PostScript as your output format, this option works
- only with recent versions of Ghostscript.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[line width=1ex]
- \draw (0,0) -- (3,1);
- \filldraw [fill=yellow!80!black,draw opacity=0.5] (1,0) rectangle (2,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-Note that the |draw opacity| options only sets the opacity of drawn lines. The
-opacity of fillings is set using the option |fill opacity| (documented in
-Section~\ref{section-fill-opacity}. The option |opacity| sets both at the same
-time.
-
-\begin{key}{/tikz/opacity=\meta{value}}
- Sets both the drawing and filling opacity to \meta{value}.
-
- The following predefined styles make it easier to use this option:
- %
- \begin{stylekey}{/tikz/transparent}
- Makes everything totally transparent and, hence, invisible.
- %
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[transparent,red] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \end{stylekey}
-
- \begin{stylekey}{/tikz/ultra nearly transparent}
- Makes everything, well, ultra nearly transparent.
- %
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[ultra nearly transparent] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \end{stylekey}
-
- \begin{stylekey}{/tikz/very nearly transparent}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[very nearly transparent] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \end{stylekey}
-
- \begin{stylekey}{/tikz/nearly transparent}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[nearly transparent] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \end{stylekey}
-
- \begin{stylekey}{/tikz/semitransparent}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[semitransparent] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \end{stylekey}
-
- \begin{stylekey}{/tikz/nearly opaque}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[nearly opaque] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \end{stylekey}
-
- \begin{stylekey}{/tikz/very nearly opaque}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[very nearly opaque] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \end{stylekey}
-
- \begin{stylekey}{/tikz/ultra nearly opaque}
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[ultra nearly opaque] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \end{stylekey}
-
- \begin{stylekey}{/tikz/opaque}
- This yields completely opaque drawings, which is the default.
- %
-\begin{codeexample}[]
-\tikz{\fill[red] (0,0) rectangle (1,0.5);
- \fill[opaque] (0.5,0) rectangle (1.5,0.25); }
-\end{codeexample}
- \end{stylekey}
-\end{key}
-
-\begin{key}{/tikz/fill opacity=\meta{value}}
- This option sets the opacity of fillings. In addition to filling
- operations, this opacity also applies to text and images.
-
- Note, again, that when you use PostScript as your output format, this
- option works only with recent versions of Ghostscript.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[thick,fill opacity=0.5]
- \filldraw[fill=red] (0:1cm) circle (12mm);
- \filldraw[fill=green] (120:1cm) circle (12mm);
- \filldraw[fill=blue] (-120:1cm) circle (12mm);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- \fill[red] (0,0) rectangle (3,2);
-
- \node at (0,0) {\huge A};
- \node[fill opacity=0.5] at (3,2) {\huge B};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/text opacity=\meta{value}}
- Sets the opacity of text labels, overriding the |fill opacity| setting.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[every node/.style={fill,draw}]
- \draw[line width=2mm,blue!50,line cap=round] (0,0) grid (3,2);
-
- \node[opacity=0.5] at (1.5,2) {Upper node};
- \node[draw opacity=0.8,fill opacity=0.2,text opacity=1]
- at (1.5,0) {Lower node};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-Note the following effect: If you set up a certain opacity for stroking or
-filling and you stroke or fill the same area twice, the effect accumulates:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[fill opacity=0.5]
- \fill[red] (0,0) circle (1);
- \fill[red] (1,0) circle (1);
-\end{tikzpicture}
-\end{codeexample}
-
-Often, this is exactly what you intend, but not always. You can use
-transparency groups, see the end of this section, to change this.
-
-
-\subsection{Blend Modes}
-\label{section-blend-modes}
-
-A \emph{blend mode} specifies how colors mix when you paint on a canvas.
-Normally, if you paint a red box on a green circle, the red color will
-completely replace the green circle. However, in some situations you might also
-wish the red color to somehow ``mix'' or ``blend'' with the green circle. We
-already saw that, using transparency, we can draw something without completely
-obscuring the background. \emph{Blending} is a similar operation, only here we
-mix colors in more complicated ways.
-
-\emph{Note:} Blending is a rather ``advanced'' feature of \textsc{pdf}. Most
-renderers, let alone printers, will have trouble rendering blending correctly.
-
-\begin{key}{/tikz/blend mode=\meta{mode}}
- Sets the current blend mode to \meta{mode}. Here \meta{mode} must be one of
- the modes listed below. More details on these modes can also be found in
- Section~7.2.4 of the \textsc{pdf} Specification, version~1.7.
-
- In the following example, the blend mode is only used and set inside a
- transparency group (see also Section~\ref{section-transparency-groups}).
- This is because most renderers (viewing programs) have trouble rendering
- blending correctly otherwise. For instance, at the time of writing, the
- versions of Adobe's Reader and Apple's Preview render the following drawing
- very differently, if the transparency group is not used in the following
- example.
- %
-\begin{codeexample}[]
-\tikz {
- \begin{scope}[transparency group]
- \begin{scope}[blend mode=screen]
- \fill[red!90!black] ( 90:.6) circle (1);
- \fill[green!80!black] (210:.6) circle (1);
- \fill[blue!90!black] (330:.6) circle (1);
- \end{scope}
- \end{scope}
-}
-\end{codeexample}
-
- Because of the trouble with rendering blending correctly outside
- transparency groups, there is a special key that establishes a transparency
- group and sets a blend mode simultaneously:
-
- \begin{key}{/tikz/blend group=\meta{mode}}
- This key can only be used with a scope (like |transparency group|). It
- will cause the current scope to become a transparency group and, inside
- this group, the blend mode will be set to \meta{mode}.
- %
-\begin{codeexample}[]
-\tikz [blend group=screen] {
- \fill[red!90!black] ( 90:.6) circle (1);
- \fill[green!80!black] (210:.6) circle (1);
- \fill[blue!90!black] (330:.6) circle (1);
-}
-\end{codeexample}
- \end{key}
-
- Here is an overview of the effects of the different available blend modes.
- In the examples, we always have three circles drawn on top of each other
- (as in the example code earlier): We start with a triple of pure red,
- green, and blue. Below it, we have a triple of light versions of these
- three colors (|red!50|, |green!50|, and |blue!50|). Next comes the triple
- yellow, cyan, and magenta; again with a triple of light versions below it.
- The large example consists of three balls (produced using |ball color|)
- having the colors red, green, and blue, are drawn on top of each other just
- like the circles.
-
- \definecolor{rg}{rgb}{1,1,0}
- \definecolor{gb}{rgb}{0,1,1}
- \definecolor{br}{rgb}{1,0,1}
-
- \def\makeline#1#2#3{\leavevmode
- \hbox to 40mm{#1\hss}\ \hbox to
- 20.5mm{#2\hss}\ \begin{minipage}[t]{88.5mm}\raggedright#3\end{minipage}\par
- \textcolor{black!25}{\hrule height1pt}
- }
-
- \def\showmode#1#2{
- \makeline{
- \tikz [blend mode=#1,baseline=-.5ex] {
- \fill[red] ( 90:.5em) circle (.75em);
- \fill[green] (210:.5em) circle (.75em);
- \fill[blue] (330:.5em) circle (.75em);
- \scoped[yshift=-2.5em]{
- \fill[red!50] ( 90:.5em) circle (.75em);
- \fill[green!50] (210:.5em) circle (.75em);
- \fill[blue!50] (330:.5em) circle (.75em);
- }
- }
- \tikz [blend mode=#1,baseline=-.5ex] {
- \fill[rg] ( 90:.5em) circle (.75em);
- \fill[gb] (210:.5em) circle (.75em);
- \fill[br] (330:.5em) circle (.75em);
- \scoped[yshift=-2.5em]{
- \fill[rg!50] ( 90:.5em) circle (.75em);
- \fill[gb!50] (210:.5em) circle (.75em);
- \fill[br!50] (330:.5em) circle (.75em);
- }
- }
- \tikz [blend mode=#1,baseline=-.5ex+1.25em] {
- \shade[ball color=red] ( 90:1em) circle (1.5em);
- \shade[ball color=green] (210:1em) circle (1.5em);
- \shade[ball color=blue] (330:1em) circle (1.5em);
- }}{\verb|#1|}{#2}%
- % this argument was changed from {|#1|}
- % --> see <https://sourceforge.net/p/pgf/bugs/486/>
- }
-
- \medskip
- \makeline{\emph{Example}}{\emph{Mode}}{\emph{Explanations quoted from
- Table~7.2 of the \textsc{pdf} Specification, Version~1.7}}
- \showmode{normal}{When painting a pixel with a some color (called the
- ``source color''), the background color (called the ``backdrop'') is
- completely ignored.}
- \showmode{multiply}{Multiplies the backdrop and source color values. The
- result color is always at least as dark as either of the two
- constituent colors. Multiplying any color with black produces black;
- multiplying with white leaves the original color unchanged. Painting
- successive overlapping objects with a color other than black or white
- produces progressively darker colors.}
- \showmode{screen}{Multiplies the complements of the backdrop and source
- color values, then complements the result. The result color is always
- at least as light as either of the two constituent colors. Screening
- any color with white produces white; screening with black leaves the
- original color unchanged. The effect is similar to projecting multiple
- photographic slides simultaneously onto a single screen.}
- \showmode{overlay}{Multiplies or screens the colors, depending on the
- backdrop color value. Source colors overlay the backdrop while
- preserving its highlights and shadows. The backdrop color is not
- replaced but is mixed with the source color to reflect the lightness or
- darkness of the backdrop.}
- \showmode{darken}{Selects the darker of the backdrop and source colors. The
- backdrop is replaced with the source where the source is darker;
- otherwise, it is left unchanged.}
- \showmode{lighten}{Selects the lighter of the backdrop and source colors.
- The backdrop is replaced with the source where the source is lighter;
- otherwise, it is left unchanged.}
- \showmode{color dodge}{Brightens the backdrop color to reflect the source
- color. Painting with black produces no changes.}
- \showmode{color burn}{Darkens the backdrop color to reflect the source
- color. Painting with white produces no change.}
- \showmode{hard light}{Multiplies or screens the colors, depending on the
- source color value. The effect is similar to shining a harsh spotlight
- on the backdrop.}
- \showmode{soft light}{Darkens or lightens the colors, depending on the
- source color value. The effect is similar to shining a diffused
- spotlight on the backdrop.}
- \showmode{difference}{Subtracts the darker of the two constituent colors
- from the lighter color. Painting with white inverts the backdrop color;
- painting with black produces no change.}
- \showmode{exclusion}{Produces an effect similar to that of the Difference
- mode but lower in contrast. Painting with white inverts the backdrop
- color; painting with black produces no change.}
- \showmode{hue}{Creates a color with the hue of the source color and the
- saturation and luminosity of the backdrop color.}
- \showmode{saturation}{Creates a color with the saturation of the source
- color and the hue and luminosity of the backdrop color. Painting with
- this mode in an area of the backdrop that is a pure gray (no
- saturation) produces no change.}
- \showmode{color}{Creates a color with the hue and saturation of the source
- color and the luminosity of the backdrop color. This preserves the gray
- levels of the backdrop and is useful for coloring monochrome images or
- tinting color images.}
- \showmode{luminosity}{Creates a color with the luminosity of the source
- color and the hue and saturation of the backdrop color. This produces
- an inverse effect to that of the Color mode.}
-\end{key}
-
-
-\subsection{Fadings}
-
-For complicated graphics, uniform transparency settings are not always
-sufficient. Suppose, for instance, that while you paint a picture, you want the
-transparency to vary smoothly from completely opaque to completely transparent.
-This is a ``shading-like'' transparency. For such a form of transparency I will
-use the term \emph{fading} (as a noun). They are also known as \emph{soft
-masks}, \emph{opacity masks}, \emph{masks}, or \emph{soft clips}.
-
-
-\subsubsection{Creating Fadings}
-
-How do we specify a fading? This is a bit of an art since the underlying
-mechanism is quite powerful, but a bit difficult to use.
-
-Let us start with a bit of terminology. A \emph{fading} specifies for each
-point of an area the transparency of that point. This transparency can by any
-number between 0 and 1. A \emph{fading picture} is a normal graphic that, in a
-way to be described in a moment, determines the transparency of points inside
-the fading. Each fading has an underlying fading picture.
-
-The fading picture is a normal graphic drawn using any of the normal graphic
-drawing commands. A fading and its fading picture are related as follows: Given
-any point of the fading, the transparency of this point is determined by the
-luminosity of the fading picture at the same position. The luminosity of a
-point determines ``how bright'' the point is. The brighter the point in the
-fading picture, the more opaque is the point in the fading. In particular, a
-white point of the fading picture is completely opaque in the fading and a
-black point of the fading picture is completely transparent in the fading. (The
-background of the fading picture is always transparent in the fading as if the
-background were black.)
-
-It is rather counter-intuitive that a \emph{white} pixel of the fading picture
-will be \emph{opaque} in the fading and a \emph{black} pixel will be
-\emph{transparent}. For this reason, \tikzname\ defines a color called
-|transparent| that is the same as |black|. The nice thing about this definition
-is that the color |transparent!|\meta{percentage} in the fading picture yields
-a pixel that is \meta{percentage} percent transparent in the fading.
-
-Turning a fading picture into a normal picture is achieved using the following
-commands, which are \emph{only defined in the library}, namely the library
-|fadings|. So, to use them, you have to say |\usetikzlibrary{fadings}| first.
-
-\begin{environment}{{tikzfadingfrompicture}\oarg{options}}
- This command works like a |{tikzpicture}|, only the picture is not shown,
- but instead a fading is defined based on this picture. To set the name of
- the picture, use the |name| option (which is normally used to set the name
- of a node).
- %
- \begin{key}{/tikz/name=\marg{name}}
- Use this option with the |{tikzfadingfrompicture}| environment to set
- the name of the fading. You \emph{must} provide this option.
- \end{key}
-
- The following shading is 2cm by 2cm and gets more and more transparent from
- left to right, but is 50\% transparent for a large circle in the middle.
- %
-{\ifpgfmanualexternalize\tikzexternaldisable\fi
-\begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
-\begin{tikzfadingfrompicture}[name=fade right with circle]
- \shade[left color=transparent!0,
- right color=transparent!100] (0,0) rectangle (2,2);
- \fill[transparent!50] (1,1) circle (0.7);
-\end{tikzfadingfrompicture}
-
-% Now we use the fading in another picture:
-\begin{tikzpicture}
- % Background
- \fill [black!20] (-1.2,-1.2) rectangle (1.2,1.2);
- \pattern [pattern=checkerboard,pattern color=black!30]
- (-1.2,-1.2) rectangle (1.2,1.2);
-
- \fill [path fading=fade right with circle,red] (-1,-1) rectangle (1,1);
-\end{tikzpicture}
-\end{codeexample}
- %
- In the next example we create a fading picture that contains some text.
- When the fading is used, we only see the shading ``through it''.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
-\begin{tikzfadingfrompicture}[name=tikz]
- \node [text=transparent!20]
- {\fontencoding{T1}\fontfamily{ptm}\fontsize{45}{45}\bfseries\selectfont
- Ti\emph{k}Z};
-\end{tikzfadingfrompicture}
-
-% Now we use the fading in another picture:
-\begin{tikzpicture}
- \fill [black!20] (-2,-1) rectangle (2,1);
- \pattern [pattern=checkerboard,pattern color=black!30]
- (-2,-1) rectangle (2,1);
-
- \shade[path fading=tikz,fit fading=false,
- left color=blue,right color=black]
- (-2,-1) rectangle (2,1);
-\end{tikzpicture}
-\end{codeexample}
-}%
-
- The same effect can also be achieved using knockout groups, see
- Section~\ref{section-transparency-groups}.
-\end{environment}
-
-\begin{plainenvironment}{{tikzfadingfrompicture}\oarg{options}}
- The plain\TeX\ version of the environment.
-\end{plainenvironment}
-
-\begin{contextenvironment}{{tikzfadingfrompicture}\oarg{options}}
- The Con\TeX t version of the environment.
-\end{contextenvironment}
-
-\begin{command}{\tikzfading\oarg{options}}
- This command is used to define a fading similarly to the way a shading is
- defined. In the \meta{options} you should
- %
- \begin{enumerate}
- \item use the |name=|\meta{name} option to set a name for the fading,
- \item use the |shading| option to set the name of the shading that you
- wish to use,
- \item extra options for setting the colors of the shading (typically
- you will set them to the color |transparent!|\meta{percentage}).
- \end{enumerate}
- %
- Then, a new fading named \meta{name} will be created based on the shading.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
-\tikzfading[name=fade right,
- left color=transparent!0,
- right color=transparent!100]
-
-% Now we use the fading in another picture:
-\begin{tikzpicture}
- % Background
- \fill [black!20] (-1.2,-1.2) rectangle (1.2,1.2);
- \path [pattern=checkerboard,pattern color=black!30]
- (-1.2,-1.2) rectangle (1.2,1.2);
-
- \fill [red,path fading=fade right] (-1,-1) rectangle (1,1);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
-\tikzfading[name=fade out,
- inner color=transparent!0,
- outer color=transparent!100]
-
-% Now we use the fading in another picture:
-\begin{tikzpicture}
- % Background
- \fill [black!20] (-1.2,-1.2) rectangle (1.2,1.2);
- \path [pattern=checkerboard,pattern color=black!30]
- (-1.2,-1.2) rectangle (1.2,1.2);
-
- \fill [blue,path fading=fade out] (-1,-1) rectangle (1,1);
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{command}
-
-
-\subsubsection{Fading a Path}
-
-A fading specifies for each pixel of a certain area how transparent this pixel
-will be. The following options are used to install such a fading for the
-current scope or path.
-
-\pgfdeclarefading{fade down}{%
- \tikzset{top color=pgftransparent!0,bottom color=pgftransparent!100}
- \pgfuseshading{axis}
-}
-\pgfdeclarefading{fade inside}{%
- \tikzset{inner color=pgftransparent!90,outer color=pgftransparent!30}
- \pgfuseshading{radial}
-}
-
-\begin{key}{/tikz/path fading=\meta{name} (default \normalfont scope's setting)}
- This option tells \tikzname\ that the current path should be faded with the
- fading \meta{name}. If no \meta{name} is given, the \meta{name} set for the
- whole scope is used. Similarly to options like |draw| or |fill|, this
- option is reset for each path, so you have to add it to each path that
- should be faded. You can also specify |none| as \meta{name}, in which case
- fading for the path will be switched off in case it has been switched on by
- previous options or styles.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
-\begin{tikzpicture}[path fading=south]
- % Checker board
- \fill [black!20] (0,0) rectangle (4,3);
- \pattern [pattern=checkerboard,pattern color=black!30]
- (0,0) rectangle (4,3);
-
- \fill [color=blue] (0.5,1.5) rectangle +(1,1);
- \fill [color=blue,path fading=north] (2.5,1.5) rectangle +(1,1);
-
- \fill [color=red,path fading] (1,0.75) ellipse (.75 and .5);
- \fill [color=red] (3,0.75) ellipse (.75 and .5);
-\end{tikzpicture}
-\end{codeexample}
-
- \begin{key}{/tikz/fit fading=\meta{boolean} (default true, initially true)}
- When set to |true|, the fading is shifted and resized (in exactly the
- same way as a shading) so that it covers the current path. When set to
- |false|, the fading is only shifted so that it is centered on the
- path's center, but it is not resized. This can be useful for
- special-purpose fadings, for instance when you use a fading to ``punch
- out'' something.
- \end{key}
-
- \begin{key}{/tikz/fading transform=\meta{transformation options}}
- The \meta{transformation options} are applied to the fading before it
- is used. For instance, if \meta{transformation options} is set to
- |rotate=90|, the fading is rotated by 90 degrees.
- %
-\begin{codeexample}[
- preamble={\usetikzlibrary{fadings,patterns}},
- pre={\pgfdeclarefading{fade down}{%
- \tikzset{top color=pgftransparent!0,bottom color=pgftransparent!100}
- \pgfuseshading{axis}
-}}]
-\begin{tikzpicture}[path fading=fade down]
- % Checker board
- \fill [black!20] (0,0) rectangle (4,1.5);
- \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,1.5);
-
- \fill [red,path fading,fading transform={rotate=90}]
- (1,0.75) ellipse (.75 and .5);
- \fill [red,path fading,fading transform={rotate=30}]
- (3,0.75) ellipse (.75 and .5);
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/fading angle=\meta{degree}}
- A shortcut for |fading transform={rotate=|\meta{degree}|}|.
- \end{key}
-
- Note that you can ``fade just about anything''. In particular, you can fade
- a shading.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
-\begin{tikzpicture}
- % Checker board
- \fill [black!20] (0,0) rectangle (4,4);
- \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,4);
-
- \shade [ball color=blue,path fading=south] (2,2) circle (1.8);
-\end{tikzpicture}
-\end{codeexample}
-
- The |fade inside| of the following example is more transparent in the
- middle than on the outside.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
-\tikzfading[name=fade inside,
- inner color=transparent!80,
- outer color=transparent!30]
-\begin{tikzpicture}
- % Checker board
- \fill [black!20] (0,0) rectangle (4,4);
- \path [pattern=checkerboard,pattern color=black!30] (0,0) rectangle (4,4);
-
- \shade [ball color=red] (3,3) circle (0.8);
- \shade [ball color=white,path fading=fade inside] (2,2) circle (1.8);
-\end{tikzpicture}
-\end{codeexample}
-
- Note that adding the |path fading| option to a node fades the (background)
- path, not the text itself. To fade the text, you need to use a scope fading
- (see below).
-\end{key}
-
-Note that using fadings in conjunction with patterns can create visually rather
-pleasing effects:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns,shadows}}]
-\tikzfading[name=middle,
- top color=transparent!50,
- bottom color=transparent!50,
- middle color=transparent!20]
-\begin{tikzpicture}
- \node [circle,circular drop shadow,
- pattern=horizontal lines dark blue,
- path fading=south,
- minimum size=3.6cm] {};
- \pattern [path fading=north,
- pattern=horizontal lines dark gray]
- (0,0) circle (1.8cm);
- \pattern [path fading=middle,
- pattern=crosshatch dots light steel blue]
- (0,0) circle (1.8cm);
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{Fading a Scope}
-
-In addition to fading individual paths, you may also wish to ``fade a scope'',
-that is, you may wish to install a fading that is used globally to specify the
-transparency for all objects drawn inside a scope. This effect can also be
-thought of as a ``soft clip'' and it works in a similar way: You add the
-|scope fading| option to a path in a scope -- typically the first one -- and
-then all subsequent drawings in the scope are faded. You will use a
-|transparency group| in conjunction, see the end of this section.
-
-\begin{key}{/tikz/scope fading=\meta{fading}}
- In principle, this key works in exactly the same way as the |path fading|
- key. The only difference is, that the effect of the fading will persist
- after the current path till the end of the scope. Thus, the \meta{fading}
- is applied to all subsequent drawings in the current scope, not just to the
- current path. In this regard, the option works very much like the |clip|
- option. (Note, however, that, unlike the |clip| option, fadings to not
- accumulate unless a transparency group is used.)
-
- The keys |fit fading| and |fading transform| have the same effect as for
- |path fading|. Also that, just as for |path fading|, providing the
- |scope fading| option with a |{scope}| only sets the name of the fading to
- be used. You have to explicitly provide the |scope fading| with a path to
- actually install a fading.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
-\begin{tikzpicture}
- \fill [black!20] (-2,-2) rectangle (2,2);
- \pattern [pattern=checkerboard,pattern color=black!30]
- (-2,-2) rectangle (2,2);
-
- % The bounding box of the shading:
- \draw [red] (-50bp,-50bp) rectangle (50bp,50bp);
-
- \path [scope fading=south,fit fading=false] (0,0);
- % fading is centered at its natural size
-
- \fill[red] ( 90:1) circle (1);
- \fill[green] (210:1) circle (1);
- \fill[blue] (330:1) circle (1);
-\end{tikzpicture}
-\end{codeexample}
-
- In the following example we resize the fading to the size of the whole
- picture:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fadings,patterns}}]
-\begin{tikzpicture}
- \fill [black!20] (-2,-2) rectangle (2,2);
- \pattern [pattern=checkerboard,pattern color=black!30]
- (-2,-2) rectangle (2,2);
-
- \path [scope fading=south] (-2,-2) rectangle (2,2);
-
- \fill[red] ( 90:1) circle (1);
- \fill[green] (210:1) circle (1);
- \fill[blue] (330:1) circle (1);
-\end{tikzpicture}
-\end{codeexample}
-
- Scope fadings are also needed if you wish to fade a node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{fadings}}]
-\tikz \node [scope fading=south,fading angle=45,text width=3.5cm]
-{
- This is some text that will fade out as we go right
- and down. It is pretty hard to achieve this effect in
- other ways.
-};
-\end{codeexample}
- %
-\end{key}
-
-
-\subsection{Transparency Groups}
-\label{section-transparency-groups}
-
-Consider the following cross and sign. They ``look wrong'' because we can see
-how they were constructed, while this is not really part of the desired effect.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[opacity=.5]
- \draw [line width=5mm] (0,0) -- (2,2);
- \draw [line width=5mm] (2,0) -- (0,2);
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};
-
- \node [opacity=.5]
- at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};
-\end{tikzpicture}
-\end{codeexample}
-
-Transparency groups are used to render them correctly:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[opacity=.5]
- \begin{scope}[transparency group]
- \draw [line width=5mm] (0,0) -- (2,2);
- \draw [line width=5mm] (2,0) -- (0,2);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.symbols}}]
-\begin{tikzpicture}
- \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};
-
- \begin{scope}[opacity=.5,transparency group]
- \node at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
- {Smoking};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{key}{/tikz/transparency group=\oarg{options}}
- This option can be given to a |scope|. It will have the following effect:
- The scope's contents is stroked\,/\penalty0\,filled ``ignoring any outside
- transparency''. This means, all previous transparency settings are ignored
- (you can still set transparency inside the group, but never mind). For
- instance, in the forbidden sign example, the whole sign is first painted
- (conceptually) like the image on the left hand side. Note that some pixels
- of the sign are painted multiple times (up to three times), but only the
- last color ``wins''.
-
- Then, when the scope is finished, it is painted as a whole. The \emph{fill}
- transparency settings are now applied to the resulting picture. For
- instance, the pixel that has been painted three times is just red at the
- end, so this red color will be blended with whatever is ``behind'' the
- group on the page.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns,shapes.symbols}}]
-\begin{tikzpicture}
- \pattern[pattern=checkerboard,pattern color=black!15](-1,-1) rectangle (3,1);
- \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};
-
- \begin{scope}[transparency group,opacity=.5]
- \node at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
- {Smoking};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
- Note that in the example, the |opacity=.5| is not active inside the
- transparency group: The group is only established at beginning of the scope
- and all options given to the |{scope}| environment are set before the group
- is established. To change the opacity \emph{inside} the group, you need to
- open another scope inside it or use the |opacity| key with a command inside
- the group:
- %
-\begin{codeexample}[preamble={\usetikzlibrary{patterns,shapes.symbols}}]
-\begin{tikzpicture}
- \pattern[pattern=checkerboard,pattern color=black!15](-1,-1) rectangle (3,1);
- \node at (0,0) [forbidden sign,line width=2ex,draw=red,fill=white] {Smoking};
-
- \begin{scope}[transparency group,opacity=.5]
- \node (s) at (2,0) [forbidden sign,line width=2ex,draw=red,fill=white]
- {Smoking};
-
- \draw [opacity=.5, line width=2ex, blue] (1.2,0) -- (2.8,0);
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
- The \meta{options} are a list of comma-separated options:
- %
- \begin{itemize}
- \item \declare{|knockout|} When this option is given inside the
- \meta{options}, the group becomes a so-called \emph{knockout}
- group. This means, essentially, that inside the group everything is
- painted as if the ``opacity'' of a line or area were just another
- color channel. In particular, if you paint a pixel with opacity $0$
- inside a knockout group, this pixel becomes perfectly transparent
- immediately. In contrast, painting a pixel with something of
- opacity $0$ normally has no effect.
-
- Not all renderers, let alone printers, will support this. At the
- time of writing, Apple's Preview will not show the following
- correctly (you should see the text \tikzname\ in the middle):
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \shade [left color=red,right color=blue] (-2,-1) rectangle (2,1);
- \begin{scope}[transparency group=knockout]
- \fill [white] (-1.9,-.9) rectangle (1.9,.9);
- \node [opacity=0,font=\fontencoding{T1}\fontfamily{ptm}\fontsize{45}{45}\bfseries]
- {Ti\emph{k}Z};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
- %
- In the example, we first draw a large shading and then, inside the
- transparency group ``overwrite'' most of this shading by a big
- white rectangle. The interesting part is the text of the node,
- which has opacity |0|. Normally, this would mean that nothing is
- shown. However, in a knockout group, we ``paint'' the text with an
- ``opacity zero'' color. The effect is that part of the totally
- opaque white rectangle gets overwritten by a perfectly transparent
- area (namely exactly the area taken up by the pixels of the text).
- When this whole knockout group is then placed on top of the
- shading, the shading will ``shine through'' at the knocked-out
- pixels.
-
- \item \declare{|isolated|}|=false| A group can be isolated or not. By
- default, they are isolated, since this is typically what you want.
- For details on what isolated groups are, exactly, see Section~7.3.4
- of the \textsc{pdf} Specification, version~1.7.
- \end{itemize}
-
- Note that when a transparency group is created, \tikzname\ must correctly
- determine the size of the material inside the group. Usually, this is no
- problem, but when you use things like |overlay| or |transform canvas|,
- trouble may result. In this case, please consult
- Section~\ref{section-transparency} on how to sidestep this problem in such
- cases.
-\end{key}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-trees.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-trees.tex
deleted file mode 100644
index d53ae5516c..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tikz-trees.tex
+++ /dev/null
@@ -1,868 +0,0 @@
-% 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{Making Trees Grow}
-\label{section-trees}
-
-\subsection{Introduction to the Child Operation}
-
-\emph{Trees} are a common way of visualizing hierarchical structures. A simple
-tree looks like this:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node {root}
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-\end{codeexample}
-
-Admittedly, in reality trees are more likely to grow \emph{upward} and not
-downward as above. You can tell whether the author of a paper is a
-mathematician or a computer scientist by looking at the direction their trees
-grow. A computer scientist's trees will grow downward while a mathematician's
-tree will grow upward. Naturally, the \emph{correct} way is the mathematician's
-way, which can be specified as follows:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node {root} [grow'=up]
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-\end{codeexample}
-
-In \tikzname, there are two ways of specifying trees: Using either the |graph|
-path operation, which is covered in Section~\ref{section-library-graphs}, or
-using the |child| path operation, which is covered in the present section. Both
-methods have their advantages.
-
-In \tikzname, trees are specified by adding \emph{children} to a node on a path
-using the |child| operation:
-
-\begin{pathoperation}{child}{\opt{\oarg{options}}%
- \opt{|foreach|\meta{variables}|in|\marg{values}}\opt{\marg{child path}}}
- This operation should directly follow a completed |node| operation or
- another |child| operation, although it is permissible that the first
- |child| operation is preceded by options (we will come to that).
-
- When a |node| operation like |node {X}| is followed by |child|, \tikzname\
- starts counting the number of child nodes that follow the original
- |node {X}|. For this, it scans the input and stores away each |child| and
- its arguments until it reaches a path operation that is not a |child|. Note
- that this will fix the character codes of all text inside the child
- arguments, which means, in essence, that you cannot use verbatim text
- inside the nodes inside a |child|. Sorry.
-
- Once the children have been collected and counted, \tikzname\ starts
- generating the child nodes. For each child of a parent node \tikzname\
- computes an appropriate position where the child is placed. For each child,
- the coordinate system is transformed so that the origin is at this
- position. Then the \meta{child path} is drawn. Typically, the child path
- just consists of a |node| specification, which results in a node being
- drawn at the child's position. Finally, an edge is drawn from the first
- node in the \meta{child path} to the parent node.
-
- The optional |foreach| part (note that there is no backslash before
- |foreach|) allows you to specify multiple children in a single |child|
- command. The idea is the following: A |\foreach| statement is (internally)
- used to iterate over the list of \meta{values}. For each value in this
- list, a new |child| is added to the node. The syntax for \meta{variables}
- and for \meta{values} is the same as for the |\foreach| statement, see
- Section~\ref{section-foreach}. For example, when you say
- %
-\begin{codeexample}[code only]
-node {root} child [red] foreach \name in {1,2} {node {\name}}
-\end{codeexample}
- %
- the effect will be the same as if you had said
- %
-\begin{codeexample}[code only]
-node {root} child[red] {node {1}} child[red] {node {2}}
-\end{codeexample}
- %
- When you write
- %
-\begin{codeexample}[code only]
-node {root} child[\pos] foreach \name/\pos in {1/left,2/right} {node[\pos] {\name}}
-\end{codeexample}
- %
- the effect will be the same as for
- %
-\begin{codeexample}[code only]
-node {root} child[left] {node[left] {1}} child[right] {node[right] {2}}
-\end{codeexample}
-
- You can nest things as in the following example:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- [level distance=4mm,level/.style={sibling distance=8mm/#1}]
- \coordinate
- child foreach \x in {0,1}
- {child foreach \y in {0,1}
- {child foreach \z in {0,1}}};
-\end{tikzpicture}
-\end{codeexample}
-
- The details and options for this operation are described in the rest of
- this present section.
-\end{pathoperation}
-
-
-\subsection{Child Paths and Child Nodes}
-
-For each |child| of a root node, its \meta{child path} is inserted at a
-specific location in the picture (the placement rules are discussed in
-Section~\ref{section-tree-placement}). The first node in the \meta{child path},
-if it exists, is special and called the \emph{child node}. If there is no first
-node in the \meta{child path}, that is, if the \meta{child path} is missing
-(including the curly braces) or if it does not start with |node| or with
-|coordinate|, then an empty child node of shape |coordinate| is automatically
-added.
-
-Consider the example |\node {x} child {node {y}} child;|. For the first child,
-the \meta{child path} has the child node |node {y}|. For the second child, no
-child node is specified and, thus, it is just |coordinate|.
-
-As for any normal node, you can give the child node a name, shift it around, or
-use options to influence how it is rendered.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
-\begin{tikzpicture}[sibling distance=15mm]
- \node[rectangle,draw] {root}
- child {node[circle,draw,yshift=-5mm] (left node) {left}}
- child {node[ellipse,draw] (right node) {right}};
- \draw[dashed,->] (left node) -- (right node);
-\end{tikzpicture}
-\end{codeexample}
-
-In many cases, the \meta{child path} will just consist of a specification of a
-child node and, possibly, children of this child node. However, the node
-specification may be followed by arbitrary other material that will be added to
-the picture, transformed to the child's coordinate system. For your
-convenience, a move-to |(0,0)| operation is inserted automatically at the
-beginning of the path. Here is an example:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node {root}
- child {[fill] circle (2pt)}
- child {[fill] circle (2pt)};
-\end{tikzpicture}
-\end{codeexample}
-
-At the end of the \meta{child path} you may add a special path operation called
-|edge from parent|. If this operation is not given by yourself somewhere on the
-path, it will be automatically added at the end. This option causes a
-connecting edge from the parent node to the child node to be added to the path.
-By giving options to this operation you can influence how the edge is rendered.
-Also, nodes following the |edge from parent| operation will be placed on this
-edge, see Section~\ref{section-edge-from-parent} for details.
-
-To sum up:
-%
-\begin{enumerate}
- \item The child path starts with a node specification. If it is not there,
- it is added automatically.
- \item The child path ends with a |edge from parent| operation, possibly
- followed by nodes to be put on this edge. If the operation is not given
- at the end, it is added automatically.
-\end{enumerate}
-
-
-\subsection{Naming Child Nodes}
-
-Child nodes can be named like any other node using either the |name| option or
-the special syntax in which the name of the node is placed in round parentheses
-between the |node| operation and the node's text.
-
-If you do not assign a name to a child node, \tikzname\ will automatically
-assign a name as follows: Assume that the name of the parent node is, say,
-|parent|. (If you did not assign a name to the parent, \tikzname\ will do so
-itself, but that name will not be user-accessible.) The first child of |parent|
-will be named |parent-1|, the second child is named |parent-2|, and so on.
-
-This naming convention works recursively. If the second child |parent-2| has
-children, then the first of these children will be called |parent-2-1| and the
-second |parent-2-2| and so on.
-
-If you assign a name to a child node yourself, no name is generated
-automatically (the node does not have two names). However, ``counting
-continues'', which means that the third child of |parent| is called |parent-3|
-independently of whether you have assigned names to the first and/or second
-child of |parent|.
-
-Here is an example:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[sibling distance=15mm]
- \node (root) {root}
- child
- child {
- child {coordinate (special)}
- child
- };
- \node at (root-1) {root-1};
- \node at (root-2) {root-2};
- \node at (special) {special};
- \node at (root-2-2) {root-2-2};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Specifying Options for Trees and Children}
-\label{section-tree-options}
-
-Each |child| may have its own \meta{options}, which apply to ``the whole
-child'', including all of its grandchildren. Here is an example:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- [thick,level 1/.style={sibling distance=15mm},
- level 2/.style={sibling distance=10mm}]
- \coordinate
- child[red] {child child}
- child[green] {child child[blue]};
-\end{tikzpicture}
-\end{codeexample}
-
-The options of the root node have no effect on the children since the options
-of a node are always ``local'' to that node. Because of this, the edges in the
-following tree are black, not red.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[thick]
- \node [red] {root}
- child
- child;
-\end{tikzpicture}
-\end{codeexample}
-%
-This raises the problem of how to set options for \emph{all} children.
-Naturally, you could always set options for the whole path as in
-|\path [red] node {root} child child;| but this is bothersome in some
-situations. Instead, it is easier to give the options \emph{before the first
-child} as follows:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[thick]
- \node [red] {root}
- [green] % option applies to all children
- child
- child;
-\end{tikzpicture}
-\end{codeexample}
-
-Here is the set of rules:
-%
-\begin{enumerate}
- \item Options for the whole tree are given before the root node.
- \item Options for the root node are given directly to the |node| operation
- of the root.
- \item Options for all children can be given between the root node and the
- first child.
- \item Options applying to a specific child path are given as options to the
- |child| operation.
- \item Options applying to the node of a child, but not to the whole child
- path, are given as options to the |node| command inside the \meta{child
- path}.
-\end{enumerate}
-%
-\begin{codeexample}[code only]
-\begin{tikzpicture}
- \scoped
- [...] % Options apply to the whole tree
- \node[...] {root} % Options apply to the root node only
- [...] % Options apply to all children
- child[...] % Options apply to this child and all its children
- {
- node[...] {} % Options apply to the child node only
- ...
- }
- child[...] % Options apply to this child and all its children
- ;
-\end{tikzpicture}
-\end{codeexample}
-
-There are additional styles that influence how children are rendered:
-%
-\begin{stylekey}{/tikz/every child (initially \normalfont empty)}
- This style is used at the beginning of each child, as if you had given the
- style's contents as options to the |child| operation.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/every child node (initially \normalfont empty)}
- This style is used at the beginning of each child node in addition to the
- |every node| style.
-\end{stylekey}
-
-\begin{stylekey}{/tikz/level=\meta{number} (initially \normalfont empty)}
- This style is executed at the beginning of each set of children, where
- \meta{number} is the current level in the current tree. For example, when
- you say |\node {x} child child;|, then |level=1| is used before the first
- |child|. The style or code of this key will be passed \meta{number} as its
- first parameter. If this first |child| has children itself, then |level=2|
- would be used for them.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[level/.style={sibling distance=20mm/#1}]
- \node {root}
- child { child child }
- child { child child child };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-\begin{stylekey}{/tikz/level \meta{number} (initially \normalfont empty)}
- This style is used in addition to the |level| style. So, when you say
- |\node {x} child child;|, then the following key list is executed:
- |level=1,level 1|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- [level 1/.style={sibling distance=20mm},
- level 2/.style={sibling distance=5mm}]
- \node {root}
- child { child child }
- child { child child child };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{stylekey}
-
-
-\subsection{Placing Child Nodes}
-\label{section-tree-placement}
-
-\subsubsection{Basic Idea}
-
-Perhaps the most difficult part in drawing a tree is the correct layout of the
-children. Typically, the children have different sizes and it is not easy to
-arrange them in such a manner that not too much space is wasted, the children
-do not overlap, and they are either evenly spaced or their centers are evenly
-distributed. Calculating good positions is especially difficult since a good
-position for the first child may depend on the size of the last child.
-
-In basic \tikzname, when you do not make use of the graph drawing facilities
-explained in Part~\ref{part-gd}, a comparatively simple approach is taken to
-placing the children. In order to compute a child's position, all that is taken
-into account is the number of the current child in the list of children and the
-number of children in this list. Thus, if a node has five children, then there
-is a fixed position for the first child, a position for the second child, and
-so on. These positions \emph{do not depend on the size of the children} and,
-hence, children can easily overlap. However, since you can use options to shift
-individual children a bit, this is not as great a problem as it may seem.
-
-Although the placement of the children only depends on their number in the list
-of children and the total number of children, everything else about the
-placement is highly configurable. You can change the distance between children
-(appropriately called the |sibling distance|) and the distance between levels
-of the tree. These distances may change from level to level. The direction in
-which the tree grows can be changed globally and for parts of the tree. You can
-even specify your own ``growth function'' to arrange children on a circle or
-along special lines or curves.
-
-
-\subsubsection{Default Growth Function}
-
-The default growth function works as follows: Assume that we are given a node
-and five children. These children will be placed on a line with their centers
-(or, more generally, with their anchors) spaced apart by the current
-|sibling distance|. The line is orthogonal to the current \emph{direction of
-growth}, which is set with the |grow| and |grow'| option (the latter option
-reverses the ordering of the children). The distance from the line to the
-parent node is given by the |level distance|.
-%
-{\catcode`\|=12
-\begin{codeexample}[]
-\begin{tikzpicture}[sibling distance=15mm, level distance=15mm]
- \path [help lines]
- node (root) {root}
- [grow=-10]
- child {node {1}}
- child {node {2}}
- child {node {3}}
- child {node {4}};
-
- \draw[|<->|,thick] (root-1.center)
- -- node[above,sloped] {sibling distance} (root-2.center);
-
- \draw[|<->|,thick] (root.center)
- -- node[above,sloped] {level distance} +(-10:\tikzleveldistance);
-\end{tikzpicture}
-\end{codeexample}
-}
-
-\begin{key}{/tikz/level distance=\meta{distance} (initially 15mm)}
- This key determines the distance between different levels of the tree, more
- precisely, between the parent and the line on which its children are
- arranged. When given to a single child, this will set the distance for this
- child only.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node {root}
- [level distance=20mm]
- child
- child {
- [level distance=5mm]
- child
- child
- child
- }
- child[level distance=10mm];
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- [level 1/.style={level distance=10mm},
- level 2/.style={level distance=5mm}]
- \node {root}
- child
- child {
- child
- child[level distance=10mm]
- child
- }
- child;
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/sibling distance=\meta{distance} (initially 15mm)}
- This key specifies the distance between the anchors of the children of a
- parent node.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- [level distance=4mm,
- level 1/.style={sibling distance=8mm},
- level 2/.style={sibling distance=4mm},
- level 3/.style={sibling distance=2mm}]
- \coordinate
- child {
- child {child child}
- child {child child}
- }
- child {
- child {child child}
- child {child child}
- };
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- [level distance=10mm,
- every node/.style={fill=red!60,circle,inner sep=1pt},
- level 1/.style={sibling distance=20mm,nodes={fill=red!45}},
- level 2/.style={sibling distance=10mm,nodes={fill=red!30}},
- level 3/.style={sibling distance=5mm,nodes={fill=red!25}}]
- \node {31}
- child {node {30}
- child {node {20}
- child {node {5}}
- child {node {4}}
- }
- child {node {10}
- child {node {9}}
- child {node {1}}
- }
- }
- child {node {20}
- child {node {19}
- child {node {1}}
- child[missing]
- }
- child {node {18}}
- };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/grow=\meta{direction}}
- This key is used to define the \meta{direction} in which the tree will
- grow. The \meta{direction} can either be an angle in degrees or one of the
- following special text strings: |down|, |up|, |left|, |right|, |north|,
- |south|, |east|, |west|, |north east|, |north west|, |south east|, and
- |south west|. All of these have ``their obvious meaning'', so, say,
- |south west| is the same as the angle $-135^\circ$.
-
- As a side effect, this option installs the default growth function.
-
- In addition to setting the direction, this option also has a seemingly
- strange effect: It sets the sibling distance for the current level to
- |0pt|, but leaves the sibling distance for later levels unchanged.
-
- This somewhat strange behavior has a highly desirable effect: If you give
- this option before the list of children of a node starts, the ``current
- level'' is still the parent level. Each child will be on a later level and,
- hence, the sibling distance will be as specified originally. This will
- cause the children to be neatly aligned in a line orthogonal to the given
- \meta{direction}. However, if you give this option locally to a single
- child, then ``current level'' will be the same as the child's level. The
- zero sibling distance will then cause the child to be placed exactly at a
- point at distance |level distance| in the direction \meta{direction}.
- However, the children of the child will be placed ``normally'' on a line
- orthogonal to the \meta{direction}.
-
- These placement effects are best demonstrated by some examples:
- %
-\begin{codeexample}[]
-\tikz \node {root} [grow=right] child child;
-\end{codeexample}
-
-\begin{codeexample}[]
-\tikz \node {root} [grow=south west] child child;
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[level distance=10mm,sibling distance=5mm]
- \node {root}
- [grow=down]
- child
- child
- child[grow=right] {
- child child child
- };
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}[level distance=2em]
- \node {C}
- child[grow=up] {node {H}}
- child[grow=left] {node {H}}
- child[grow=down] {node {H}}
- child[grow=right] {node {C}
- child[grow=up] {node {H}}
- child[grow=right] {node {H}}
- child[grow=down] {node {H}}
- edge from parent[double]
- coordinate (wrong)
- };
- \draw[<-,red] ([yshift=-2mm]wrong) -- +(0,-1)
- node[below]{This is wrong!};
-\end{tikzpicture}
-\end{codeexample}
-
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node[rectangle,draw] (a) at (0,0) {start node};
- \node[rectangle,draw] (b) at (2,1) {end};
-
- \draw (a) -- (b)
- node[coordinate,midway] {}
- child[grow=100,<-] {node[above] {the middle is here}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/grow'=\meta{direction}}
- This key has the same effect as |grow|, only the children are arranged in
- the opposite order.
-\end{key}
-
-
-\subsubsection{Missing Children}
-
-Sometimes one or more of the children of a node are ``missing''. Such a missing
-child will count as a child with respect to the total number of children and
-also with respect to the current child count, but it will not be rendered.
-
-\begin{key}{/tikz/missing=\meta{true or false} (default true)}
- If this option is given to a child, the current child counter is increased,
- but the child is otherwise ignored. In particular, the normal contents of
- the child is completely ignored.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[level distance=10mm,sibling distance=5mm]
- \node {root} [grow=down]
- child { node {1} }
- child { node {2} }
- child { node {3} }
- child[missing] { node {4} }
- child { node {5} }
- child { node {6} };
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-
-\subsubsection{Custom Growth Functions}
-
-\begin{key}{/tikz/growth parent anchor=\meta{anchor} (initially center)}
- This key allows you to specify which anchor of the parent node is to be
- used for computing the children's position. For example, when there is only
- one child and the |level distance| is |2cm|, then the child node will be
- placed two centimeters below the \meta{anchor} of the parent node. ``Being
- placed'' means that the child node's anchor (which is the anchor specified
- using the |anchor=| option in the |node| command of the child) is two
- centimeters below the parent node's \meta{anchor}.
-
- In the following example, the two red lines both have length |1cm|.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[level distance=1cm]
- \node [rectangle,draw] (a) at (0,0) {root}
- [growth parent anchor=south] child;
-
- \node [rectangle,draw] (b) at (2,0) {root}
- [growth parent anchor=north east] child;
-
- \draw [red,thick,dashed] (a.south) -- (a-1);
- \draw [red,thick,dashed] (b.north east) -- (b-1);
-\end{tikzpicture}
-\end{codeexample}
-
- In the next example, the top and bottom nodes are aligned at the top and
- the bottom, respectively.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- [level distance=2cm,growth parent anchor=north,
- every node/.style={anchor=north,rectangle,draw}
- every child node/.style={anchor=south}]
-
- \node at (0,0) {root} child {node {small}};
-
- \node at (2,0) {big root} child {node {\large big}};
-\end{tikzpicture}
-\end{codeexample}
- %
-\end{key}
-
-\begin{key}{/tikz/growth function=\meta{macro name} (initially \normalfont an internal function)}
- This rather low-level option allows you to set a new growth function. The
- \meta{macro name} must be the name of a macro without parameters. This
- macro will be called for each child of a node. The initial function is an
- internal function that corresponds to downward growth.
-
- The effect of executing the macro should be the following: It should
- transform the coordinate system in such a way that the origin becomes the
- place where the current child should be anchored. When the macro is called,
- the current coordinate system will be set up such that the anchor of the
- parent node is in the origin. Thus, in each call, the \meta{macro name}
- must essentially do a shift to the child's origin. When the macro is
- called, the \TeX\ counter |\tikznumberofchildren| will be set to the total
- number of children of the parent node and the counter
- |\tikznumberofcurrentchild| will be set to the number of the current child.
-
- The macro may, in addition to shifting the coordinate system, also
- transform the coordinate system further. For example, it could be rotated
- or scaled.
-
- Additional growth functions are defined in the library, see
- Section~\ref{section-tree-library}.
-\end{key}
-
-
-\subsection{Edges From the Parent Node}
-\label{section-edge-from-parent}
-
-Every child node is connected to its parent node via a special kind of edge
-called the |edge from parent|. This edge is added to the \meta{child path} when
-the following path operation is encountered:
-
-\begin{pathoperation}{edge from parent}{\opt{\oarg{options}}}
- This path operation can only be used inside \meta{child paths} and should
- be given at the end, possibly followed by \meta{node specifications} like
- |node {a}|. If a \meta{child path} does not contain this operation, it will
- be added at the end of the \meta{child path} automatically.
-
- By default, this operation does the following:
- %
- \begin{enumerate}
- \item The following style is executed:
- %
- \begin{stylekey}{/tikz/edge from parent (initially draw)}
- This style is inserted right before the |edge from parent path|
- and before the \meta{options} are inserted.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- [edge from parent/.style={draw,red,thick}]
- \node {root}
- child {node {left} edge from parent[dashed]}
- child {node {right}
- child {node {child}}
- child {node {child} edge from parent[draw=none]}
- };
-\end{tikzpicture}
-\end{codeexample}
- \end{stylekey}
- \item Next, the \meta{options} are executed.
- \item Next, the text stored in the following key is inserted:
- %
- \begin{key}{/tikz/edge from parent path=\meta{path} (initially \normalfont code shown below)}
- This option allows you to set the |edge from parent path| to a
- new path. Initially, this path is the following:
- %
-\begin{codeexample}[code only]
-(\tikzparentnode\tikzparentanchor) -- (\tikzchildnode\tikzchildanchor)
-\end{codeexample}
- %
- The |\tikzparentnode| is a macro that will expand to the name
- of the parent node. This works even when you have not assigned
- a name to the parent node, in this case an internal name is
- automatically generated. The |\tikzchildnode| is a macro that
- expands to the name of the child node. The two |...anchor|
- macros are empty by default. So, what is essentially inserted
- is just the path segment
- |(\tikzparentnode) -- (\tikzchildnode)|; which is exactly an
- edge from the parent to the child.
-
- You can modify this edge from parent path to achieve all sorts
- of effects. For example, we could replace the straight line by
- a curve as follows:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}[level distance=15mm, sibling distance=15mm,
- edge from parent path=
- {(\tikzparentnode.south) .. controls +(0,-1) and +(0,1)
- .. (\tikzchildnode.north)}]
- \node {root}
- child {node {left}}
- child {node {right}
- child {node {child}}
- child {node {child}}
- };
-\end{tikzpicture}
-\end{codeexample}
-
- Further useful |edge from parent path|s are defined in the tree
- library, see Section~\ref{section-tree-library}.
-
- The nodes in a \meta{node specification} following the
- |edge from parent| path command get executed as if the |pos|
- option had been added to all these nodes, see also
- Section~\ref{section-pos-option}.
-
- As an example, consider the following code:
- %
-\begin{codeexample}[code only]
-\node (root) {} child {node (child) {} edge to parent node {label}};
-\end{codeexample}
- %
- The |edge to parent| operation and the following |node|
- operation will, together, have the same effect as if we had
- said:
- %
-\begin{codeexample}[code only]
-(root) -- (child) node [pos=0.5] {label}
-\end{codeexample}
-
- Here is a more complicated example:
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node {root}
- child {
- node {left}
- edge from parent
- node[left] {a}
- node[right] {b}
- }
- child {
- node {right}
- child {
- node {child}
- edge from parent
- node[left] {c}
- }
- child {node {child}}
- edge from parent
- node[near end] {x}
- };
-\end{tikzpicture}
-\end{codeexample}
-
- As said before, the anchors in the default
- |edge from parent path| are empty. However, you can set them
- using the following keys:
- %
- \begin{key}{/tikz/child anchor=\meta{anchor} (initially border)}
- Specifies the anchor where the edge from parent meets the
- child node by setting the macro |\tikzchildanchor| to
- |.|\meta{anchor}.
-
- If you specify |border| as the \meta{anchor}, then the
- macro |\tikzchildanchor| is set to the empty string. The
- effect of this is that the edge from the parent will meet
- the child on the border at an automatically calculated
- position.
- %
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node {root}
- [child anchor=north]
- child {node {left} edge from parent[dashed]}
- child {node {right}
- child {node {child}}
- child {node {child} edge from parent[draw=none]}
- };
-\end{tikzpicture}
-\end{codeexample}
- \end{key}
-
- \begin{key}{/tikz/parent anchor=\meta{anchor} (initially border)}
- This option works the same way as the |child anchor|, only
- for the parent.
- \end{key}
- \end{key}
- \end{enumerate}
-
- All of the above describes the standard functioning of the
- |edge from parent| command. You may, however, sometimes need even more
- fine-grained control (the graph drawing engine needs it, for instance). In
- such cases the following key gives you complete control:
- %
- \begin{key}{/tikz/edge from parent macro=\meta{macro}}
- The \meta{macro} gets expanded each time the |edge from parent| path
- operation is used. This \meta{macro} must take two parameters and must
- expand to some text that is subsequently parsed by the parser. The
- first parameter will be the set of \meta{options} that where passed to
- the |edge from parent| command, the second parameter will be the
- \meta{node specifications} that following the command.
-
- The standard behavior of drawing a straight line from the parent node
- to the child node could be achieved by setting the \meta{macro} to the
- following:
- %
-\begin{codeexample}[code only]
-\def\mymacro#1#2{
- [style=edge from parent, #1]
- (\tikzparentnode\tikzparentanchor) -- #2 (\tikzchildnode\tikzchildanchor)
-}
-\end{codeexample}
- %
- Note that |#2| is placed between |--| and the node to ensure that nodes
- are put ``on top'' of the line.
- \end{key}
-\end{pathoperation}
-
-
-%%% Local Variables:
-%%% mode: latex
-%%% TeX-master: "pgfmanual-pdftex-version"
-%%% End:
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-Euclid.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-Euclid.tex
deleted file mode 100644
index 228cfbbe19..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-Euclid.tex
+++ /dev/null
@@ -1,692 +0,0 @@
-% 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{Tutorial: Euclid's Amber Version of the \emph{Elements}}
-
-In this third tutorial we have a look at how \tikzname\ can be used to draw
-geometric constructions.
-
-Euclid is currently quite busy writing his new book series, whose working title
-is ``Elements'' (Euclid is not quite sure whether this title will convey the
-message of the series to future generations correctly, but he intends to change
-the title before it goes to the publisher). Up to now, he wrote down his text
-and graphics on papyrus, but his publisher suddenly insists that he must submit
-in electronic form. Euclid tries to argue with the publisher that electronics
-will only be discovered thousands of years later, but the publisher informs him
-that the use of papyrus is no longer cutting edge technology and Euclid will
-just have to keep up with modern tools.
-
-Slightly disgruntled, Euclid starts converting his papyrus entitled ``Book I,
-Proposition I'' to an amber version.
-
-
-\subsection{Book I, Proposition I}
-
-The drawing on his papyrus looks like this:\footnote{The text is taken from the
-wonderful interactive version of Euclid's Elements by David E. Joyce, to be
-found on his website at Clark University.}
-
-\bigskip
-\noindent
-\begin{tikzpicture}[thick,help lines/.style={thin,draw=black!50}]
- \pgfmathsetseed{1}
- \def\A{\textcolor{input}{$A$}}
- \def\B{\textcolor{input}{$B$}}
- \def\C{\textcolor{output}{$C$}}
- \def\D{$D$}
- \def\E{$E$}
-
- \colorlet{input}{blue!80!black}
- \colorlet{output}{red!70!black}
- \colorlet{triangle}{orange}
-
- \coordinate [label=left:\A]
- (A) at ($ (0,0) + .1*(rand,rand) $);
- \coordinate [label=right:\B]
- (B) at ($ (1.25,0.25) + .1*(rand,rand) $);
-
- \draw [input] (A) -- (B);
-
- \node [name path=D,help lines,draw,label=left:\D] (D) at (A) [circle through=(B)] {};
- \node [name path=E,help lines,draw,label=right:\E] (E) at (B) [circle through=(A)] {};
-
- \path [name intersections={of=D and E,by={[label=above:\C]C}}];
-
- \draw [output] (A) -- (C);
- \draw [output] (B) -- (C);
-
- \foreach \point in {A,B,C}
- \fill [black,opacity=.5] (\point) circle (2pt);
-
- \begin{pgfonlayer}{background}
- \fill[triangle!80] (A) -- (C) -- (B) -- cycle;
- \end{pgfonlayer}
-
- \node [below right,text width=10cm,align=justify] at (4,3)
- {
- \small
- \textbf{Proposition I}\par
- \emph{To construct an \textcolor{triangle}{equilateral triangle}
- on a given \textcolor{input}{finite straight line}.}
- \par
- \vskip1em
- Let \A\B\ be the given \textcolor{input}{finite straight line}. It
- is required to construct an \textcolor{triangle}{equilateral
- triangle} on the \textcolor{input}{straight line}~\A\B.
-
- Describe the circle \B\C\D\ with center~\A\ and radius \A\B. Again
- describe the circle \A\C\E\ with center~\B\ and radius \B\A. Join the
- \textcolor{output}{straight lines} \C\A\ and \C\B\ from the
- point~\C\ at which the circles cut one another to the points~\A\ and~\B.
-
- Now, since the point~\A\ is the center of the circle \C\D\B,
- therefore \A\C\ equals \A\B. Again, since the point \B\ is the
- center of the circle \C\A\E, therefore \B\C\ equals \B\A. But
- \A\C\ was proved equal to \A\B, therefore each of the straight
- lines \A\C\ and \B\C\ equals \A\B. And
- things which equal the same thing also equal one another,
- therefore \A\C\ also equals \B\C. Therefore the three straight
- lines \A\C, \A\B, and \B\C\ equal one another.
- Therefore the \textcolor{triangle}{triangle} \A\B\C\ is
- equilateral, and it has been constructed on the given finite
- \textcolor{input}{straight line}~\A\B.
- };
-\end{tikzpicture}
-\bigskip
-
-Let us have a look at how Euclid can turn this into \tikzname\ code.
-
-
-\subsubsection{Setting up the Environment}
-
-As in the previous tutorials, Euclid needs to load \tikzname, together with
-some libraries. These libraries are |calc|, |intersections|, |through|, and
-|backgrounds|. Depending on which format he uses, Euclid would use one of the
-following in the preamble:
-%
-\begin{codeexample}[code only]
-% For LaTeX:
-\usepackage{tikz}
-\usetikzlibrary{calc,intersections,through,backgrounds}
-\end{codeexample}
-
-\begin{codeexample}[code only]
-% For plain TeX:
-\input tikz.tex
-\usetikzlibrary{calc,intersections,through,backgrounds}
-\end{codeexample}
-
-\begin{codeexample}[code only]
-% For ConTeXt:
-\usemodule[tikz]
-\usetikzlibrary[calc,intersections,through,backgrounds]
-\end{codeexample}
-
-
-\subsubsection{The Line \emph{AB}}
-
-The first part of the picture that Euclid wishes to draw is the line $AB$. That
-is easy enough, something like |\draw (0,0) -- (2,1);| might do. However,
-Euclid does not wish to reference the two points $A$ and $B$ as $(0,0)$ and
-$(2,1)$ subsequently. Rather, he wishes to just write |A| and |B|. Indeed, the
-whole point of his book is that the points $A$ and $B$ can be arbitrary and all
-other points (like $C$) are constructed in terms of their positions. It would
-not do if Euclid were to write down the coordinates of $C$ explicitly.
-
-So, Euclid starts with defining two coordinates using the |\coordinate|
-command:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \coordinate (A) at (0,0);
- \coordinate (B) at (1.25,0.25);
-
- \draw[blue] (A) -- (B);
-\end{tikzpicture}
-\end{codeexample}
-
-That was easy enough. What is missing at this point are the labels for the
-coordinates. Euclid does not want them \emph{on} the points, but next to them.
-He decides to use the |label| option:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \coordinate [label=left:\textcolor{blue}{$A$}] (A) at (0,0);
- \coordinate [label=right:\textcolor{blue}{$B$}] (B) at (1.25,0.25);
-
- \draw[blue] (A) -- (B);
-\end{tikzpicture}
-\end{codeexample}
-
-At this point, Euclid decides that it would be even nicer if the points $A$ and
-$B$ were in some sense ``random''. Then, neither Euclid nor the reader can make
-the mistake of taking ``anything for granted'' concerning these position of
-these points. Euclid is pleased to learn that there is a |rand| function in
-\tikzname\ that does exactly what he needs: It produces a number between $-1$
-and $1$. Since \tikzname\ can do a bit of math, Euclid can change the
-coordinates of the points as follows:
-%
-\begin{codeexample}[code only]
-\coordinate [...] (A) at (0+0.1*rand,0+0.1*rand);
-\coordinate [...] (B) at (1.25+0.1*rand,0.25+0.1*rand);
-\end{codeexample}
-
-This works fine. However, Euclid is not quite satisfied since he would prefer
-that the ``main coordinates'' $(0,0)$ and $(1.25,0.25)$ are ``kept separate''
-from the perturbation $0.1(\mathit{rand},\mathit{rand})$. This means, he would
-like to specify that coordinate $A$ as ``the point that is at $(0,0)$ plus one
-tenth of the vector $(\mathit{rand},\mathit{rand})$''.
-
-It turns out that the |calc| library allows him to do exactly this kind of
-computation. When this library is loaded, you can use special coordinates that
-start with |($| and end with |$)| rather than just |(| and~|)|. Inside these
-special coordinates you can give a linear combination of coordinates. (Note
-that the dollar signs are only intended to signal that a ``computation'' is
-going on; no mathematical typesetting is done.)
-
-The new code for the coordinates is the following:
-%
-\begin{codeexample}[code only]
-\coordinate [...] (A) at ($ (0,0) + .1*(rand,rand) $);
-\coordinate [...] (B) at ($ (1.25,0.25) + .1*(rand,rand) $);
-\end{codeexample}
-
-Note that if a coordinate in such a computation has a factor (like |.1|), you
-must place a |*| directly before the opening parenthesis of the coordinate. You
-can nest such computations.
-
-
-\subsubsection{The Circle Around \emph{A}}
-
-The first tricky construction is the circle around~$A$. We will see later how
-to do this in a very simple manner, but first let us do it the ``hard'' way.
-
-The idea is the following: We draw a circle around the point $A$ whose radius
-is given by the length of the line $AB$. The difficulty lies in computing the
-length of this line.
-
-Two ideas ``nearly'' solve this problem: First, we can write |($ (A) - (B) $)|
-for the vector that is the difference between $A$ and~$B$. All we need is the
-length of this vector. Second, given two numbers $x$ and $y$, one can write
-|veclen(|$x$|,|$y$|)| inside a mathematical expression. This gives the value
-$\sqrt{x^2+y^2}$, which is exactly the desired length.
-
-The only remaining problem is to access the $x$- and $y$-coordinate of the
-vector~$AB$. For this, we need a new concept: the \emph{let operation}. A let
-operation can be given anywhere on a path where a normal path operation like a
-line-to or a move-to is expected. The effect of a let operation is to evaluate
-some coordinates and to assign the results to special macros. These macros make
-it easy to access the $x$- and $y$-coordinates of the coordinates.
-
-Euclid would write the following:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (1.25,0.25);
- \draw (A) -- (B);
-
- \draw (A) let
- \p1 = ($ (B) - (A) $)
- in
- circle ({veclen(\x1,\y1)});
-\end{tikzpicture}
-\end{codeexample}
-
-Each assignment in a let operation starts with |\p|, usually followed by a
-\meta{digit}. Then comes an equal sign and a coordinate. The coordinate is
-evaluated and the result is stored internally. From then on you can use the
-following expressions:
-%
-\begin{enumerate}
- \item |\x|\meta{digit} yields the $x$-coordinate of the resulting point.
- \item |\y|\meta{digit} yields the $y$-coordinate of the resulting point.
- \item |\p|\meta{digit} yields the same as
- |\x|\meta{digit}|,\y|\meta{digit}.
-\end{enumerate}
-%
-You can have multiple assignments in a let operation, just separate them with
-commas. In later assignments you can already use the results of earlier
-assignments.
-
-Note that |\p1| is not a coordinate in the usual sense. Rather, it just expands
-to a string like |10pt,20pt|. So, you cannot write, for instance,
-|(\p1.center)| since this would just expand to |(10pt,20pt.center)|, which
-makes no sense.
-
-Next, we want to draw both circles at the same time. Each time the radius is
-|veclen(\x1,\y1)|. It seems natural to compute this radius only once. For this,
-we can also use a let operation: Instead of writing |\p1 = ...|, we write
-|\n2 = ...|. Here, ``n'' stands for ``number'' (while ``p'' stands for
-``point''). The assignment of a number should be followed by a number in curly
-braces.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (1.25,0.25);
- \draw (A) -- (B);
-
- \draw let \p1 = ($ (B) - (A) $),
- \n2 = {veclen(\x1,\y1)}
- in
- (A) circle (\n2)
- (B) circle (\n2);
-\end{tikzpicture}
-\end{codeexample}
-%
-In the above example, you may wonder, what |\n1| would yield? The answer is
-that it would be undefined -- the |\p|, |\x|, and |\y| macros refer to the same
-logical point, while the |\n| macro has ``its own namespace''. We could even
-have replaced |\n2| in the example by |\n1| and it would still work. Indeed,
-the digits following these macros are just normal \TeX\ parameters. We could
-also use a longer name, but then we have to use curly braces:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (1.25,0.25);
- \draw (A) -- (B);
-
- \draw let \p1 = ($ (B) - (A) $),
- \n{radius} = {veclen(\x1,\y1)}
- in
- (A) circle (\n{radius})
- (B) circle (\n{radius});
-\end{tikzpicture}
-\end{codeexample}
-
-At the beginning of this section it was promised that there is an easier way to
-create the desired circle. The trick is to use the |through| library. As the
-name suggests, it contains code for creating shapes that go through a given
-point.
-
-The option that we are looking for is |circle through|. This option is given to
-a \emph{node} and has the following effects: First, it causes the node's inner
-and outer separations to be set to zero. Then it sets the shape of the node to
-|circle|. Finally, it sets the radius of the node such that it goes through the
-parameter given to |circle through|. This radius is computed in essentially the
-same way as above.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{through}}]
-\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (1.25,0.25);
- \draw (A) -- (B);
-
- \node [draw,circle through=(B),label=left:$D$] at (A) {};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{The Intersection of the Circles}
-
-Euclid can now draw the line and the circles. The final problem is to compute
-the intersection of the two circles. This computation is a bit involved if you
-want to do it ``by hand''. Fortunately, the |intersections| library allows us
-to compute the intersection of arbitrary paths.
-
-The idea is simple: First, you ``name'' two paths using the |name path| option.
-Then, at some later point, you can use the option |name intersections|, which
-creates coordinates called |intersection-1|, |intersection-2|, and so on at all
-intersections of the paths. Euclid assigns the names |D| and |E| to the paths
-of the two circles (which happen to be the same names as the nodes themselves,
-but nodes and their paths live in different ``namespaces'').
-%
-\begin{codeexample}[preamble={\usetikzlibrary{intersections,through}}]
-\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (1.25,0.25);
- \draw (A) -- (B);
-
- \node (D) [name path=D,draw,circle through=(B),label=left:$D$] at (A) {};
- \node (E) [name path=E,draw,circle through=(A),label=right:$E$] at (B) {};
-
- % Name the coordinates, but do not draw anything:
- \path [name intersections={of=D and E}];
-
- \coordinate [label=above:$C$] (C) at (intersection-1);
-
- \draw [red] (A) -- (C);
- \draw [red] (B) -- (C);
-\end{tikzpicture}
-\end{codeexample}
-
-It turns out that this can be further shortened: The |name intersections| takes
-an optional argument |by|, which lets you specify names for the coordinates and
-options for them. This creates more compact code. Although Euclid does not need
-it for the current picture, it is just a small step to computing the bisection
-of the line $AB$:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{intersections,through}}]
-\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (1.25,0.25);
- \draw [name path=A--B] (A) -- (B);
-
- \node (D) [name path=D,draw,circle through=(B),label=left:$D$] at (A) {};
- \node (E) [name path=E,draw,circle through=(A),label=right:$E$] at (B) {};
-
- \path [name intersections={of=D and E, by={[label=above:$C$]C, [label=below:$C'$]C'}}];
-
- \draw [name path=C--C',red] (C) -- (C');
-
- \path [name intersections={of=A--B and C--C',by=F}];
- \node [fill=red,inner sep=1pt,label=-45:$F$] at (F) {};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{The Complete Code}
-
-Back to Euclid's code. He introduces a few macros to make life simpler, like a
-|\A| macro for typesetting a blue $A$. He also uses the |background| layer for
-drawing the triangle behind everything at the end.
-%
-\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{backgrounds,calc,intersections,through}}]
-\begin{tikzpicture}[thick,help lines/.style={thin,draw=black!50}]
- \def\A{\textcolor{input}{$A$}} \def\B{\textcolor{input}{$B$}}
- \def\C{\textcolor{output}{$C$}} \def\D{$D$}
- \def\E{$E$}
-
- \colorlet{input}{blue!80!black} \colorlet{output}{red!70!black}
- \colorlet{triangle}{orange}
-
- \coordinate [label=left:\A] (A) at ($ (0,0) + .1*(rand,rand) $);
- \coordinate [label=right:\B] (B) at ($ (1.25,0.25) + .1*(rand,rand) $);
-
- \draw [input] (A) -- (B);
-
- \node [name path=D,help lines,draw,label=left:\D] (D) at (A) [circle through=(B)] {};
- \node [name path=E,help lines,draw,label=right:\E] (E) at (B) [circle through=(A)] {};
-
- \path [name intersections={of=D and E,by={[label=above:\C]C}}];
-
- \draw [output] (A) -- (C) -- (B);
-
- \foreach \point in {A,B,C}
- \fill [black,opacity=.5] (\point) circle (2pt);
-
- \begin{pgfonlayer}{background}
- \fill[triangle!80] (A) -- (C) -- (B) -- cycle;
- \end{pgfonlayer}
-
- \node [below right, text width=10cm,align=justify] at (4,3) {
- \small\textbf{Proposition I}\par
- \emph{To construct an \textcolor{triangle}{equilateral triangle}
- on a given \textcolor{input}{finite straight line}.}
- \par\vskip1em
- Let \A\B\ be the given \textcolor{input}{finite straight line}. \dots
- };
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Book I, Proposition II}
-
-The second proposition in the Elements is the following:
-
-\bigskip\noindent
-\begin{tikzpicture}[thick,help lines/.style={thin,draw=black!50}]
- \pgfmathsetseed{1}
- \def\A{\textcolor{orange}{$A$}} \def\B{\textcolor{input}{$B$}}
- \def\C{\textcolor{input}{$C$}} \def\D{$D$}
- \def\E{$E$} \def\F{$F$}
- \def\G{$G$} \def\H{$H$}
- \def\K{$K$} \def\L{\textcolor{output}{$L$}}
-
- \colorlet{input}{blue!80!black} \colorlet{output}{red!70!black}
-
- \coordinate [label=left:\A] (A) at ($ (0,0) + .1*(rand,rand) $);
- \coordinate [label=right:\B] (B) at ($ (1,0.2) + .1*(rand,rand) $);
- \coordinate [label=above:\C] (C) at ($ (1,2) + .1*(rand,rand) $);
-
- \draw [input] (B) -- (C);
- \draw [help lines] (A) -- (B);
-
- \coordinate [label=above:\D] (D) at ($ (A)!.5!(B) ! {sin(60)*2} ! 90:(B) $);
-
- \draw [help lines] (D) -- ($ (D)!3.75!(A) $) coordinate [label=-135:\E] (E);
- \draw [help lines] (D) -- ($ (D)!3.75!(B) $) coordinate [label=-45:\F] (F);
-
- \node (H) at (B) [name path=H,help lines,circle through=(C),draw,label=135:\H] {};
- \path [name path=B--F] (B) -- (F);
- \path [name intersections={of=H and B--F}]
- coordinate [label=right:\G] (G) at (intersection-1);
-
- \node (K) at (D) [name path=K,help lines,circle through=(G),draw,label=135:\K] {};
-
- \path [name path=A to E line] (A) -- (E);
- \path [name intersections={of=K and A to E line}]
- coordinate [label=below:\L] (L) at (intersection-1);
-
- \draw [output] (A) -- (L);
-
- \foreach \point in {A,B,C,D,G,L}
- \fill [black,opacity=.5] (\point) circle (2pt);
-
- \node [below right, text width=9cm,align=justify] at (4,4) {
- \small\textbf{Proposition II}\par
- \emph{To place a \textcolor{output}{straight line} equal to a
- given \textcolor{input}{straight line} with
- one end at a \textcolor{orange}{given point}.}
- \par\vskip1em
- Let \A\ be the given point, and \B\C\ the given
- \textcolor{input}{straight line}.
- It is required to place a \textcolor{output}{straight line} equal
- to the given \textcolor{input}{straight line} \B\C\ with one end
- at the point~\A.
-
- Join the straight line \A\B\ from the point \A\ to the point \B, and
- construct the equilateral triangle \D\A\B\ on it.
-
- Produce the straight lines \A\E\ and \B\F\ in a straight line with
- \D\A\ and \D\B. Describe the circle \C\G\H\ with center \B\ and
- radius \B\C, and again, describe the circle \G\K\L\ with center
- \D\ and radius \D\G.
-
- Since the point \B\ is the center of the circle \C\G\H, therefore
- \B\C\ equals \B\G. Again, since the point \D\ is the center of the
- circle \G\K\L, therefore \D\L\ equals \D\G. And in these \D\A\
- equals \D\B, therefore the remainder \A\L\ equals the remainder
- \B\G. But \B\C\ was also proved equal to \B\G, therefore each of
- the straight lines \A\L\ and \B\C\ equals \B\G. And things which
- equal the same thing also equal one another, therefore \A\L\ also
- equals \B\C.
-
- Therefore the \textcolor{output}{straight line} \A\L\ equal to the
- given \textcolor{input}{straight line} \B\C\ has been placed with
- one end at the \textcolor{orange}{given point}~\A.
- };
-\end{tikzpicture}
-
-
-\subsubsection{Using Partway Calculations for the Construction of \emph{D}}
-
-Euclid's construction starts with ``referencing'' Proposition~I for the
-construction of the point~$D$. Now, while we could simply repeat the
-construction, it seems a bit bothersome that one has to draw all these circles
-and do all these complicated constructions.
-
-For this reason, \tikzname\ supports some simplifications. First, there is a
-simple syntax for computing a point that is ``partway'' on a line from $p$
-to~$q$: You place these two points in a coordinate calculation -- remember,
-they start with |($| and end with |$)| -- and then combine them using
-|!|\meta{part}|!|. A \meta{part} of |0| refers to the \emph{first} coordinate,
-a \meta{part} of |1| refers to the second coordinate, and a value in between
-refers to a point on the line from $p$ to~$q$. Thus, the syntax is similar to
-the |xcolor| syntax for mixing colors.
-
-Here is the computation of the point in the middle of the line $AB$:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (1.25,0.25);
- \draw (A) -- (B);
- \node [fill=red,inner sep=1pt,label=below:$X$] (X) at ($ (A)!.5!(B) $) {};
-\end{tikzpicture}
-\end{codeexample}
-
-The computation of the point $D$ in Euclid's second proposition is a bit more
-complicated. It can be expressed as follows: Consider the line from $X$ to $B$.
-Suppose we rotate this line around $X$ for 90$^\circ$ and then stretch it by a
-factor of $\sin(60^\circ) \cdot 2$. This yields the desired point~$D$. We can
-do the stretching using the partway modifier above, for the rotation we need a
-new modifier: the rotation modifier. The idea is that the second coordinate in
-a partway computation can be prefixed by an angle. Then the partway point is
-computed normally (as if no angle were given), but the resulting point is
-rotated by this angle around the first point.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (1.25,0.25);
- \draw (A) -- (B);
- \node [fill=red,inner sep=1pt,label=below:$X$] (X) at ($ (A)!.5!(B) $) {};
- \node [fill=red,inner sep=1pt,label=above:$D$] (D) at
- ($ (X) ! {sin(60)*2} ! 90:(B) $) {};
- \draw (A) -- (D) -- (B);
-\end{tikzpicture}
-\end{codeexample}
-
-Finally, it is not necessary to explicitly name the point $X$. Rather, again
-like in the |xcolor| package, it is possible to chain partway modifiers:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc}}]
-\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (1.25,0.25);
- \draw (A) -- (B);
- \node [fill=red,inner sep=1pt,label=above:$D$] (D) at
- ($ (A) ! .5 ! (B) ! {sin(60)*2} ! 90:(B) $) {};
- \draw (A) -- (D) -- (B);
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{Intersecting a Line and a Circle}
-
-The next step in the construction is to draw a circle around $B$ through $C$,
-which is easy enough to do using the |circle through| option. Extending the
-lines $DA$ and $DB$ can be done using partway calculations, but this time with
-a part value outside the range $[0,1]$:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc,through}}]
-\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (0.75,0.25);
- \coordinate [label=above:$C$] (C) at (1,1.5);
- \draw (A) -- (B) -- (C);
- \coordinate [label=above:$D$] (D) at
- ($ (A) ! .5 ! (B) ! {sin(60)*2} ! 90:(B) $) {};
- \node (H) [label=135:$H$,draw,circle through=(C)] at (B) {};
- \draw (D) -- ($ (D) ! 3.5 ! (B) $) coordinate [label=below:$F$] (F);
- \draw (D) -- ($ (D) ! 2.5 ! (A) $) coordinate [label=below:$E$] (E);
-\end{tikzpicture}
-\end{codeexample}
-
-We now face the problem of finding the point $G$, which is the intersection of
-the line $BF$ and the circle $H$. One way is to use yet another variant of the
-partway computation: Normally, a partway computation has the form
-\meta{p}|!|\meta{factor}|!|\meta{q}, resulting in the point
-$(1-\meta{factor})\meta{p} + \meta{factor}\meta{q}$. Alternatively, instead of
-\meta{factor} you can also use a \meta{dimension} between the points. In this
-case, you get the point that is \meta{dimension} away from \meta{p} on the
-straight line to \meta{q}.
-
-We know that the point $G$ is on the way from $B$ to $F$. The distance is given
-by the radius of the circle~$H$. Here is the code for computing $H$:
-%
-{\ifpgfmanualexternalize\tikzexternaldisable\fi
-\begin{codeexample}[
- preamble={\usetikzlibrary{calc,through}},
- pre={\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (0.75,0.25);
- \coordinate [label=above:$C$] (C) at (1,1.5);
- \draw (A) -- (B) -- (C);
- \coordinate [label=above:$D$] (D) at
- ($ (A) ! .5 ! (B) ! {sin(60)*2} ! 90:(B) $) {};
- \draw (D) -- ($ (D) ! 3.5 ! (B) $) coordinate [label=below:$F$] (F);
- \draw (D) -- ($ (D) ! 2.5 ! (A) $) coordinate [label=below:$E$] (E);},
- post={\end{tikzpicture}},
-]
- \node (H) [label=135:$H$,draw,circle through=(C)] at (B) {};
- \path let \p1 = ($ (B) - (C) $) in
- coordinate [label=left:$G$] (G) at ($ (B) ! veclen(\x1,\y1) ! (F) $);
- \fill[red,opacity=.5] (G) circle (2pt);
-\end{codeexample}
-
-However, there is a simpler way: We can simply name the path of the circle and
-of the line in question and then use |name intersections| to compute the
-intersections.
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{calc,intersections,through}},
- pre={\begin{tikzpicture}
- \coordinate [label=left:$A$] (A) at (0,0);
- \coordinate [label=right:$B$] (B) at (0.75,0.25);
- \coordinate [label=above:$C$] (C) at (1,1.5);
- \draw (A) -- (B) -- (C);
- \coordinate [label=above:$D$] (D) at
- ($ (A) ! .5 ! (B) ! {sin(60)*2} ! 90:(B) $) {};
- \draw (D) -- ($ (D) ! 3.5 ! (B) $) coordinate [label=below:$F$] (F);
- \draw (D) -- ($ (D) ! 2.5 ! (A) $) coordinate [label=below:$E$] (E);},
- post={\end{tikzpicture}},
-]
- \node (H) [name path=H,label=135:$H$,draw,circle through=(C)] at (B) {};
- \path [name path=B--F] (B) -- (F);
- \path [name intersections={of=H and B--F,by={[label=left:$G$]G}}];
- \fill[red,opacity=.5] (G) circle (2pt);
-\end{codeexample}
-}%
-
-
-\subsubsection{The Complete Code}
-
-\begin{codeexample}[pre={\pgfmathsetseed{1}},preamble={\usetikzlibrary{calc,intersections,through}}]
-\begin{tikzpicture}[thick,help lines/.style={thin,draw=black!50}]
- \def\A{\textcolor{orange}{$A$}} \def\B{\textcolor{input}{$B$}}
- \def\C{\textcolor{input}{$C$}} \def\D{$D$}
- \def\E{$E$} \def\F{$F$}
- \def\G{$G$} \def\H{$H$}
- \def\K{$K$} \def\L{\textcolor{output}{$L$}}
-
- \colorlet{input}{blue!80!black} \colorlet{output}{red!70!black}
-
- \coordinate [label=left:\A] (A) at ($ (0,0) + .1*(rand,rand) $);
- \coordinate [label=right:\B] (B) at ($ (1,0.2) + .1*(rand,rand) $);
- \coordinate [label=above:\C] (C) at ($ (1,2) + .1*(rand,rand) $);
-
- \draw [input] (B) -- (C);
- \draw [help lines] (A) -- (B);
-
- \coordinate [label=above:\D] (D) at ($ (A)!.5!(B) ! {sin(60)*2} ! 90:(B) $);
-
- \draw [help lines] (D) -- ($ (D)!3.75!(A) $) coordinate [label=-135:\E] (E);
- \draw [help lines] (D) -- ($ (D)!3.75!(B) $) coordinate [label=-45:\F] (F);
-
- \node (H) at (B) [name path=H,help lines,circle through=(C),draw,label=135:\H] {};
- \path [name path=B--F] (B) -- (F);
- \path [name intersections={of=H and B--F,by={[label=right:\G]G}}];
-
- \node (K) at (D) [name path=K,help lines,circle through=(G),draw,label=135:\K] {};
- \path [name path=A--E] (A) -- (E);
- \path [name intersections={of=K and A--E,by={[label=below:\L]L}}];
-
- \draw [output] (A) -- (L);
-
- \foreach \point in {A,B,C,D,G,L}
- \fill [black,opacity=.5] (\point) circle (2pt);
-
- % \node ...
-\end{tikzpicture}
-\end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-chains.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-chains.tex
deleted file mode 100644
index 04b6f58433..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-chains.tex
+++ /dev/null
@@ -1,1067 +0,0 @@
-% 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{Tutorial: Diagrams as Simple Graphs}
-
-In this tutorial we have a look at how graphs and matrices can be used to
-typeset a diagram.
-
-Ilka, who just got tenure for her professorship on Old and Lovable Programming
-Languages, has recently dug up a technical report entitled \emph{The
-Programming Language Pascal} in the dusty cellar of the library of her
-university. Having been created in the good old times using pens and rules, it
-looks like this%
-\footnote{The shown diagram was not scanned, but rather typeset using
-\tikzname. The jittering lines were created using the |random steps|
-decoration.}:
-
-{
- \tikzset{
- nonterminal/.style={
- % The shape:
- rectangle,
- % The size:
- minimum size=6mm,
- % The border:
- very thick,
- draw=red!50!black!50, % 50% red and 50% black,
- % and that mixed with 50% white
- % The filling:
- top color=white, % a shading that is white at the top...
- bottom color=red!50!black!20, % and something else at the bottom
- % Font
- font=\itshape
- },
- terminal/.style={
- % The shape:
- rounded rectangle,
- minimum size=6mm,
- % The rest
- very thick,draw=black!50,
- top color=white,bottom color=black!20,
- font=\ttfamily},
- skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}}
- }
- \tikzset{terminal/.append style={text height=1.5ex,text depth=.25ex}}
- \tikzset{nonterminal/.append style={text height=1.5ex,text depth=.25ex}}
- \pgfmathsetseed{1}
-\medskip
-\noindent\begin{tikzpicture}[
- >=latex,thick,
- /pgf/every decoration/.style={/tikz/sharp corners},
- fuzzy/.style={decorate,decoration={random steps,segment length=0.5mm,amplitude=0.15pt}},
- minimum size=6mm,line join=round,line cap=round,
- terminal/.style={rectangle,draw,fill=white,fuzzy,rounded corners=3mm},
- nonterminal/.style={rectangle,draw,fill=white,fuzzy},
- node distance=4mm]
-
- \ttfamily
- \begin{scope}[start chain,
- every node/.style={on chain},
- terminal/.append style={join=by {->,shorten >=-1pt,fuzzy,decoration={post length=4pt}}},
- nonterminal/.append style={join=by {->,shorten >=-1pt,fuzzy,decoration={post length=4pt}}},
- support/.style={coordinate,join=by fuzzy}]
- \node [support] (start) {};
- \node [nonterminal] {unsigned integer};
- \node [support] (after ui) {};
- \node [terminal] {.};
- \node [support] (after dot) {};
- \node [terminal] {digit};
- \node [support] (after digit) {};
- \node [support] (skip) {};
- \node [support] (before E) {};
- \node [terminal] {E};
- \node [support] (after E) {};
- \node [support,xshift=5mm] (between) {};
- \node [support,xshift=5mm] (before last) {};
- \node [nonterminal] {unsigned integer};
- \node [support] (after last) {};
- \node [coordinate,join=by ->] (end) {};
- \end{scope}
- \node (plus) [terminal,above=of between] {+};
- \node (minus) [terminal,below=of between] {-};
-
- \begin{scope}[->,decoration={post length=4pt},rounded corners=2mm,every path/.style=fuzzy]
- \draw (after ui) -- +(0,.7) -| (skip);
- \draw (after digit) -- +(0,-.7) -| (after dot);
- \draw (before E) -- +(0,-1.2) -| (after last);
- \draw (after E) |- (plus);
- \draw (plus) -| (before last);
- \draw (after E) |- (minus);
- \draw (minus) -| (before last);
- \end{scope}
-\end{tikzpicture}
-\medskip
-
-For her next lecture, Ilka decides to redo this diagram, but this time perhaps
-a bit cleaner and perhaps also bit ``cooler''.
-
-\medskip
-\noindent\begin{tikzpicture}[point/.style={coordinate},>={Stealth[round]},thick,draw=black!50,
- tip/.style={->,shorten >=1pt},every join/.style={rounded corners},
- hv path/.style={to path={-| (\tikztotarget)}},
- vh path/.style={to path={|- (\tikztotarget)}}]
- \matrix[column sep=4mm] {
- % First row:
- & & & & & & & & & & & \node (plus) [terminal] {+};\\
- % Second row:
- \node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; &
- \node (p2) [point] {}; & \node (dot) [terminal] {.}; &
- \node (p3) [point] {}; & \node (digit) [terminal] {digit}; &
- \node (p4) [point] {}; & \node (p5) [point] {}; &
- \node (p6) [point] {}; & \node (e) [terminal] {E}; &
- \node (p7) [point] {}; & &
- \node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; &
- \node (p9) [point] {}; & \node (p10) [point] {};\\
- % Third row:
- & & & & & & & & & & & \node (minus)[terminal] {-};\\
- };
-
- { [start chain]
- \chainin (p1);
- \chainin (ui1) [join=by tip];
- \chainin (p2) [join];
- \chainin (dot) [join=by tip];
- \chainin (p3) [join];
- \chainin (digit) [join=by tip];
- \chainin (p4) [join];
- { [start branch=digit loop]
- \chainin (p3) [join=by {skip loop=-6mm,tip}];
- }
- \chainin (p5) [join,join=with p2 by {skip loop=6mm,tip}];
- \chainin (p6) [join];
- \chainin (e) [join=by tip];
- \chainin (p7) [join];
- { [start branch=plus]
- \chainin (plus) [join=by {vh path,tip}];
- \chainin (p8) [join=by {hv path,tip}];
- }
- { [start branch=minus]
- \chainin (minus) [join=by {vh path,tip}];
- \chainin (p8) [join=by {hv path,tip}];
- }
- \chainin (p8) [join];
- \chainin (ui2) [join=by tip];
- \chainin (p9) [join,join=with p6 by {skip loop=-11mm,tip}];
- \chainin (p10) [join=by tip];
- }
-\end{tikzpicture}
-}\medskip
-
-Having read the previous tutorials, Ilka knows already how to set up the
-environment for her diagram, namely using a |tikzpicture| environment. She
-wonders which libraries she will need. She decides that she will postpone the
-decision and add the necessary libraries as needed as she constructs the
-picture.
-
-
-\subsection{Styling the Nodes}
-
-The bulk of this tutorial will be about arranging the nodes and connecting them
-using chains, but let us start with setting up styles for the nodes.
-
-There are two kinds of nodes in the diagram, namely what theoreticians like to
-call \emph{terminals} and \emph{nonterminals}. For the terminals, Ilka decides
-to use a black color, which visually shows that ``nothing needs to be done
-about them''. The nonterminals, which still need to be ``processed'' further,
-get a bit of red mixed in.
-
-Ilka starts with the simpler nonterminals, as there are no rounded corners
-involved. Naturally, she sets up a style:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}[
- nonterminal/.style={
- % The shape:
- rectangle,
- % The size:
- minimum size=6mm,
- % The border:
- very thick,
- draw=red!50!black!50, % 50% red and 50% black,
- % and that mixed with 50% white
- % The filling:
- top color=white, % a shading that is white at the top...
- bottom color=red!50!black!20, % and something else at the bottom
- % Font
- font=\itshape
- }]
- \node [nonterminal] {unsigned integer};
-\end{tikzpicture}
-\end{codeexample}
-%
-Ilka is pretty proud of the use of the |minimum size| option: As the name
-suggests, this option ensures that the node is at least 6mm by 6mm, but it will
-expand in size as necessary to accommodate longer text. By giving this option
-to all nodes, they will all have the same height of 6mm.
-
-Styling the terminals is a bit more difficult because of the round corners.
-Ilka has several options how she can achieve them. One way is to use the
-|rounded corners| option. It gets a dimension as parameter and causes all
-corners to be replaced by little arcs with the given dimension as radius. By
-setting the radius to 3mm, she will get exactly what she needs: circles, when
-the shapes are, indeed, exactly 6mm by 6mm and otherwise half circles on the
-sides:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}[node distance=5mm,
- terminal/.style={
- % The shape:
- rectangle,minimum size=6mm,rounded corners=3mm,
- % The rest
- very thick,draw=black!50,
- top color=white,bottom color=black!20,
- font=\ttfamily}]
- \node (dot) [terminal] {.};
- \node (digit) [terminal,right=of dot] {digit};
- \node (E) [terminal,right=of digit] {E};
-\end{tikzpicture}
-\end{codeexample}
-
-Another possibility is to use a shape that is specially made for typesetting
-rectangles with arcs on the sides (she has to use the |shapes.misc| library to
-use it). This shape gives Ilka much more control over the appearance. For
-instance, she could have an arc only on the left side, but she will not need
-this.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
-\begin{tikzpicture}[node distance=5mm,
- terminal/.style={
- % The shape:
- rounded rectangle,
- minimum size=6mm,
- % The rest
- very thick,draw=black!50,
- top color=white,bottom color=black!20,
- font=\ttfamily}]
- \node (dot) [terminal] {.};
- \node (digit) [terminal,right=of dot] {digit};
- \node (E) [terminal,right=of digit] {E};
-\end{tikzpicture}
-\end{codeexample}
-%
-At this point, she notices a problem. The baseline of the text in the nodes is
-not aligned:
-%
-\begin{codeexample}[setup code,hidden]
-\tikzset{
- terminal/.style={
- % The shape:
- rounded rectangle,
- minimum size=6mm,
- % The rest
- very thick,draw=black!50,
- top color=white,bottom color=black!20,
- font=\ttfamily},
-}
-\end{codeexample}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc,positioning,shapes.misc}}]
-\begin{tikzpicture}[node distance=5mm]
- \node (dot) [terminal] {.};
- \node (digit) [terminal,right=of dot] {digit};
- \node (E) [terminal,right=of digit] {E};
-
- \draw [help lines] let \p1 = (dot.base),
- \p2 = (digit.base),
- \p3 = (E.base)
- in (-.5,\y1) -- (3.5,\y1)
- (-.5,\y2) -- (3.5,\y2)
- (-.5,\y3) -- (3.5,\y3);
-\end{tikzpicture}
-\end{codeexample}
-%
-\noindent (Ilka has moved the style definition to the preamble by saying
-|\tikzset{terminal/.style=...}|, so that she can use it in all pictures.)
-
-For the |digit| and the |E| the difference in the baselines is almost
-imperceptible, but for the dot the problem is quite severe: It looks more like
-a multiplication dot than a period.
-
-Ilka toys with the idea of using the |base right=of...| option rather than
-|right=of...| to align the nodes in such a way that the baselines are all on
-the same line (the |base right| option places a node right of something so that
-the baseline is right of the baseline of the other object). However, this does
-not have the desired effect:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
-\begin{tikzpicture}[node distance=5mm]
- \node (dot) [terminal] {.};
- \node (digit) [terminal,base right=of dot] {digit};
- \node (E) [terminal,base right=of digit] {E};
-\end{tikzpicture}
-\end{codeexample}
-%
-The nodes suddenly ``dance around''! There is no hope of changing the position
-of text inside a node using anchors. Instead, Ilka must use a trick: The
-problem of mismatching baselines is caused by the fact that |.| and |digit| and
-|E| all have different heights and depth. If they all had the same, they would
-all be positioned vertically in the same manner. So, all Ilka needs to do is to
-use the |text height| and |text depth| options to explicitly specify a height
-and depth for the nodes.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
-\begin{tikzpicture}[node distance=5mm,
- text height=1.5ex,text depth=.25ex]
- \node (dot) [terminal] {.};
- \node (digit) [terminal,right=of dot] {digit};
- \node (E) [terminal,right=of digit] {E};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Aligning the Nodes Using Positioning Options}
-
-Ilka now has the ``styling'' of the nodes ready. The next problem is to place
-them in the right places. There are several ways to do this. The most
-straightforward is to simply explicitly place the nodes at certain coordinates
-``calculated by hand''. For very simple graphics this is perfectly alright, but
-it has several disadvantages:
-%
-\begin{enumerate}
- \item For more difficult graphics, the calculation may become
- complicated.
- \item Changing the text of the nodes may make it necessary to recalculate
- the coordinates.
- \item The source code of the graphic is not very clear since the
- relationships between the positions of the nodes are not made
- explicit.
-\end{enumerate}
-
-For these reasons, Ilka decides to try out different ways of arranging the
-nodes on the page.
-
-The first method is the use of \emph{positioning options}. To use them, you
-need to load the |positioning| library. This gives you access to advanced
-implementations of options like |above| or |left|, since you can now say
-|above=of some node| in order to place a node above of |some node|, with the
-borders separated by |node distance|.
-
-Ilka can use this to draw the place the nodes in a long row:
-%
-\begin{codeexample}[setup code,hidden]
-\tikzset{
- nonterminal/.style={
- % The shape:
- rectangle,
- % The size:
- minimum size=6mm,
- % The border:
- very thick,
- draw=red!50!black!50, % 50% red and 50% black,
- % and that mixed with 50% white
- % The filling:
- top color=white, % a shading that is white at the top...
- bottom color=red!50!black!20, % and something else at the bottom
- % Font
- font=\itshape,
- },
-}
-\tikzset{
- terminal/.append style={text height=1.5ex,text depth=.25ex},
- nonterminal/.append style={text height=1.5ex,text depth=.25ex},
-}
-\end{codeexample}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
-\begin{tikzpicture}[node distance=5mm and 5mm]
- \node (ui1) [nonterminal] {unsigned integer};
- \node (dot) [terminal,right=of ui1] {.};
- \node (digit) [terminal,right=of dot] {digit};
- \node (E) [terminal,right=of digit] {E};
- \node (plus) [terminal,above right=of E] {+};
- \node (minus) [terminal,below right=of E] {-};
- \node (ui2) [nonterminal,below right=of plus] {unsigned integer};
-\end{tikzpicture}
-\end{codeexample}
-
-For the plus and minus nodes, Ilka is a bit startled by their placements.
-Shouldn't they be more to the right? The reason they are placed in that manner
-is the following: The |north east| anchor of the |E| node lies at the ``upper
-start of the right arc'', which, a bit unfortunately in this case, happens to
-be the top of the node. Likewise, the |south west| anchor of the |+| node is
-actually at its bottom and, indeed, the horizontal and vertical distances
-between the top of the |E| node and the bottom of the |+| node are both 5mm.
-
-There are several ways of fixing this problem. The easiest way is to simply add
-a little bit of horizontal shift by hand:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
-\begin{tikzpicture}[node distance=5mm and 5mm]
- \node (E) [terminal] {E};
- \node (plus) [terminal,above right=of E,xshift=5mm] {+};
- \node (minus) [terminal,below right=of E,xshift=5mm] {-};
- \node (ui2) [nonterminal,below right=of plus,xshift=5mm] {unsigned integer};
-\end{tikzpicture}
-\end{codeexample}
-
-A second way is to revert back to the idea of using a normal rectangle for the
-terminals, but with rounded corners. Since corner rounding does not affect
-anchors, she gets the following result:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning,shapes.misc}}]
-\begin{tikzpicture}[node distance=5mm and 5mm,terminal/.append style={rectangle,rounded corners=3mm}]
- \node (E) [terminal] {E};
- \node (plus) [terminal,above right=of E] {+};
- \node (minus) [terminal,below right=of E] {-};
- \node (ui2) [nonterminal,below right=of plus] {unsigned integer};
-\end{tikzpicture}
-\end{codeexample}
-%
-A third way is to use matrices, which we will do later.
-
-Now that the nodes have been placed, Ilka needs to add connections. Here, some
-connections are more difficult than others. Consider for instance the
-``repeat'' line around the |digit|. One way of describing this line is to say
-``it starts a little to the right of |digit| than goes down and then goes to
-the left and finally ends at a point a little to the left of |digit|''. Ilka
-can put this into code as follows:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc,positioning,shapes.misc}}]
-\begin{tikzpicture}[node distance=5mm and 5mm]
- \node (dot) [terminal] {.};
- \node (digit) [terminal,right=of dot] {digit};
- \node (E) [terminal,right=of digit] {E};
-
- \path (dot) edge[->] (digit) % simple edges
- (digit) edge[->] (E);
-
- \draw [->]
- % start right of digit.east, that is, at the point that is the
- % linear combination of digit.east and the vector (2mm,0pt). We
- % use the ($ ... $) notation for computing linear combinations
- ($ (digit.east) + (2mm,0) $)
- % Now go down
- -- ++(0,-.5)
- % And back to the left of digit.west
- -| ($ (digit.west) - (2mm,0) $);
-\end{tikzpicture}
-\end{codeexample}
-
-Since Ilka needs this ``go up/down then horizontally and then up/down to a
-target'' several times, it seems sensible to define a special \emph{to-path}
-for this. Whenever the |edge| command is used, it simply adds the current value
-of |to path| to the path. So, Ilka can set up a style that contains the correct
-path:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc,positioning,shapes.misc}}]
-\begin{tikzpicture}[node distance=5mm and 5mm,
- skip loop/.style={to path={-- ++(0,-.5) -| (\tikztotarget)}}]
- \node (dot) [terminal] {.};
- \node (digit) [terminal,right=of dot] {digit};
- \node (E) [terminal,right=of digit] {E};
-
- \path (dot) edge[->] (digit) % simple edges
- (digit) edge[->] (E)
- ($ (digit.east) + (2mm,0) $)
- edge[->,skip loop] ($ (digit.west) - (2mm,0) $);
-\end{tikzpicture}
-\end{codeexample}
-
-Ilka can even go a step further and make her |skip loop| style parameterized.
-For this, the skip loop's vertical offset is passed as parameter |#1|. Also, in
-the following code Ilka specifies the start and targets differently, namely as
-the positions that are ``in the middle between the nodes''.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{calc,positioning,shapes.misc}}]
-\begin{tikzpicture}[node distance=5mm and 5mm,
- skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}}]
- \node (dot) [terminal] {.};
- \node (digit) [terminal,right=of dot] {digit};
- \node (E) [terminal,right=of digit] {E};
-
- \path (dot) edge[->] (digit) % simple edges
- (digit) edge[->] (E)
- ($ (digit.east)!.5!(E.west) $)
- edge[->,skip loop=-5mm] ($ (digit.west)!.5!(dot.east) $);
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Aligning the Nodes Using Matrices}
-
-Ilka is still bothered a bit by the placement of the plus and minus nodes.
-Somehow, having to add an explicit |xshift| seems too much like cheating.
-
-A perhaps better way of positioning the nodes is to use a \emph{matrix}. In
-\tikzname\ matrices can be used to align quite arbitrary graphical objects in
-rows and columns. The syntax is very similar to the use of arrays and tables in
-\TeX\ (indeed, internally \TeX\ tables are used, but a lot of stuff is going on
-additionally).
-
-In Ilka's graphic, there will be three rows: One row containing only the plus
-node, one row containing the main nodes and one row containing only the minus
-node.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\begin{tikzpicture}
- \matrix[row sep=1mm,column sep=5mm] {
- % First row:
- & & & & \node [terminal] {+}; & \\
- % Second row:
- \node [nonterminal] {unsigned integer}; &
- \node [terminal] {.}; &
- \node [terminal] {digit}; &
- \node [terminal] {E}; &
- &
- \node [nonterminal] {unsigned integer}; \\
- % Third row:
- & & & & \node [terminal] {-}; & \\
- };
-\end{tikzpicture}
-\end{codeexample}
-%
-That was easy! By toying around with the row and columns separations, Ilka can
-achieve all sorts of pleasing arrangements of the nodes.
-
-Ilka now faces the same connecting problem as before. This time, she has an
-idea: She adds small nodes (they will be turned into coordinates later on and
-be invisible) at all the places where she would like connections to start and
-end.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{shapes.misc}}]
-\begin{tikzpicture}[point/.style={circle,inner sep=0pt,minimum size=2pt,fill=red},
- skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}}]
- \matrix[row sep=1mm,column sep=2mm] {
- % First row:
- & & & & & & & & & & & \node (plus) [terminal] {+};\\
- % Second row:
- \node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; &
- \node (p2) [point] {}; & \node (dot) [terminal] {.}; &
- \node (p3) [point] {}; & \node (digit) [terminal] {digit}; &
- \node (p4) [point] {}; & \node (p5) [point] {}; &
- \node (p6) [point] {}; & \node (e) [terminal] {E}; &
- \node (p7) [point] {}; & &
- \node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; &
- \node (p9) [point] {}; & \node (p10) [point] {};\\
- % Third row:
- & & & & & & & & & & & \node (minus)[terminal] {-};\\
- };
-
- \path (p4) edge [->,skip loop=-5mm] (p3)
- (p2) edge [->,skip loop=5mm] (p6);
-\end{tikzpicture}
-\end{codeexample}
-%
-Now, it's only a small step to add all the missing edges.
-
-
-\subsection{The Diagram as a Graph}
-
-Matrices allow Ilka to align the nodes nicely, but the connections are not
-quite perfect. The problem is that the code does not really reflect the paths
-that underlie the diagram. For this, it seems natural enough to Ilka to use the
-|graphs| library since, after all, connecting nodes by edges is exactly what
-happens in a graph. The |graphs| library can both be used to connect nodes that
-have already been created, but it can also be used to create nodes ``on the
-fly'' and these processes can also be mixed.
-
-
-\subsubsection{Connecting Already Positioned Nodes}
-
-Ilka has already a fine method for positioning her nodes (using a |matrix|), so
-all that she needs is an easy way of specifying the edges. For this, she uses
-the |\graph| command (which is actually just a shorthand for |\path graph|). It
-allows her to write down edges between them in a simple way (the macro
-|\matrixcontent| contains exactly the matrix content from the previous example;
-no need to repeat it here):
-%
-\begin{codeexample}[setup code,hidden]
-\def\matrixcontent{
- % First row:
- \& \& \& \& \& \& \& \& \& \& \& \node (plus) [terminal] {+};\\
- % Second row:
- \node (p1) [point] {}; \& \node (ui1) [nonterminal] {unsigned integer}; \&
- \node (p2) [point] {}; \& \node (dot) [terminal] {.}; \&
- \node (p3) [point] {}; \& \node (digit) [terminal] {digit}; \&
- \node (p4) [point] {}; \& \node (p5) [point] {}; \&
- \node (p6) [point] {}; \& \node (e) [terminal] {E}; \&
- \node (p7) [point] {}; \& \&
- \node (p8) [point] {}; \& \node (ui2) [nonterminal] {unsigned integer}; \&
- \node (p9) [point] {}; \& \node (p10) [point] {};\\
- % Third row:
- \& \& \& \& \& \& \& \& \& \& \& \node (minus)[terminal] {-};\\
-}
-\end{codeexample}
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{graphs,shapes.misc}},
- pre={\tikzset{ampersand replacement=\&,point/.style={coordinate}}},
-]
-\begin{tikzpicture}[skip loop/.style={to path={-- ++(0,#1) -| (\tikztotarget)}},
- hv path/.style={to path={-| (\tikztotarget)}},
- vh path/.style={to path={|- (\tikztotarget)}}]
- \matrix[row sep=1mm,column sep=2mm] { \matrixcontent };
-
- \graph {
- (p1) -> (ui1) -- (p2) -> (dot) -- (p3) -> (digit) -- (p4)
- -- (p5) -- (p6) -> (e) -- (p7) -- (p8) -> (ui2) -- (p9) -> (p10);
- (p4) ->[skip loop=-5mm] (p3);
- (p2) ->[skip loop=5mm] (p5);
- (p6) ->[skip loop=-11mm] (p9);
- (p7) ->[vh path] (plus) -> [hv path] (p8);
- (p7) ->[vh path] (minus) -> [hv path] (p8);
- };
-\end{tikzpicture}
-\end{codeexample}
-
-This is already pretty near to the desired result, just a few ``finishing
-touches'' are needed to style the edges more nicely.
-
-However, Ilka does not have the feeling that the |graph| command is all that
-hot in the example. It certainly does cut down on the number of characters she
-has to write, but the overall graph structure is not that much clear -- it is
-still mainly a list of paths through the graph. It would be nice to specify
-that, say, there the path from |(p7)| sort of splits to |(plus)| and |(minus)|
-and then merges once more at |(p8)|. Also, all these parentheses are bit hard
-to type.
-
-It turns out that edges from a node to a whole group of nodes are quite easy to
-specify, as shown in the next example. Additionally, by using the
-|use existing nodes| option, Ilka can also leave out all the parentheses
-(again, some options have been moved outside to keep the examples shorter):
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{arrows.meta,graphs,shapes.misc}},
- pre={\tikzset{
- ampersand replacement=\&,
- point/.style={coordinate},
- skip loop/.style={to path={-- ++(0,##1) -| (\tikztotarget)}},
- hv path/.style={to path={-| (\tikztotarget)}},
- vh path/.style={to path={|- (\tikztotarget)}},
-}},
-]
-\begin{tikzpicture}[>={Stealth[round]},thick,black!50,text=black,
- every new ->/.style={shorten >=1pt},
- graphs/every graph/.style={edges=rounded corners}]
- \matrix[column sep=4mm] { \matrixcontent };
-
- \graph [use existing nodes] {
- p1 -> ui1 -- p2 -> dot -- p3 -> digit -- p4 -- p5 -- p6 -> e -- p7 -- p8 -> ui2 -- p9 -> p10;
- p4 ->[skip loop=-5mm] p3;
- p2 ->[skip loop=5mm] p5;
- p6 ->[skip loop=-11mm] p9;
- p7 ->[vh path] { plus, minus } -> [hv path] p8;
- };
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsubsection{Creating Nodes Using the Graph Command}
-
-Ilka has heard that the |graph| command is also supposed to make it easy to
-create nodes, not only to connect them. This is, indeed, correct: When the
-|use existing nodes| option is not used and when a node name is not surrounded
-by parentheses, then \tikzname\ will actually create a node whose name and text
-is the node name:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs}}]
-\tikz \graph [grow right=2cm] { unsigned integer -> d -> digit -> E };
-\end{codeexample}
-%
-Not quite perfect, but we are getting somewhere. First, let us change the
-positioning algorithm by saying |grow right sep|, which causes new nodes to be
-placed to the right of the previous nodes with a certain fixed separation
-(|1em| by default). Second, we add some options to make the node ``look nice''.
-Third, note the funny |d| node above: Ilka tried writing just |.| there first,
-but got some error messages. The reason is that a node cannot be called |.| in
-\tikzname, so she had to choose a different name -- which is not good, since
-she wants a dot to be shown! The trick is to put the dot in quotation marks,
-this allows you to use ``quite arbitrary text'' as a node name:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,shapes.misc}}]
-\tikz \graph [grow right sep] {
- unsigned integer[nonterminal] -> "."[terminal] -> digit[terminal] -> E[terminal]
-};
-\end{codeexample}
-%
-Now comes the fork to the plus and minus signs. Here, Ilka can use the grouping
-mechanism of the |graph| command to create a split:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{graphs,shapes.misc}}]
-\tikz \graph [grow right sep] {
- unsigned integer [nonterminal] ->
- "." [terminal] ->
- digit [terminal] ->
- E [terminal] ->
- {
- "+" [terminal],
- "" [coordinate],
- "-" [terminal]
- } ->
- ui2/unsigned integer [nonterminal]
-};
-\end{codeexample}
-%
-Let us see, what is happening here. We want two |unsigned integer| nodes, but
-if we just were to use this text twice, then \tikzname\ would have noticed that
-the same name was used already in the current graph and, being smart (actually
-too smart in this case), would have created an edge back to the already-created
-node. Thus, a fresh name is needed here. However, Ilka also cannot just write
-|unsigned integer2|, because she wants the original text to be shown, after
-all! The trick is to use a slash inside the node name: In order to ``render''
-the node, the text following the slash is used instead of the node name, which
-is the text before the slash. Alternatively, the |as| option can be used, which
-also allows you to specify how a node should be rendered.
-
-It turns out that Ilka does not need to invent a name like |ui2| for a node
-that she will not reference again anyway. In this case, she can just leave out
-the name (write nothing before |/|), which always stands for a ``fresh,
-anonymous'' node name.
-
-Next, Ilka needs to add some coordinates in between of some nodes where the
-back-loops should got and she needs to shift the nodes a bit:
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{arrows.meta,graphs,shapes.misc}},
- pre={\tikzset{
- skip loop/.style={to path={-- ++(0,##1) -| (\tikztotarget)}},
- hv path/.style={to path={-| (\tikztotarget)}},
- vh path/.style={to path={|- (\tikztotarget)}},
-}},
-]
-\begin{tikzpicture}[>={Stealth[round]}, thick, black!50, text=black,
- every new ->/.style={shorten >=1pt},
- graphs/every graph/.style={edges=rounded corners}]
- \graph [grow right sep, branch down=7mm] {
- / [coordinate] ->
- unsigned integer [nonterminal] --
- p1 [coordinate] ->
- "." [terminal] --
- p2 [coordinate] ->
- digit [terminal] --
- p3 [coordinate] --
- p4 [coordinate] --
- p5 [coordinate] ->
- E [terminal] --
- q1 [coordinate] ->[vh path]
- { [nodes={yshift=7mm}]
- "+" [terminal],
- q2/ [coordinate],
- "-" [terminal]
- } -> [hv path]
- q3 [coordinate] --
- /unsigned integer [nonterminal] --
- p6 [coordinate] ->
- / [coordinate];
-
- p1 ->[skip loop=5mm] p4;
- p3 ->[skip loop=-5mm] p2;
- p5 ->[skip loop=-11mm] p6;
- };
-\end{tikzpicture}
-\end{codeexample}
-
-All that remains to be done is to somehow get rid of the strange curves between
-the |E| and the unsigned integer. They are caused by \tikzname's attempt at
-creating an edge that first goes vertical and then horizontal but is actually
-just horizontal. Additionally, the edge should not really be pointed; but it
-seems difficult to get rid of this since the \emph{other} edges from |q1|,
-namely to |plus| and |minus| should be pointed.
-
-It turns out that there is a nice way of solving this problem: You can specify
-that a graph is |simple|. This means that there can be at most one edge between
-any two nodes. Now, if you specify an edge twice, the options of the second
-specification ``win''. Thus, by adding two more lines that ``correct'' these
-edges, we get the final diagram with its complete code:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,graphs,shapes.misc}}]
-\tikz [>={Stealth[round]}, black!50, text=black, thick,
- every new ->/.style = {shorten >=1pt},
- graphs/every graph/.style = {edges=rounded corners},
- skip loop/.style = {to path={-- ++(0,#1) -| (\tikztotarget)}},
- hv path/.style = {to path={-| (\tikztotarget)}},
- vh path/.style = {to path={|- (\tikztotarget)}},
- nonterminal/.style = {
- rectangle, minimum size=6mm, very thick, draw=red!50!black!50, top color=white,
- bottom color=red!50!black!20, font=\itshape, text height=1.5ex,text depth=.25ex},
- terminal/.style = {
- rounded rectangle, minimum size=6mm, very thick, draw=black!50, top color=white,
- bottom color=black!20, font=\ttfamily, text height=1.5ex, text depth=.25ex},
- shape = coordinate
- ]
- \graph [grow right sep, branch down=7mm, simple] {
- / -> unsigned integer[nonterminal] -- p1 -> "." [terminal] -- p2 -> digit[terminal] --
- p3 -- p4 -- p5 -> E[terminal] -- q1 ->[vh path]
- {[nodes={yshift=7mm}]
- "+"[terminal], q2, "-"[terminal]
- } -> [hv path]
- q3 -- /unsigned integer [nonterminal] -- p6 -> /;
-
- p1 ->[skip loop=5mm] p4;
- p3 ->[skip loop=-5mm] p2;
- p5 ->[skip loop=-11mm] p6;
-
- q1 -- q2 -- q3; % make these edges plain
- };
-\end{codeexample}
-
-
-%% TODOsp: a commented subsection
-% \subsection{Using Chains}
-%
-% Matrices allow Ilka to align the nodes nicely, but the connections are
-% not quite perfect. The problem is that the code does not really
-% reflect the paths that underlie the diagram.
-%
-%
-% For this reason, Ilka decides to try out \emph{chains} by including
-% the |chain| library. Basically, a chain is just a sequence of
-% (usually) connected nodes. The nodes can already have been constructed
-% or they can be constructed as the chain is constructed (or these
-% processes can be mixed).
-%
-% \subsubsection{Creating a Simple Chain}
-%
-%
-% Ilka starts with creating a chain from scratch. For this, she starts a
-% chain using the |start chain| option in a scope. Then, inside the
-% scope, she uses the |on chain| option on nodes to add them to the
-% chain.
-% \begin{codeexample}[]
-% \begin{tikzpicture}[start chain,node distance=5mm]
-% \node [on chain,nonterminal] {unsigned integer};
-% \node [on chain,terminal] {.};
-% \node [on chain,terminal] {digit};
-% \node [on chain,terminal] {E};
-% \node [on chain,nonterminal] {unsigned integer};
-% \end{tikzpicture}
-% \end{codeexample}
-% (Ilka will add the plus and minus nodes later.)
-%
-% As can be seen, the nodes of a chain are placed in a row. This can be
-% changed, for instance by saying |start chain=going below| we get a
-% chain where each node is below the previous one.
-%
-% The next step is to \emph{join} the nodes of the chain. For this, we
-% add the |join| option to each node. This joins the node with the
-% previous node (for the first node nothing happens).
-% \begin{codeexample}[]
-% \begin{tikzpicture}[start chain,node distance=5mm]
-% \node [on chain,join,nonterminal] {unsigned integer};
-% \node [on chain,join,terminal] {.};
-% \node [on chain,join,terminal] {digit};
-% \node [on chain,join,terminal] {E};
-% \node [on chain,join,nonterminal] {unsigned integer};
-% \end{tikzpicture}
-% \end{codeexample}
-% In order to get a arrow tip, we redefine the |every join| style. Also,
-% we move the |join| and |on chain| options to the |every node|
-% style so that we do not have to repeat them so often.
-% \begin{codeexample}[]
-% \begin{tikzpicture}[start chain,node distance=5mm, every node/.style={on chain,join}, every join/.style={->}]
-% \node [nonterminal] {unsigned integer};
-% \node [terminal] {.};
-% \node [terminal] {digit};
-% \node [terminal] {E};
-% \node [nonterminal] {unsigned integer};
-% \end{tikzpicture}
-% \end{codeexample}
-%
-%
-% \subsubsection{Branching and Joining a Chain}
-%
-% It is now time to add the plus and minus signs. They obviously
-% \emph{branch off} the main chain. For this reason, we start a branch
-% for them using the |start branch| option.
-% \begin{codeexample}[]
-% \begin{tikzpicture}[start chain,node distance=5mm, every node/.style={on chain,join}, every join/.style={->}]
-% \node [nonterminal] {unsigned integer};
-% \node [terminal] {.};
-% \node [terminal] {digit};
-% \node [terminal] {E};
-% \begin{scope}[start branch=plus]
-% \node (plus) [terminal,on chain=going above right] {+};
-% \end{scope}
-% \begin{scope}[start branch=minus]
-% \node (minus) [terminal,on chain=going below right] {-};
-% \end{scope}
-% \node [nonterminal,join=with plus,join=with minus] {unsigned integer};
-% \end{tikzpicture}
-% \end{codeexample}
-%
-% Let us see, what is going on here. First, the |start branch| begins a
-% branch, starting with the node last created on the current chain,
-% which is the |E| node in our case. This is implicitly also the first
-% node on this branch. A branch is nothing different from a chain, which
-% is why the plus node is put on this branch using the |on chain|
-% option. However, this time we specify the placement of the node
-% explicitly using |going |\meta{direction}. This causes the plus sign
-% to be placed above and right of the |E| node. It is automatically
-% joined to its predecessor on the branch by the implicit |join|
-% option.
-%
-% When the first branch ends, only the plus node has been added and the
-% current chain is the original chain once more and we are back to the
-% |E| node. Now we start a new branch for the minus node. After this
-% branch, the current chain ends at |E| node once more.
-%
-% Finally, the rightmost unsigned integer is added to the (main) chain,
-% which is why it is joined correctly with the |E| node. The two
-% additional |join| options get a special |with| parameter. This allows
-% you to join a node with a node other than the predecessor on the
-% chain. The |with| should be followed by the name of a node.
-%
-% Since Ilka will need scopes more often in the following, she includes
-% the |scopes| library. This allows her to replace |\begin{scope}|
-% simply by an opening brace and |\end{scope}| by the corresponding
-% closing brace. Also, in the following example we reference
-% the nodes |plus| and |minus| using
-% their automatic name: The $i$th node on a chain is called
-% |chain-|\meta{i}. For a branch \meta{branch}, the $i$th node is called
-% |chain/|\meta{branch}|-|\meta{i}. The \meta{i} can be replaced by
-% |begin| and |end| to reference the first and (currently) last node on
-% the chain.
-%
-% \begin{codeexample}[]
-% \begin{tikzpicture}[start chain,node distance=5mm, every on chain/.style={join}, every join/.style={->}]
-% \node [on chain,nonterminal] {unsigned integer};
-% \node [on chain,terminal] {.};
-% \node [on chain,terminal] {digit};
-% \node [on chain,terminal] {E};
-% { [start branch=plus]
-% \node (plus) [terminal,on chain=going above right] {+};
-% }
-% { [start branch=minus]
-% \node (minus) [terminal,on chain=going below right] {-};
-% }
-% \node [nonterminal,on chain,join=with chain/plus-end,join=with chain/minus-end] {unsigned integer};
-% \end{tikzpicture}
-% \end{codeexample}
-%
-%
-% The next step is to add intermediate coordinate nodes in the same
-% manner as Ilka did for the matrix. For them, we change the |join|
-% style slightly, namely for these nodes we do not want an arrow
-% tip. This can be achieved either by (locally) changing the
-% |every join| style or, which is what is done in the below example, by
-% giving the desired style using |join=by ...|, where |...| is the style
-% to be used for the join.
-%
-% \begin{codeexample}[]
-% \begin{tikzpicture}[start chain,node distance=5mm and 2mm,
-% every node/.style={on chain},
-% nonterminal/.append style={join=by ->},
-% terminal/.append style={join=by ->},
-% point/.style={join=by -,circle,fill=red,minimum size=2pt,inner sep=0pt}]
-% \node [point] {}; \node [nonterminal] {unsigned integer};
-% \node [point] {}; \node [terminal] {.};
-% \node [point] {}; \node [terminal] {digit};
-% \node [point] {}; \node [point] {};
-% \node [point] {}; \node [terminal] {E};
-% \node [point] {};
-% { [node distance=5mm and 1cm] % local change in horizontal distance
-% { [start branch=plus]
-% \node (plus) [terminal,on chain=going above right] {+};
-% }
-% { [start branch=minus]
-% \node (minus) [terminal,on chain=going below right] {-};
-% }
-% \node [point,below right=of plus,join=with chain/plus-end by ->,join=with chain/minus-end by ->] {};
-% }
-% \node [nonterminal] {unsigned integer};
-% \node [point] {};
-% \end{tikzpicture}
-% \end{codeexample}
-%
-%
-% \subsubsection{Chaining Together Already Positioned Nodes}
-%
-% The final step is to add the missing arrows. We can also use branches
-% for them (even though we do not have to, but it is good practice and
-% they exhibit the structure of the diagram in the code).
-%
-% Let us start with the repeat loop around the |digit|. This can be
-% thought of as a branch that starts at the point after the digit and
-% that ends at the point before the digit. However, we have already
-% constructed the point before the digit! In such cases, it is possible
-% to ``chain in'' an already positioned node, using the |\chainin|
-% command. This command must be followed by a coordinate that contains a
-% node name and optionally some options. The effect is that the named
-% node is made part of the current chain.
-%
-% \begin{codeexample}[pre={\tikzset{node distance=5mm and 2mm,
-% every node/.style={on chain},
-% terminal/.append style={join=by ->},
-% point/.style={join=by -,circle,fill=red,minimum size=2pt,inner sep=0pt}}}]
-% \begin{tikzpicture}[start chain] % plus some styles that are not shown
-% \node [point] {};
-% \node (before digit) [point] {};
-% \node [terminal] {digit};
-% \node [point] {};
-% { [start branch=digit loop]
-% \chainin (before digit) [join=by {->,skip loop=-5mm}];
-% }
-% \node [point] {};
-% \end{tikzpicture}
-% \end{codeexample}
-%
-%
-% \subsubsection{Combined Use of Matrices and Chains}
-%
-% Ilka's final idea is to combine matrices and chains in the following
-% manner: She will use a matrix to position the nodes. However, to show
-% the logical ``flow structure'' inside the diagram, she will create
-% chains and branches that show what is going on.
-%
-% Ilka starts with the matrix we had earlier, only with slightly adapted
-% styles. Then she writes down the main chain and its branches:
-%
-% \begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-% \begin{tikzpicture}[point/.style={coordinate},>={Stealth[round]},thick,draw=black!50,
-% tip/.style={->,shorten >=1pt},every join/.style={rounded corners},
-% hv path/.style={to path={-| (\tikztotarget)}},
-% vh path/.style={to path={|- (\tikztotarget)}}]
-% \matrix[column sep=4mm] {
-% % First row:
-% & & & & & & & & & & & \node (plus) [terminal] {+};\\
-% % Second row:
-% \node (p1) [point] {}; & \node (ui1) [nonterminal] {unsigned integer}; &
-% \node (p2) [point] {}; & \node (dot) [terminal] {.}; &
-% \node (p3) [point] {}; & \node (digit) [terminal] {digit}; &
-% \node (p4) [point] {}; & \node (p5) [point] {}; &
-% \node (p6) [point] {}; & \node (e) [terminal] {E}; &
-% \node (p7) [point] {}; & &
-% \node (p8) [point] {}; & \node (ui2) [nonterminal] {unsigned integer}; &
-% \node (p9) [point] {}; & \node (p10) [point] {};\\
-% % Third row:
-% & & & & & & & & & & & \node (minus)[terminal] {-};\\
-% };
-%
-% { [start chain]
-% \chainin (p1);
-% \chainin (ui1) [join=by tip];
-% \chainin (p2) [join];
-% \chainin (dot) [join=by tip];
-% \chainin (p3) [join];
-% \chainin (digit) [join=by tip];
-% \chainin (p4) [join];
-% { [start branch=digit loop]
-% \chainin (p3) [join=by {skip loop=-6mm,tip}];
-% }
-% \chainin (p5) [join,join=with p2 by {skip loop=6mm,tip}];
-% \chainin (p6) [join];
-% \chainin (e) [join=by tip];
-% \chainin (p7) [join];
-% { [start branch=plus]
-% \chainin (plus) [join=by {vh path,tip}];
-% \chainin (p8) [join=by {hv path,tip}];
-% }
-% { [start branch=minus]
-% \chainin (minus) [join=by {vh path,tip}];
-% \chainin (p8) [join=by {hv path,tip}];
-% }
-% \chainin (p8) [join];
-% \chainin (ui2) [join=by tip];
-% \chainin (p9) [join,join=with p6 by {skip loop=-11mm,tip}];
-% \chainin (p10) [join=by tip];
-% }
-% \end{tikzpicture}
-% \end{codeexample}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-map.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-map.tex
deleted file mode 100644
index 4c895031c6..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-map.tex
+++ /dev/null
@@ -1,1331 +0,0 @@
-% 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{Tutorial: A Lecture Map for Johannes}
-
-In this tutorial we explore the tree and mind map mechanisms of \tikzname.
-
-Johannes is quite excited: For the first time he will be teaching a course all
-by himself during the upcoming semester! Unfortunately, the course is not on
-his favorite subject, which is of course Theoretical Immunology, but on
-Complexity Theory, but as a young academic Johannes is not likely to complain
-too loudly. In order to help the students get a general overview of what is
-going to happen during the course as a whole, he intends to draw some kind of
-tree or graph containing the basic concepts. He got this idea from his old
-professor who seems to be using these ``lecture maps'' with some success.
-Independently of the success of these maps, Johannes thinks they look quite
-neat.
-
-
-\subsection{Problem Statement}
-
-Johannes wishes to create a lecture map with the following features:
-%
-\begin{enumerate}
- \item It should contain a tree or graph depicting the main concepts.
- \item It should somehow visualize the different lectures that will be
- taught. Note that the lectures are not necessarily the same as the
- concepts since the graph may contain more concepts than will be
- addressed in lectures and some concepts may be addressed during more
- than one lecture.
- \item The map should also contain a calendar showing when the individual
- lectures will be given.
- \item The aesthetical reasons, the whole map should have a visually nice
- and information-rich background.
-\end{enumerate}
-
-As always, Johannes will have to include the right libraries and set up the
-environment. Johannes is going to use the |mindmap| library and since he wishes
-to show a calendar, he will also need the |calendar| library. In order to put
-something on a background layer, it seems like a good idea to also include the
-|backgrounds| library.
-
-
-\subsection{Introduction to Trees}
-
-The first choice Johannes must make is whether he will organize the concepts as
-a tree, with root concepts and concept branches and leaf concepts, or as a
-general graph. The tree implicitly organizes the concepts, while a graph is
-more flexible. Johannes decides to compromise: Basically, the concepts will be
-organized as a tree. However, he will selectively add connections between
-concepts that are related, but which appear on different levels or branches of
-the tree.
-
-Johannes starts with a tree-like list of concepts that he feels are important
-in Computational Complexity:
-%
-\begin{itemize}
- \item Computational Problems
- \begin{itemize}\itemsep=0pt\parskip=0pt
- \item Problem Measures
- \item Problem Aspects
- \item Problem Domains
- \item Key Problems
- \end{itemize}
- \item Computational Models
- \begin{itemize}\itemsep=0pt\parskip=0pt
- \item Turing Machines
- \item Random-Access Machines
- \item Circuits
- \item Binary Decision Diagrams
- \item Oracle Machines
- \item Programming in Logic
- \end{itemize}
- \item Measuring Complexity
- \begin{itemize}\itemsep=0pt\parskip=0pt
- \item Complexity Measures
- \item Classifying Complexity
- \item Comparing Complexity
- \item Describing Complexity
- \end{itemize}
- \item Solving Problems
- \begin{itemize}\itemsep=0pt\parskip=0pt
- \item Exact Algorithms
- \item Randomization
- \item Fixed-Parameter Algorithms
- \item Parallel Computation
- \item Partial Solutions
- \item Approximation
- \end{itemize}
-\end{itemize}
-
-Johannes will surely need to modify this list later on, but it looks good as a
-first approximation. He will also need to add a number of subtopics (like
-\emph{lots} of complexity classes under the topic ``classifying complexity''),
-but he will do this as he constructs the map.
-
-Turning the list of topics into a \tikzname-tree is easy, in principle. The
-basic idea is that a node can have \emph{children}, which in turn can have
-children of their own, and so on. To add a child to a node, Johannes can simply
-write |child {|\meta{node}|}| right after a node. The \meta{node} should, in
-turn, be the code for creating a node. To add another node, Johannes can use
-|child| once more, and so on. Johannes is eager to try out this construct and
-writes down the following:
-%
-\begin{codeexample}[]
-\tikz
- \node {Computational Complexity} % root
- child { node {Computational Problems}
- child { node {Problem Measures} }
- child { node {Problem Aspects} }
- child { node {Problem Domains} }
- child { node {Key Problems} }
- }
- child { node {Computational Models}
- child { node {Turing Machines} }
- child { node {Random-Access Machines} }
- child { node {Circuits} }
- child { node {Binary Decision Diagrams} }
- child { node {Oracle Machines} }
- child { node {Programming in Logic} }
- }
- child { node {Measuring Complexity}
- child { node {Complexity Measures} }
- child { node {Classifying Complexity} }
- child { node {Comparing Complexity} }
- child { node {Describing Complexity} }
- }
- child { node {Solving Problems}
- child { node {Exact Algorithms} }
- child { node {Randomization} }
- child { node {Fixed-Parameter Algorithms} }
- child { node {Parallel Computation} }
- child { node {Partial Solutions} }
- child { node {Approximation} }
- };
-\end{codeexample}
-
-Well, that did not quite work out as expected (although, what, exactly, did one
-expect?). There are two problems:
-%
-\begin{enumerate}
- \item The overlap of the nodes is due to the fact that \tikzname\ is not
- particularly smart when it comes to placing child nodes. Even though
- it is possible to configure \tikzname\ to use rather clever placement
- methods, \tikzname\ has no way of taking the actual size of the child
- nodes into account. This may seem strange but the reason is that the
- child nodes are rendered and placed one at a time, so the size of the
- last node is not known when the first node is being processed. In
- essence, you have to specify appropriate level and sibling node
- spacings ``by hand''.
- \item The standard computer-science-top-down rendering of a tree is
- rather ill-suited to visualizing the concepts. It would be better to
- either rotate the map by ninety degrees or, even better, to use some
- sort of circular arrangement.
-\end{enumerate}
-
-Johannes redraws the tree, but this time with some more appropriate options
-set, which he found more or less by trial-and-error:
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{trees}},
- render instead={
- \tikz [font=\footnotesize,
- grow=right, level 1/.style={sibling distance=6em},
- level 2/.style={sibling distance=1em}, level distance=5cm]
- \node {Computational Complexity} % root
- child { node {Computational Problems}
- child { node {Problem Measures} } child { node {Problem Aspects} }
- child { node {Problem Domains} } child { node {Key Problems} }
- }
- child { node {Computational Models}
- child { node {Turing Machines} } child { node {Random-Access Machines} }
- child { node {Circuits} } child { node {Binary Decision Diagrams} }
- child { node {Oracle Machines} } child { node {Programming in Logic} }
- }
- child { node {Measuring Complexity}
- child { node {Complexity Measures} } child { node {Classifying Complexity} }
- child { node {Comparing Complexity} } child { node {Describing Complexity} }
- }
- child { node {Solving Problems}
- child { node {Exact Algorithms} } child { node {Randomization} }
- child { node {Fixed-Parameter Algorithms} } child { node {Parallel Computation} }
- child { node {Partial Solutions} } child { node {Approximation} }
- };
- },
-]
-\tikz [font=\footnotesize,
- grow=right, level 1/.style={sibling distance=6em},
- level 2/.style={sibling distance=1em}, level distance=5cm]
- \node {Computational Complexity} % root
- child { node {Computational Problems}
- child { node {Problem Measures} }
- child { node {Problem Aspects} }
- ... % as before
-\end{codeexample}
-
-Still not quite what Johannes had in mind, but he is getting somewhere.
-
-For configuring the tree, two parameters are of particular importance: The
-|level distance| tells \tikzname\ the distance between (the centers of) the
-nodes on adjacent levels or layers of a tree. The |sibling distance| is, as the
-name suggests, the distance between (the centers of) siblings of the tree.
-
-You can globally set these parameters for a tree by simply setting them
-somewhere before the tree starts, but you will typically wish them to be
-different for different levels of the tree. In this case, you should set styles
-like |level 1| or |level 2|. For the first level of the tree, the |level 1|
-style is used, for the second level the |level 2| style, and so on. You can
-also set the sibling and level distances only for certain nodes by passing
-these options to the |child| command as options. (Note that the options of a
-|node| command are local to the node and have no effect on the children. Also
-note that it is possible to specify options that do have an effect on the
-children. Finally note that specifying options for children ``at the right
-place'' is an arcane art and you should peruse
-Section~\ref{section-tree-options} on a rainy Sunday afternoon, if you are
-really interested.)
-
-The |grow| key is used to configure the direction in which a tree grows. You
-can change growth direction ``in the middle of a tree'' simply by changing this
-key for a single child or a whole level. By including the |trees| library you
-also get access to additional growth strategies such as a ``circular'' growth:
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{trees}},
- render instead={
- \tikz [text width=2.7cm, align=flush center,
- grow cyclic,
- level 1/.style={level distance=2.5cm,sibling angle=90},
- level 2/.style={text width=2cm, font=\footnotesize, level distance=3cm,sibling angle=30}]
- \node[font=\bfseries] {Computational Complexity} % root
- child { node {Computational Problems}
- child { node {Problem Measures} } child { node {Problem Aspects} }
- child { node {Problem Domains} } child { node {Key Problems} }
- }
- child { node {Computational Models}
- child { node {Turing Machines} } child { node {Random-Access Machines} }
- child { node {Circuits} } child { node {Binary Decision Diagrams} }
- child { node {Oracle Machines} } child { node {Programming in Logic} }
- }
- child { node {Measuring Complexity}
- child { node {Complexity Measures} } child { node {Classifying Complexity} }
- child { node {Comparing Complexity} } child { node {Describing Complexity} }
- }
- child { node {Solving Problems}
- child { node {Exact Algorithms} } child { node {Randomization} }
- child { node {Fixed-Parameter Algorithms} } child { node {Parallel Computation} }
- child { node {Partial Solutions} } child { node {Approximation} }
- };
- },
-]
-\tikz [text width=2.7cm, align=flush center,
- grow cyclic,
- level 1/.style={level distance=2.5cm,sibling angle=90},
- level 2/.style={text width=2cm, font=\footnotesize, level distance=3cm,sibling angle=30}]
- \node[font=\bfseries] {Computational Complexity} % root
- child { node {Computational Problems}
- child { node {Problem Measures} }
- child { node {Problem Aspects} }
- ... % as before
-\end{codeexample}
-
-Johannes is pleased to learn that he can access and manipulate the nodes of the
-tree like any normal node. In particular, he can name them using the |name=|
-option or the |(|\meta{name}|)| notation and he can use any available shape or
-style for the trees nodes. He can connect trees later on using the normal
-|\draw (some node) -- (another node);| syntax. In essence, the |child| command
-just computes an appropriate position for a node and adds a line from the child
-to the parent node.
-
-
-\subsection{Creating the Lecture Map}
-
-Johannes now has a first possible layout for his lecture map. The next step is
-to make it ``look nicer''. For this, the |mindmap| library is helpful since it
-makes a number of styles available that will make a tree look like a nice
-``mind map'' or ``concept map''.
-
-The first step is to include the |mindmap| library, which Johannes already did.
-Next, he must add one of the following options to a scope that will contain the
-lecture map: |mindmap| or |large mindmap| or |huge mindmap|. These options all
-have the same effect, except that for a |large mindmap| the predefined font
-size and node sizes are somewhat larger than for a standard |mindmap| and for a
-|huge mindmap| they are even larger. So, a |large mindmap| does not necessarily
-need to have a lot of concepts, but it will need a lot of paper.
-
-The second step is to add the |concept| option to every node that will, indeed,
-be a concept of the mindmap. The idea is that some nodes of a tree will be real
-concepts, while other nodes might just be ``simple children''. Typically, this
-is not the case, so you might consider saying |every node/.style=concept|.
-
-The third step is to set up the sibling \emph{angle} (rather than a sibling
-distance) to specify the angle between sibling concepts.
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{mindmap}},
- render instead={
- \tikz [mindmap, every node/.style=concept, concept color=black!20,
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90},
- level 2/.append style={level distance=3cm,sibling angle=45}]
- \node [root concept] {Computational Complexity} % root
- child { node {\hbox to 2cm{Computational\hss} Problems}
- child { node {Problem Measures} }
- child { node {Problem Aspects} }
- child { node {Problem Domains} }
- child { node {Key Problems} }
- }
- child { node {\hbox to 2cm{Computational\hss} Models}
- child { node {Turing Machines} }
- child { node {Random-Access Machines} }
- child { node {Circuits} }
- child { node {Binary Decision Diagrams} }
- child { node {Oracle Machines} }
- child { node {\hbox to1.5cm{Programming\hss} in Logic} }
- }
- child { node {Measuring Complexity}
- child { node {Complexity Measures} }
- child { node {Classifying Complexity} }
- child { node {Comparing Complexity} }
- child { node {Describing Complexity} }
- }
- child { node {Solving Problems}
- child { node {Exact Algorithms} }
- child { node {\hbox to 1.5cm{Randomization\hss}} }
- child { node {Fixed-Parameter Algorithms} }
- child { node {Parallel Computation} }
- child { node {Partial Solutions} }
- child { node {\hbox to1.5cm{Approximation\hss}} }
- };
- },
-]
-\tikz [mindmap, every node/.style=concept, concept color=black!20,
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90},
- level 2/.append style={level distance=3cm,sibling angle=45}]
- \node [root concept] {Computational Complexity} % root
- child { node {Computational Problems}
- child { node {Problem Measures} }
- child { node {Problem Aspects} }
- ... % as before
-\end{codeexample}
-
-When Johannes typesets the above map, \TeX\ (rightfully) starts complaining
-about several overfull boxes and, indeed, words like ``Randomization'' stretch
-out beyond the circle of the concept. This seems a bit mysterious at first
-sight: Why does \TeX\ not hyphenate the word? The reason is that \TeX\ will
-never hyphenate the first word of a paragraph because it starts looking for
-``hyphenatable'' letters only after a so-called glue. In order to have \TeX\
-hyphenate these single words, Johannes must use a bit of evil trickery: He
-inserts a |\hskip0pt| before the word. This has no effect except for inserting
-an (invisible) glue before the word and, thereby, allowing \TeX\ to hyphenate
-the first word also. Since Johannes does not want to add |\hskip0pt| inside
-each node, he uses the |execute at begin node| option to make \tikzname\ insert
-this text with every node.
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{mindmap}},
- render instead={
- \begin{tikzpicture}
- [mindmap,
- every node/.style={concept, execute at begin node=\hskip0pt},
- concept color=black!20,
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90},
- level 2/.append style={level distance=3cm,sibling angle=45}]
- \clip (-1,2) rectangle ++ (-4,5);
- \node [root concept] {Computational Complexity} % root
- child { node {Computational Problems}
- child { node {Problem Measures} }
- child { node {Problem Aspects} }
- child { node {Problem Domains} }
- child { node {Key Problems} }
- }
- child { node {Computational Models}
- child { node {Turing Machines} }
- child { node {Random-Access Machines} }
- child { node {Circuits} }
- child { node {Binary Decision Diagrams} }
- child { node {Oracle Machines} }
- child { node {Programming in Logic} }
- }
- child { node {Measuring Complexity}
- child { node {Complexity Measures} }
- child { node {Classifying Complexity} }
- child { node {Comparing Complexity} }
- child { node {Describing Complexity} }
- }
- child { node {Solving Problems}
- child { node {Exact Algorithms} }
- child { node {Randomization} }
- child { node {Fixed-Parameter Algorithms} }
- child { node {Parallel Computation} }
- child { node {Partial Solutions} }
- child { node {Approximation} }
- };
- \end{tikzpicture}
- },
-]
-\begin{tikzpicture}
- [mindmap,
- every node/.style={concept, execute at begin node=\hskip0pt},
- concept color=black!20,
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90},
- level 2/.append style={level distance=3cm,sibling angle=45}]
- \clip (-1,2) rectangle ++ (-4,5);
- \node [root concept] {Computational Complexity} % root
- child { node {Computational Problems}
- child { node {Problem Measures} }
- child { node {Problem Aspects} }
- ... % as before
-\end{tikzpicture}
-\end{codeexample}
-
-In the above example a clipping was used to show only part of the lecture map,
-in order to save space. The same will be done in the following examples, we
-return to the complete lecture map at the end of this tutorial.
-
-Johannes is now eager to colorize the map. The idea is to use different colors
-for different parts of the map. He can then, during his lectures, talk about
-the ``green'' or the ``red'' topics. This will make it easier for his students
-to locate the topic he is talking about on the map. Since ``computational
-problems'' somehow sounds ``problematic'', Johannes chooses red for them, while
-he picks green for the ``solving problems''. The topics ``measuring
-complexity'' and ``computational models'' get more neutral colors; Johannes
-picks orange and blue.
-
-To set the colors, Johannes must use the |concept color| option, rather than
-just, say, |node [fill=red]|. Setting just the fill color to |red| would,
-indeed, make the node red, but it would \emph{just} make the node red and not
-the bar connecting the concept to its parent and also not its children. By
-comparison, the special |concept color| option will not only set the color of
-the node and its children, but it will also (magically) create appropriate
-shadings so that the color of a parent concept smoothly changes to the color of
-a child concept.
-
-For the root concept Johannes decides to do something special: He sets the
-concept color to black, sets the line width to a large value, and sets the fill
-color to white. The effect of this is that the root concept will be encircled
-with a thick black line and the children are connected to the central concept
-via bars.
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{mindmap}},
- render instead={
- \begin{tikzpicture}
- [mindmap,
- every node/.style={concept, execute at begin node=\hskip0pt},
- root concept/.append style={
- concept color=black,
- fill=white, line width=1ex,
- text=black},
- text=white,
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90},
- level 2/.append style={level distance=3cm,sibling angle=45}]
- \clip (0,-1) rectangle ++(4,5);
- \node [root concept] {Computational Complexity} % root
- child [concept color=red] { node {Computational Problems}
- child { node {Problem Measures} }
- child { node {Problem Aspects} }
- child { node {Problem Domains} }
- child { node {Key Problems} }
- }
- child [concept color=blue] { node {Computational Models}
- child { node {Turing Machines} }
- child { node {Random-Access Machines} }
- child { node {Circuits} }
- child { node {Binary Decision Diagrams} }
- child { node {Oracle Machines} }
- child { node {Programming in Logic} }
- }
- child [concept color=orange] { node {Measuring Complexity}
- child { node {Complexity Measures} }
- child { node {Classifying Complexity} }
- child { node {Comparing Complexity} }
- child { node {Describing Complexity} }
- }
- child [concept color=green!50!black] { node {Solving Problems}
- child { node {Exact Algorithms} }
- child { node {Randomization} }
- child { node {Fixed-Parameter Algorithms} }
- child { node {Parallel Computation} }
- child { node {Partial Solutions} }
- child { node {Approximation} }
- };
- \end{tikzpicture}
- },
-]
-\begin{tikzpicture}
- [mindmap,
- every node/.style={concept, execute at begin node=\hskip0pt},
- root concept/.append style={
- concept color=black, fill=white, line width=1ex, text=black},
- text=white,
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90},
- level 2/.append style={level distance=3cm,sibling angle=45}]
- \clip (0,-1) rectangle ++(4,5);
- \node [root concept] {Computational Complexity} % root
- child [concept color=red] { node {Computational Problems}
- child { node {Problem Measures} }
- ... % as before
- }
- child [concept color=blue] { node {Computational Models}
- child { node {Turing Machines} }
- ... % as before
- }
- child [concept color=orange] { node {Measuring Complexity}
- child { node {Complexity Measures} }
- ... % as before
- }
- child [concept color=green!50!black] { node {Solving Problems}
- child { node {Exact Algorithms} }
- ... % as before
- };
-\end{tikzpicture}
-\end{codeexample}
-
-Johannes adds three finishing touches: First, he changes the font of the main
-concepts to small caps. Second, he decides that some concepts should be
-``faded'', namely those that are important in principle and belong on the map,
-but which he will not talk about in his lecture. To achieve this, Johannes
-defines four styles, one for each of the four main branches. These styles (a)
-set up the correct concept color for the whole branch and (b) define the
-|faded| style appropriately for this branch. Third, he adds a
-|circular drop shadow|, defined in the |shadows| library, to the concepts, just
-to make things look a bit more fancy.
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{mindmap,shadows}},
- render instead={
- \begin{tikzpicture}[mindmap]
- \begin{scope}[
- every node/.style={concept, circular drop shadow,execute at begin node=\hskip0pt},
- root concept/.append style={
- concept color=black,
- fill=white, line width=1ex,
- text=black, font=\large\scshape},
- text=white,
- computational problems/.style={concept color=red,faded/.style={concept color=red!50}},
- computational models/.style={concept color=blue,faded/.style={concept color=blue!50}},
- measuring complexity/.style={concept color=orange,faded/.style={concept color=orange!50}},
- solving problems/.style={concept color=green!50!black,faded/.style={concept color=green!50!black!50}},
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90,font=\scshape},
- level 2/.append style={level distance=3cm,sibling angle=45,font=\scriptsize}]
- \node [root concept] {Computational Complexity} % root
- child [computational problems] { node {Computational Problems}
- child { node {Problem Measures} }
- child { node {Problem Aspects} }
- child [faded] { node {Problem Domains} }
- child { node {Key Problems} }
- }
- child [computational models] { node {Computational Models}
- child { node {Turing Machines} }
- child [faded] { node {Random-Access Machines} }
- child { node {Circuits} }
- child [faded] { node {Binary Decision Diagrams} }
- child { node {Oracle Machines} }
- child { node {Programming in Logic} }
- }
- child [measuring complexity] { node {Measuring Complexity}
- child { node {Complexity Measures} }
- child { node {Classifying Complexity} }
- child { node {Comparing Complexity} }
- child [faded] { node {Describing Complexity} }
- }
- child [solving problems] { node {Solving Problems}
- child { node {Exact Algorithms} }
- child { node {Randomization} }
- child { node {Fixed-Parameter Algorithms} }
- child { node {Parallel Computation} }
- child { node {Partial Solutions} }
- child { node {Approximation} }
- };
- \end{scope}
- \end{tikzpicture}
- },
-]
-\begin{tikzpicture}[mindmap]
- \begin{scope}[
- every node/.style={concept, circular drop shadow,execute at begin node=\hskip0pt},
- root concept/.append style={
- concept color=black, fill=white, line width=1ex, text=black, font=\large\scshape},
- text=white,
- computational problems/.style={concept color=red,faded/.style={concept color=red!50}},
- computational models/.style={concept color=blue,faded/.style={concept color=blue!50}},
- measuring complexity/.style={concept color=orange,faded/.style={concept color=orange!50}},
- solving problems/.style={concept color=green!50!black,faded/.style={concept color=green!50!black!50}},
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90,font=\scshape},
- level 2/.append style={level distance=3cm,sibling angle=45,font=\scriptsize}]
- \node [root concept] {Computational Complexity} % root
- child [computational problems] { node {Computational Problems}
- child { node {Problem Measures} }
- child { node {Problem Aspects} }
- child [faded] { node {Problem Domains} }
- child { node {Key Problems} }
- }
- child [computational models] { node {Computational Models}
- child { node {Turing Machines} }
- child [faded] { node {Random-Access Machines} }
- ...
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Adding the Lecture Annotations}
-
-Johannes will give about a dozen lectures during the course ``computational
-complexity''. For each lecture he has compiled a (short) list of learning
-targets that state what knowledge and qualifications his students should
-acquire during this particular lecture (note that learning targets are not the
-same as the contents of a lecture). For each lecture he intends to put a little
-rectangle on the map containing these learning targets and the name of the
-lecture, each time somewhere near the topic of the lecture. Such ``little
-rectangles'' are called ``annotations'' by the |mindmap| library.
-
-In order to place the annotations next to the concepts, Johannes must assign
-names to the nodes of the concepts. He could rely on \tikzname's automatic
-naming of the nodes in a tree, where the children of a node named |root| are
-named |root-1|, |root-2|, |root-3|, and so on. However, since Johannes is not
-sure about the final order of the concepts in the tree, it seems better to
-explicitly name all concepts of the tree in the following manner:
-%
-\begin{codeexample}[code only]
-\node [root concept] (Computational Complexity) {Computational Complexity}
- child [computational problems] { node (Computational Problems) {Computational Problems}
- child { node (Problem Measures) {Problem Measures} }
- child { node (Problem Aspects) {Problem Aspects} }
- child [faded] { node (Problem Domains) {Problem Domains} }
- child { node (Key Problems) {Key Problems} }
- }
-...
-\end{codeexample}
-
-The |annotation| style of the |mindmap| library mainly sets up a rectangular
-shape of appropriate size. Johannes configures the style by defining
-|every annotation| appropriately.
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{mindmap,shadows}},
- render instead={
- \begin{tikzpicture}[mindmap]
- \clip (-5.25,-3) rectangle ++ (4,5);
- \begin{scope}[
- every node/.style={concept, circular drop shadow,execute at begin node=\hskip0pt},
- root concept/.append style={
- concept color=black,
- fill=white, line width=1ex,
- text=black, font=\large\scshape},
- text=white,
- computational problems/.style={concept color=red,faded/.style={concept color=red!50}},
- computational models/.style={concept color=blue,faded/.style={concept color=blue!50}},
- measuring complexity/.style={concept color=orange,faded/.style={concept color=orange!50}},
- solving problems/.style={concept color=green!50!black,faded/.style={concept color=green!50!black!50}},
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90,font=\scshape},
- level 2/.append style={level distance=3cm,sibling angle=45,font=\scriptsize}]
- \node [root concept] (Computational Complexity) {Computational Complexity} % root
- child [computational problems] { node (Computational Problems) {Computational Problems}
- child { node (Problem Measures) {Problem Measures} }
- child { node (Problem Aspects) {Problem Aspects} }
- child [faded] { node (problem Domains) {Problem Domains} }
- child { node (Key Problems) {Key Problems} }
- }
- child [computational models] { node (Computational Models) {Computational Models}
- child { node (Turing Machines) {Turing Machines} }
- child [faded] { node (Random-Access Machines) {Random-Access Machines} }
- child { node (Circuits) {Circuits} }
- child [faded] { node (Binary Decision Diagrams) {Binary Decision Diagrams} }
- child { node (Oracle Machines) {Oracle Machines} }
- child { node (Programming in Logic) {Programming in Logic} }
- }
- child [measuring complexity] { node (Measuring Complexity) {Measuring Complexity}
- child { node (Complexity Measures) {Complexity Measures} }
- child { node (Classifying Complexity) {Classifying Complexity} }
- child { node (Comparing Complexity) {Comparing Complexity} }
- child [faded] { node (Describing Complexity) {Describing Complexity} }
- }
- child [solving problems] { node (Solving Problems) {Solving Problems}
- child { node (Exact Algorithms) {Exact Algorithms} }
- child { node (Randomization) {Randomization} }
- child { node (Fixed-Parameter Algorithms) {Fixed-Parameter Algorithms} }
- child { node (Parallel Computation) {Parallel Computation} }
- child { node (Partial Solutions) {Partial Solutions} }
- child { node (Approximation) {Approximation} }
- };
- \end{scope}
- \begin{scope}[every annotation/.style={fill=black!40}]
- \node [annotation, above] at (Computational Problems.north) {
- Lecture 1: Computational Problems
- \begin{itemize}
- \item Knowledge of several key problems
- \item Knowledge of problem encodings
- \item Being able to formalize problems
- \end{itemize}
- };
- \end{scope}
- \end{tikzpicture}
- },
-]
-\begin{tikzpicture}[mindmap]
- \clip (-5,-5) rectangle ++ (4,5);
- \begin{scope}[
- every node/.style={concept, circular drop shadow, ...}] % as before
- \node [root concept] (Computational Complexity) ... % as before
- \end{scope}
-
- \begin{scope}[every annotation/.style={fill=black!40}]
- \node [annotation, above] at (Computational Problems.north) {
- Lecture 1: Computational Problems
- \begin{itemize}
- \item Knowledge of several key problems
- \item Knowledge of problem encodings
- \item Being able to formalize problems
- \end{itemize}
- };
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-Well, that does not yet look quite perfect. The spacing or the |{itemize}| is
-not really appropriate and the node is too large. Johannes can configure these
-things ``by hand'', but it seems like a good idea to define a macro that will
-take care of these things for him. The ``right'' way to do this is to define a
-|\lecture| macro that takes a list of key--value pairs as argument and produces
-the desired annotation. However, to keep things simple, Johannes' |\lecture|
-macro simply takes a fixed number of arguments having the following meaning:
-The first argument is the number of the lecture, the second is the name of the
-lecture, the third are positioning options like |above|, the fourth is the
-position where the node is placed, the fifth is the list of items to be shown,
-and the sixth is a date when the lecture will be held (this parameter is not
-yet needed, we will, however, need it later on).
-%
-% TODOsp: codeexamples: redo `\lecture` definition*s* when `preamble` can be emptied
-\begin{codeexample}[code only]
-\def\lecture#1#2#3#4#5#6{
- \node [annotation, #3, scale=0.65, text width=4cm, inner sep=2mm] at (#4) {
- Lecture #1: \textcolor{orange}{\textbf{#2}}
- \list{--}{\topsep=2pt\itemsep=0pt\parsep=0pt
- \parskip=0pt\labelwidth=8pt\leftmargin=8pt
- \itemindent=0pt\labelsep=2pt}
- #5
- \endlist
- };
-}
-\end{codeexample}
-% TODOsp: codeexamples: this definition can most likely be deleted,
-% because it is moved to the `pre` key in the `codeexamples`
-\def\lecture#1#2#3#4#5#6{
- \node [annotation, #3, scale=0.65, text width=4cm, inner sep=2mm] at (#4) {
- Lecture #1: \textcolor{orange}{\textbf{#2}}
- \list{--}{\topsep=2pt\itemsep=0pt\parsep=0pt
- \parskip=0pt\labelwidth=8pt\leftmargin=8pt
- \itemindent=0pt\labelsep=2pt}
- #5
- \endlist
- };
-}
-
-\begin{codeexample}[
- preamble={\usetikzlibrary{mindmap,shadows}},
- pre={ % !!! replace all `##x` with `#x`
-\def\lecture##1##2##3##4##5##6{
- \node [annotation, ##3, scale=0.65, text width=4cm, inner sep=2mm] at (##4) {
- Lecture ##1: \textcolor{orange}{\textbf{##2}}
- \list{--}{\topsep=2pt\itemsep=0pt\parsep=0pt
- \parskip=0pt\labelwidth=8pt\leftmargin=8pt
- \itemindent=0pt\labelsep=2pt}
- ##5
- \endlist
- };
-}},
- render instead={
- \begin{tikzpicture}[mindmap,every annotation/.style={fill=white}]
- \clip (-5.25,-3) rectangle ++ (4,5);
- \begin{scope}[
- every node/.style={concept, circular drop shadow,execute at begin node=\hskip0pt},
- root concept/.append style={
- concept color=black,
- fill=white, line width=1ex,
- text=black, font=\large\scshape},
- text=white,
- computational problems/.style={concept color=red,faded/.style={concept color=red!50}},
- computational models/.style={concept color=blue,faded/.style={concept color=blue!50}},
- measuring complexity/.style={concept color=orange,faded/.style={concept color=orange!50}},
- solving problems/.style={concept color=green!50!black,faded/.style={concept color=green!50!black!50}},
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90,font=\scshape},
- level 2/.append style={level distance=3cm,sibling angle=45,font=\scriptsize}]
- \node [root concept] (Computational Complexity) {Computational Complexity} % root
- child [computational problems] { node (Computational Problems) {Computational Problems}
- child { node (Problem Measures) {Problem Measures} }
- child { node (Problem Aspects) {Problem Aspects} }
- child [faded] { node (problem Domains) {Problem Domains} }
- child { node (Key Problems) {Key Problems} }
- }
- child [computational models] { node (Computational Models) {Computational Models}
- child { node (Turing Machines) {Turing Machines} }
- child [faded] { node (Random-Access Machines) {Random-Access Machines} }
- child { node (Circuits) {Circuits} }
- child [faded] { node (Binary Decision Diagrams) {Binary Decision Diagrams} }
- child { node (Oracle Machines) {Oracle Machines} }
- child { node (Programming in Logic) {Programming in Logic} }
- }
- child [measuring complexity] { node (Measuring Complexity) {Measuring Complexity}
- child { node (Complexity Measures) {Complexity Measures} }
- child { node (Classifying Complexity) {Classifying Complexity} }
- child { node (Comparing Complexity) {Comparing Complexity} }
- child [faded] { node (Describing Complexity) {Describing Complexity} }
- }
- child [solving problems] { node (Solving Problems) {Solving Problems}
- child { node (Exact Algorithms) {Exact Algorithms} }
- child { node (Randomization) {Randomization} }
- child { node (Fixed-Parameter Algorithms) {Fixed-Parameter Algorithms} }
- child { node (Parallel Computation) {Parallel Computation} }
- child { node (Partial Solutions) {Partial Solutions} }
- child { node (Approximation) {Approximation} }
- };
- \end{scope}
- \lecture{1}{Computational Problems}{above,xshift=-3mm}{Computational Problems.north}{
- \item Knowledge of several key problems
- \item Knowledge of problem encodings
- \item Being able to formalize problems
- }{2009-04-08}
- \end{tikzpicture}
- },
-]
-\begin{tikzpicture}[mindmap,every annotation/.style={fill=white}]
- \clip (-5,-5) rectangle ++ (4,5);
- \begin{scope}[
- every node/.style={concept, circular drop shadow, ... % as before
- \node [root concept] (Computational Complexity) ... % as before
- \end{scope}
-
- \lecture{1}{Computational Problems}{above,xshift=-3mm}
- {Computational Problems.north}{
- \item Knowledge of several key problems
- \item Knowledge of problem encodings
- \item Being able to formalize problems
- }{2009-04-08}
-\end{tikzpicture}
-\end{codeexample}
-
-In the same fashion Johannes can now add the other lecture annotations.
-Obviously, Johannes will have some trouble fitting everything on a single
-A4-sized page, but by adjusting the spacing and some experimentation he can
-quickly arrange all the annotations as needed.
-
-
-\subsection{Adding the Background}
-
-Johannes has already used colors to organize his lecture map into four regions,
-each having a different color. In order to emphasize these regions even more
-strongly, he wishes to add a background coloring to each of these regions.
-
-Adding these background colors turns out to be more tricky than Johannes would
-have thought. At first sight, what he needs is some sort of ``color wheel''
-that is blue in the lower right direction and then changes smoothly to orange
-in the upper right direction and then to green in the upper left direction and
-so on. Unfortunately, there is no easy way of creating such a color wheel
-shading (although it can be done, in principle, but only at a very high cost,
-see page~\pageref{shading-color-wheel} for an example).
-
-Johannes decides to do something a bit more basic: He creates four large
-rectangles, one for each of the four quadrants around the central concept, each
-colored with a light version of the quadrant. Then, in order to ``smooth'' the
-change between adjacent rectangles, he puts four shadings on top of them.
-
-Since these background rectangles should go ``behind'' everything else,
-Johannes puts all his background stuff on the |background| layer.
-
-In the following code, only the central concept is shown to save some space:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{backgrounds,mindmap,shadows}}]
-\begin{tikzpicture}[
- mindmap,
- concept color=black,
- root concept/.append style={
- concept,
- circular drop shadow,
- fill=white, line width=1ex,
- text=black, font=\large\scshape}
- ]
-
- \clip (-1.5,-5) rectangle ++(4,10);
-
- \node [root concept] (Computational Complexity) {Computational Complexity};
-
- \begin{pgfonlayer}{background}
- \clip (-1.5,-5) rectangle ++(4,10);
-
- \colorlet{upperleft}{green!50!black!25}
- \colorlet{upperright}{orange!25}
- \colorlet{lowerleft}{red!25}
- \colorlet{lowerright}{blue!25}
-
- % The large rectangles:
- \fill [upperleft] (Computational Complexity) rectangle ++(-20,20);
- \fill [upperright] (Computational Complexity) rectangle ++(20,20);
- \fill [lowerleft] (Computational Complexity) rectangle ++(-20,-20);
- \fill [lowerright] (Computational Complexity) rectangle ++(20,-20);
-
- % The shadings:
- \shade [left color=upperleft,right color=upperright]
- ([xshift=-1cm]Computational Complexity) rectangle ++(2,20);
- \shade [left color=lowerleft,right color=lowerright]
- ([xshift=-1cm]Computational Complexity) rectangle ++(2,-20);
- \shade [top color=upperleft,bottom color=lowerleft]
- ([yshift=-1cm]Computational Complexity) rectangle ++(-20,2);
- \shade [top color=upperright,bottom color=lowerright]
- ([yshift=-1cm]Computational Complexity) rectangle ++(20,2);
- \end{pgfonlayer}
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Adding the Calendar}
-
-Johannes intends to plan his lecture rather carefully. In particular, he
-already knows when each of his lectures will be held during the course.
-Naturally, this does not mean that Johannes will slavishly follow the plan and
-he might need longer for some subjects than he anticipated, but nevertheless he
-has a detailed plan of when which subject will be addressed.
-
-Johannes intends to share this plan with his students by adding a calendar to
-the lecture map. In addition to serving as a reference on which particular day
-a certain topic will be addressed, the calendar is also useful to show the
-overall chronological order of the course.
-
-In order to add a calendar to a \tikzname\ graphic, the |calendar| library is
-most useful. The library provides the |\calendar| command, which takes a large
-number of options and which can be configured in many ways to produce just
-about any kind of calendar imaginable. For Johannes' purposes, a simple
-|day list downward| will be a nice option since it produces a list of days that
-go ``downward''.
-%
-\begin{codeexample}[
- leave comments,
- preamble={\usetikzlibrary{calendar}},
-]
-\tiny
-\begin{tikzpicture}
- \calendar [day list downward,
- name=cal,
- dates=2009-04-01 to 2009-04-14]
- if (weekend)
- [black!25];
-\end{tikzpicture}
-\end{codeexample}
-
-Using the |name| option, we gave a name to the calendar, which will allow us to
-reference the nodes that make up the individual days of the calendar later on.
-For instance, the rectangular node containing the |1| that represents April
-1st, 2009, can be referenced as |(cal-2009-04-01)|. The |dates| option is used
-to specify an interval for which the calendar should be drawn. Johannes will
-need several months in his calendar, but the above example only shows two weeks
-to save some space.
-
-Note the |if (weekend)| construct. The |\calendar| command is followed by
-options and then by |if|-statements. These |if|-statements are checked for each
-day of the calendar and when a date passes this test, the options or the code
-following the |if|-statement is executed. In the above example, we make weekend
-days (Saturdays and Sundays, to be precise) lighter than normal days. (Use your
-favorite calendar to check that, indeed, April 5th, 2009, is a Sunday.)
-
-As mentioned above, Johannes can reference the nodes that are used to typeset
-days. Recall that his |\lecture| macro already got passed a date, which we did
-not use, yet. We can now use it to place the lecture's title next to the date
-when the lecture will be held:
-%
-\begin{codeexample}[code only]
-\def\lecture#1#2#3#4#5#6{
- % As before:
- \node [annotation, #3, scale=0.65, text width=4cm, inner sep=2mm] at (#4) {
- Lecture #1: \textcolor{orange}{\textbf{#2}}
- \list{--}{\topsep=2pt\itemsep=0pt\parsep=0pt
- \parskip=0pt\labelwidth=8pt\leftmargin=8pt
- \itemindent=0pt\labelsep=2pt}
- #5
- \endlist
- };
- % New:
- \node [anchor=base west] at (cal-#6.base east) {\textcolor{orange}{\textbf{#2}}};
-}
-\end{codeexample}
-\def\lecture#1#2#3#4#5#6{
- \node [anchor=base west] at (cal-#6.base east) {\textcolor{orange}{\textbf{#2}}};
-}
-
-Johannes can now use this new |\lecture| command as follows (in the example,
-only the new part of the definition is used):
-%
-\begin{codeexample}[
- preamble={\usetikzlibrary{calendar}},
- pre={ % !!! replace all `##x` with `#x`
-\def\lecture##1##2##3##4##5##6{
- \node [anchor=base west] at (cal-##6.base east) {\textcolor{orange}{\textbf{##2}}};
-}},
-]
-\tiny
-\begin{tikzpicture}
- \calendar [day list downward,
- name=cal,
- dates=2009-04-01 to 2009-04-14]
- if (weekend)
- [black!25];
-
- % As before:
- \lecture{1}{Computational Problems}{above,xshift=-3mm}
- {Computational Problems.north}{
- \item Knowledge of several key problems
- \item Knowledge of problem encodings
- \item Being able to formalize problems
- }{2009-04-08}
-\end{tikzpicture}
-\end{codeexample}
-
-As a final step, Johannes needs to add a few more options to the calendar
-command: He uses the |month text| option to configure how the text of a month
-is rendered (see Section~\ref{section-calender} for details) and then typesets
-the month text at a special position at the beginning of each month.
-%
-\begin{codeexample}[
- leave comments,
- preamble={\usetikzlibrary{calendar}},
- pre={ % !!! replace all `##x` with `#x`
-\def\lecture##1##2##3##4##5##6{
- \node [anchor=base west] at (cal-##6.base east) {\textcolor{orange}{\textbf{##2}}};
-}},
-]
-\tiny
-\begin{tikzpicture}
- \calendar [day list downward,
- month text=\%mt\ \%y0,
- month yshift=3.5em,
- name=cal,
- dates=2009-04-01 to 2009-05-01]
- if (weekend)
- [black!25]
- if (day of month=1) {
- \node at (0pt,1.5em) [anchor=base west] {\small\tikzmonthtext};
- };
-
- \lecture{1}{Computational Problems}{above,xshift=-3mm}
- {Computational Problems.north}{
- \item Knowledge of several key problems
- \item Knowledge of problem encodings
- \item Being able to formalize problems
- }{2009-04-08}
-
- \lecture{2}{Computational Models}{above,xshift=-3mm}
- {Computational Models.north}{
- \item Knowledge of Turing machines
- \item Being able to compare the computational power of different
- models
- }{2009-04-15}
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{The Complete Code}
-
-Putting it all together, Johannes gets the following code:
-
-First comes the definition of the |\lecture| command:
-%
-\begin{codeexample}[code only]
-\def\lecture#1#2#3#4#5#6{
- % As before:
- \node [annotation, #3, scale=0.65, text width=4cm, inner sep=2mm, fill=white] at (#4) {
- Lecture #1: \textcolor{orange}{\textbf{#2}}
- \list{--}{\topsep=2pt\itemsep=0pt\parsep=0pt
- \parskip=0pt\labelwidth=8pt\leftmargin=8pt
- \itemindent=0pt\labelsep=2pt}
- #5
- \endlist
- };
- % New:
- \node [anchor=base west] at (cal-#6.base east) {\textcolor{orange}{\textbf{#2}}};
-}
-\end{codeexample}
-
-This is followed by the main mindmap setup\dots
-%
-\begin{codeexample}[code only]
-\noindent
-\begin{tikzpicture}
- \begin{scope}[
- mindmap,
- every node/.style={concept, circular drop shadow,execute at begin node=\hskip0pt},
- root concept/.append style={
- concept color=black,
- fill=white, line width=1ex,
- text=black, font=\large\scshape},
- text=white,
- computational problems/.style={concept color=red,faded/.style={concept color=red!50}},
- computational models/.style={concept color=blue,faded/.style={concept color=blue!50}},
- measuring complexity/.style={concept color=orange,faded/.style={concept color=orange!50}},
- solving problems/.style={concept color=green!50!black,faded/.style={concept color=green!50!black!50}},
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90,font=\scshape},
- level 2/.append style={level distance=3cm,sibling angle=45,font=\scriptsize}]
-\end{codeexample}
-%
-\dots and contents:
-%
-\begin{codeexample}[code only]
- \node [root concept] (Computational Complexity) {Computational Complexity} % root
- child [computational problems] { node [yshift=-1cm] (Computational Problems) {Computational Problems}
- child { node (Problem Measures) {Problem Measures} }
- child { node (Problem Aspects) {Problem Aspects} }
- child [faded] { node (problem Domains) {Problem Domains} }
- child { node (Key Problems) {Key Problems} }
- }
- child [computational models] { node [yshift=-1cm] (Computational Models) {Computational Models}
- child { node (Turing Machines) {Turing Machines} }
- child [faded] { node (Random-Access Machines) {Random-Access Machines} }
- child { node (Circuits) {Circuits} }
- child [faded] { node (Binary Decision Diagrams) {Binary Decision Diagrams} }
- child { node (Oracle Machines) {Oracle Machines} }
- child { node (Programming in Logic) {Programming in Logic} }
- }
- child [measuring complexity] { node [yshift=1cm] (Measuring Complexity) {Measuring Complexity}
- child { node (Complexity Measures) {Complexity Measures} }
- child { node (Classifying Complexity) {Classifying Complexity} }
- child { node (Comparing Complexity) {Comparing Complexity} }
- child [faded] { node (Describing Complexity) {Describing Complexity} }
- }
- child [solving problems] { node [yshift=1cm] (Solving Problems) {Solving Problems}
- child { node (Exact Algorithms) {Exact Algorithms} }
- child { node (Randomization) {Randomization} }
- child { node (Fixed-Parameter Algorithms) {Fixed-Parameter Algorithms} }
- child { node (Parallel Computation) {Parallel Computation} }
- child { node (Partial Solutions) {Partial Solutions} }
- child { node (Approximation) {Approximation} }
- };
- \end{scope}
-\end{codeexample}
-%
-Now comes the calendar code:
-%
-\begin{codeexample}[code only]
- \tiny
- \calendar [day list downward,
- month text=\%mt\ \%y0,
- month yshift=3.5em,
- name=cal,
- at={(-.5\textwidth-5mm,.5\textheight-1cm)},
- dates=2009-04-01 to 2009-06-last]
- if (weekend)
- [black!25]
- if (day of month=1) {
- \node at (0pt,1.5em) [anchor=base west] {\small\tikzmonthtext};
- };
-\end{codeexample}
-%
-The lecture annotations:
-%
-\begin{codeexample}[code only]
- \lecture{1}{Computational Problems}{above,xshift=-5mm,yshift=5mm}{Computational Problems.north}{
- \item Knowledge of several key problems
- \item Knowledge of problem encodings
- \item Being able to formalize problems
- }{2009-04-08}
-
- \lecture{2}{Computational Models}{above left}
- {Computational Models.west}{
- \item Knowledge of Turing machines
- \item Being able to compare the computational power of different
- models
- }{2009-04-15}
-\end{codeexample}
-%
-Finally, the background:
-%
-\begin{codeexample}[code only]
- \begin{pgfonlayer}{background}
- \clip[xshift=-1cm] (-.5\textwidth,-.5\textheight) rectangle ++(\textwidth,\textheight);
-
- \colorlet{upperleft}{green!50!black!25}
- \colorlet{upperright}{orange!25}
- \colorlet{lowerleft}{red!25}
- \colorlet{lowerright}{blue!25}
-
- % The large rectangles:
- \fill [upperleft] (Computational Complexity) rectangle ++(-20,20);
- \fill [upperright] (Computational Complexity) rectangle ++(20,20);
- \fill [lowerleft] (Computational Complexity) rectangle ++(-20,-20);
- \fill [lowerright] (Computational Complexity) rectangle ++(20,-20);
-
- % The shadings:
- \shade [left color=upperleft,right color=upperright]
- ([xshift=-1cm]Computational Complexity) rectangle ++(2,20);
- \shade [left color=lowerleft,right color=lowerright]
- ([xshift=-1cm]Computational Complexity) rectangle ++(2,-20);
- \shade [top color=upperleft,bottom color=lowerleft]
- ([yshift=-1cm]Computational Complexity) rectangle ++(-20,2);
- \shade [top color=upperright,bottom color=lowerright]
- ([yshift=-1cm]Computational Complexity) rectangle ++(20,2);
- \end{pgfonlayer}
-\end{tikzpicture}
-\end{codeexample}
-
-The next page shows the resulting lecture map in all its glory (it
-would be somewhat more glorious, if there were more lecture
-annotations, but you should get the idea).
-
-\def\lecture#1#2#3#4#5#6{
- % As before:
- \node [annotation, #3, scale=0.65, text width=4cm, inner sep=2mm, fill=white] at (#4) {
- Lecture #1: \textcolor{orange}{\textbf{#2}}
- \list{--}{\topsep=2pt\itemsep=0pt\parsep=0pt
- \parskip=0pt\labelwidth=8pt\leftmargin=8pt
- \itemindent=0pt\labelsep=2pt}
- #5
- \endlist
- };
- % New:
- \node [anchor=base west] at (cal-#6.base east) {\textcolor{orange}{\textbf{#2}}};
-}
-
-\noindent
-\begin{tikzpicture}
- \begin{scope}[
- mindmap,
- every node/.style={concept, circular drop shadow,execute at begin node=\hskip0pt},
- root concept/.append style={
- concept color=black,
- fill=white, line width=1ex,
- text=black, font=\large\scshape},
- text=white,
- computational problems/.style={concept color=red,faded/.style={concept color=red!50}},
- computational models/.style={concept color=blue,faded/.style={concept color=blue!50}},
- measuring complexity/.style={concept color=orange,faded/.style={concept color=orange!50}},
- solving problems/.style={concept color=green!50!black,faded/.style={concept color=green!50!black!50}},
- grow cyclic,
- level 1/.append style={level distance=4.5cm,sibling angle=90,font=\scshape},
- level 2/.append style={level distance=3cm,sibling angle=45,font=\scriptsize}]
- \node [root concept] (Computational Complexity) {Computational Complexity} % root
- child [computational problems] { node [yshift=-1cm] (Computational Problems) {Computational Problems}
- child { node (Problem Measures) {Problem Measures} }
- child { node (Problem Aspects) {Problem Aspects} }
- child [faded] { node (problem Domains) {Problem Domains} }
- child { node (Key Problems) {Key Problems} }
- }
- child [computational models] { node [yshift=-1cm] (Computational Models) {Computational Models}
- child { node (Turing Machines) {Turing Machines} }
- child [faded] { node (Random-Access Machines) {Random-Access Machines} }
- child { node (Circuits) {Circuits} }
- child [faded] { node (Binary Decision Diagrams) {Binary Decision Diagrams} }
- child { node (Oracle Machines) {Oracle Machines} }
- child { node (Programming in Logic) {Programming in Logic} }
- }
- child [measuring complexity] { node [yshift=1cm] (Measuring Complexity) {Measuring Complexity}
- child { node (Complexity Measures) {Complexity Measures} }
- child { node (Classifying Complexity) {Classifying Complexity} }
- child { node (Comparing Complexity) {Comparing Complexity} }
- child [faded] { node (Describing Complexity) {Describing Complexity} }
- }
- child [solving problems] { node [yshift=1cm] (Solving Problems) {Solving Problems}
- child { node (Exact Algorithms) {Exact Algorithms} }
- child { node (Randomization) {Randomization} }
- child { node (Fixed-Parameter Algorithms) {Fixed-Parameter Algorithms} }
- child { node (Parallel Computation) {Parallel Computation} }
- child { node (Partial Solutions) {Partial Solutions} }
- child { node (Approximation) {Approximation} }
- };
- \end{scope}
-
- \tiny
- \calendar [day list downward,
- month text=\%mt\ \%y0,
- month yshift=3.5em,
- name=cal,
- at={(-.5\textwidth-5mm,.5\textheight-1cm)},
- dates=2009-04-01 to 2009-06-last]
- if (weekend)
- [black!25]
- if (day of month=1) {
- \node at (0pt,1.5em) [anchor=base west] {\small\tikzmonthtext};
- };
-
- \lecture{1}{Computational Problems}{above,xshift=-5mm,yshift=5mm}{Computational Problems.north}{
- \item Knowledge of several key problems
- \item Knowledge of problem encodings
- \item Being able to formalize problems
- }{2009-04-08}
-
- \lecture{2}{Computational Models}{above left}
- {Computational Models.west}{
- \item Knowledge of Turing machines
- \item Being able to compare the computational power of different
- models
- }{2009-04-15}
-
- \begin{pgfonlayer}{background}
- \clip[xshift=-1cm] (-.5\textwidth,-.5\textheight) rectangle ++(\textwidth,\textheight);
-
- \colorlet{upperleft}{green!50!black!25}
- \colorlet{upperright}{orange!25}
- \colorlet{lowerleft}{red!25}
- \colorlet{lowerright}{blue!25}
-
- % The large rectangles:
- \fill [upperleft] (Computational Complexity) rectangle ++(-20,20);
- \fill [upperright] (Computational Complexity) rectangle ++(20,20);
- \fill [lowerleft] (Computational Complexity) rectangle ++(-20,-20);
- \fill [lowerright] (Computational Complexity) rectangle ++(20,-20);
-
- % The shadings:
- \shade [left color=upperleft,right color=upperright]
- ([xshift=-1cm]Computational Complexity) rectangle ++(2,20);
- \shade [left color=lowerleft,right color=lowerright]
- ([xshift=-1cm]Computational Complexity) rectangle ++(2,-20);
- \shade [top color=upperleft,bottom color=lowerleft]
- ([yshift=-1cm]Computational Complexity) rectangle ++(-20,2);
- \shade [top color=upperright,bottom color=lowerright]
- ([yshift=-1cm]Computational Complexity) rectangle ++(20,2);
- \end{pgfonlayer}
-\end{tikzpicture}
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-nodes.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-nodes.tex
deleted file mode 100644
index 66cacc41af..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial-nodes.tex
+++ /dev/null
@@ -1,1020 +0,0 @@
-% Copyright 2020 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{Tutorial: A Petri-Net for Hagen}
-
-In this second tutorial we explore the node mechanism of \tikzname\ and
-\pgfname.
-
-Hagen must give a talk tomorrow about his favorite formalism for distributed
-systems: Petri nets! Hagen used to give his talks using a blackboard and
-everyone seemed to be perfectly content with this. Unfortunately, his audience
-has been spoiled recently with fancy projector-based presentations and there
-seems to be a certain amount of peer pressure that his Petri nets should also
-be drawn using a graphic program. One of the professors at his institute
-recommends \tikzname\ for this and Hagen decides to give it a try.
-
-
-\subsection{Problem Statement}
-
-For his talk, Hagen wishes to create a graphic that demonstrates how a net with
-place capacities can be simulated by a net without capacities. The graphic
-should look like this, ideally:
-%
-\begin{quote}
-\begin{tikzpicture}
- [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},
- every label/.style={red},on grid]
-
- \begin{scope}
- % First net
- \node [place,tokens=1] (w1) {};
- \node [place] (c1) [below=of w1] {};
- \node [place] (s) [below=of c1,label=above:$s\le 3$] {};
- \node [place] (c2) [below=of s] {};
- \node [place,tokens=1] (w2) [below=of c2] {};
-
- \node [transition] (e1) [left=of c1] {}
- edge [pre,bend left] (w1)
- edge [post,bend right] (s)
- edge [post] (c1);
-
- \node [transition] (e2) [left=of c2] {}
- edge [pre,bend right] (w2)
- edge [post,bend left] (s)
- edge [post] (c2);
-
- \node [transition] (l1) [right=of c1] {}
- edge [pre] (c1)
- edge [pre,bend left] (s)
- edge [post,bend right] node[swap] {2} (w1);
-
- \node [transition] (l2) [right=of c2] {}
- edge [pre] (c2)
- edge [pre,bend right] (s)
- edge [post,bend left] node {2} (w2);
- \end{scope}
-
- \begin{scope}[xshift=6cm]
- % Second net
- \node [place,tokens=1]
- (w1') {};
- \node [place] (c1') [below=of w1'] {};
- \node [red place] (s1') [below=of c1',xshift=-5mm,label=left:$s$] {};
- \node [red place,tokens=3]
- (s2') [below=of c1',xshift=5mm,label=right:$\bar s$] {};
- \node [place] (c2') [below=of s1',xshift=5mm] {};
- \node [place,tokens=1]
- (w2') [below=of c2'] {};
-
- \node [transition] (e1') [left=of c1'] {}
- edge [pre,bend left] (w1')
- edge [post] (s1')
- edge [pre] (s2')
- edge [post] (c1');
-
- \node [transition] (e2') [left=of c2'] {}
- edge [pre,bend right] (w2')
- edge [post] (s1')
- edge [pre] (s2')
- edge [post] (c2');
-
- \node [transition] (l1') [right=of c1'] {}
- edge [pre] (c1')
- edge [pre] (s1')
- edge [post] (s2')
- edge [post,bend right] node[swap] {2} (w1');
-
- \node [transition] (l2') [right=of c2'] {}
- edge [pre] (c2')
- edge [pre] (s1')
- edge [post] (s2')
- edge [post,bend left] node {2} (w2');
- \end{scope}
-
- \begin{scope}[on background layer]
- \node (r1) [fill=black!10,rounded corners,fit=(w1)(w2)(e1)(e2)(l1)(l2)] {};
- \node (r2) [fill=black!10,rounded corners,fit=(w1')(w2')(e1')(e2')(l1')(l2')] {};
- \end{scope}
-
- \draw [shorten >=1mm,->,thick,decorate,decoration={snake,amplitude=.4mm,segment
- length=2mm,pre=moveto,pre length=1mm,post length=2mm}]
- (r1) -- (r2)
- node [above=1mm,midway,text width=3cm,align=center]
- {replacement of the \textcolor{red}{capacity} by \textcolor{red}{two places}};
-
-\end{tikzpicture}
-\end{quote}
-
-
-\subsection{Setting up the Environment}
-
-For the picture Hagen will need to load the \tikzname\ package as did Karl in
-the previous tutorial. However, Hagen will also need to load some additional
-\emph{library packages} that Karl did not need. These library packages contain
-additional definitions like extra arrow tips that are typically not needed in a
-picture and that need to be loaded explicitly.
-
-Hagen will need to load several libraries: The |arrows.meta| library for the
-special arrow tip used in the graphic, the |decorations.pathmorphing| library
-for the ``snaking line'' in the middle, the |backgrounds| library for the two
-rectangular areas that are behind the two main parts of the picture, the |fit|
-library to easily compute the sizes of these rectangles, and the |positioning|
-library for placing nodes relative to other nodes.
-
-
-\subsubsection{Setting up the Environment in \LaTeX}
-
-When using \LaTeX\ use:
-%
-\begin{codeexample}[code only]
-\documentclass{article} % say
-
-\usepackage{tikz}
-\usetikzlibrary{arrows.meta,decorations.pathmorphing,backgrounds,positioning,fit,petri}
-
-\begin{document}
-\begin{tikzpicture}
- \draw (0,0) -- (1,1);
-\end{tikzpicture}
-\end{document}
-\end{codeexample}
-
-
-\subsubsection{Setting up the Environment in Plain \TeX}
-
-When using plain \TeX\ use:
-%
-\begin{codeexample}[code only]
-%% Plain TeX file
-\input tikz.tex
-\usetikzlibrary{arrows.meta,decorations.pathmorphing,backgrounds,positioning,fit,petri}
-\baselineskip=12pt
-\hsize=6.3truein
-\vsize=8.7truein
-\tikzpicture
- \draw (0,0) -- (1,1);
-\endtikzpicture
-\bye
-\end{codeexample}
-
-
-\subsubsection{Setting up the Environment in Con\TeX t}
-
-When using Con\TeX t, use:
-%
-\begin{codeexample}[code only]
-%% ConTeXt file
-\usemodule[tikz]
-\usetikzlibrary[arrows.meta,decorations.pathmorphing,backgrounds,positioning,fit,petri]
-
-\starttext
- \starttikzpicture
- \draw (0,0) -- (1,1);
- \stoptikzpicture
-\stoptext
-\end{codeexample}
-
-
-\subsection{Introduction to Nodes}
-
-In principle, we already know how to create the graphics that Hagen desires
-(except perhaps for the snaked line, we will come to that): We start with big
-light gray rectangle and then add lots of circles and small rectangle, plus
-some arrows.
-
-However, this approach has numerous disadvantages: First, it is hard to change
-anything at a later stage. For example, if we decide to add more places to the
-Petri nets (the circles are called places in Petri net theory), all of the
-coordinates change and we need to recalculate everything. Second, it is hard to
-read the code for the Petri net as it is just a long and complicated list of
-coordinates and drawing commands -- the underlying structure of the Petri net
-is lost.
-
-Fortunately, \tikzname\ offers a powerful mechanism for avoiding the above
-problems: nodes. We already came across nodes in the previous tutorial, where
-we used them to add labels to Karl's graphic. In the present tutorial we will
-see that nodes are much more powerful.
-
-A node is a small part of a picture. When a node is created, you provide a
-position where the node should be drawn and a \emph{shape}. A node of shape
-|circle| will be drawn as a circle, a node of shape |rectangle| as a rectangle,
-and so on. A node may also contain some text, which is why Karl used nodes to
-show text. Finally, a node can get a \emph{name} for later reference.
-
-In Hagen's picture we will use nodes for the places and for the transitions of
-the Petri net (the places are the circles, the transitions are the rectangles).
-Let us start with the upper half of the left Petri net. In this upper half we
-have three places and two transitions. Instead of drawing three circles and two
-rectangles, we use three nodes of shape |circle| and two nodes of shape
-|rectangle|.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \path ( 0,2) node [shape=circle,draw] {}
- ( 0,1) node [shape=circle,draw] {}
- ( 0,0) node [shape=circle,draw] {}
- ( 1,1) node [shape=rectangle,draw] {}
- (-1,1) node [shape=rectangle,draw] {};
-\end{tikzpicture}
-\end{codeexample}
-
-Hagen notes that this does not quite look like the final picture, but it seems
-like a good first step.
-
-Let us have a more detailed look at the code. The whole picture consists of a
-single path. Ignoring the |node| operations, there is not much going on in this
-path: It is just a sequence of coordinates with nothing ``happening'' between
-them. Indeed, even if something were to happen like a line-to or a curve-to,
-the |\path| command would not ``do'' anything with the resulting path. So, all
-the magic must be in the |node| commands.
-
-In the previous tutorial we learned that a |node| will add a piece of text at
-the last coordinate. Thus, each of the five nodes is added at a different
-position. In the above code, this text is empty (because of the empty |{}|).
-So, why do we see anything at all? The answer is the |draw| option for the
-|node| operation: It causes the ``shape around the text'' to be drawn.
-
-So, the code |(0,2) node [shape=circle,draw] {}| means the following: ``In the
-main path, add a move-to to the coordinate |(0,2)|. Then, temporarily suspend
-the construction of the main path while the node is built. This node will be a
-|circle| around an empty text. This circle is to be |draw|n, but not filled or
-otherwise used. Once this whole node is constructed, it is saved until after
-the main path is finished. Then, it is drawn.'' The following
-|(0,1) node [shape=circle,draw] {}| then has the following effect: ``Continue
-the main path with a move-to to |(0,1)|. Then construct a node at this position
-also. This node is also shown after the main path is finished.'' And so on.
-
-
-\subsection{Placing Nodes Using the At Syntax}
-
-Hagen now understands how the |node| operation adds nodes to the path, but it
-seems a bit silly to create a path using the |\path| operation, consisting of
-numerous superfluous move-to operations, only to place nodes. He is pleased to
-learn that there are ways to add nodes in a more sensible manner.
-
-First, the |node| operation allows one to add |at (|\meta{coordinate}|)| in
-order to directly specify where the node should be placed, sidestepping the
-rule that nodes are placed on the last coordinate. Hagen can then write the
-following:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \path node at ( 0,2) [shape=circle,draw] {}
- node at ( 0,1) [shape=circle,draw] {}
- node at ( 0,0) [shape=circle,draw] {}
- node at ( 1,1) [shape=rectangle,draw] {}
- node at (-1,1) [shape=rectangle,draw] {};
-\end{tikzpicture}
-\end{codeexample}
-
-Now Hagen is still left with a single empty path, but at least the path no
-longer contains strange move-to's. It turns out that this can be improved
-further: The |\node| command is an abbreviation for |\path node|, which allows
-Hagen to write:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node at ( 0,2) [circle,draw] {};
- \node at ( 0,1) [circle,draw] {};
- \node at ( 0,0) [circle,draw] {};
- \node at ( 1,1) [rectangle,draw] {};
- \node at (-1,1) [rectangle,draw] {};
-\end{tikzpicture}
-\end{codeexample}
-
-Hagen likes this syntax much better than the previous one. Note that Hagen has
-also omitted the |shape=| since, like |color=|, \tikzname\ allows you to omit
-the |shape=| if there is no confusion.
-
-
-\subsection{Using Styles}
-
-Feeling adventurous, Hagen tries to make the nodes look nicer. In the final
-picture, the circles and rectangle should be filled with different colors,
-resulting in the following code:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[thick]
- \node at ( 0,2) [circle,draw=blue!50,fill=blue!20] {};
- \node at ( 0,1) [circle,draw=blue!50,fill=blue!20] {};
- \node at ( 0,0) [circle,draw=blue!50,fill=blue!20] {};
- \node at ( 1,1) [rectangle,draw=black!50,fill=black!20] {};
- \node at (-1,1) [rectangle,draw=black!50,fill=black!20] {};
-\end{tikzpicture}
-\end{codeexample}
-
-While this looks nicer in the picture, the code starts to get a bit ugly.
-Ideally, we would like our code to transport the message ``there are three
-places and two transitions'' and not so much which filling colors should be
-used.
-
-To solve this problem, Hagen uses styles. He defines a style for places and
-another style for transitions:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- [place/.style={circle,draw=blue!50,fill=blue!20,thick},
- transition/.style={rectangle,draw=black!50,fill=black!20,thick}]
- \node at ( 0,2) [place] {};
- \node at ( 0,1) [place] {};
- \node at ( 0,0) [place] {};
- \node at ( 1,1) [transition] {};
- \node at (-1,1) [transition] {};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Node Size}
-
-Before Hagen starts naming and connecting the nodes, let us first make sure
-that the nodes get their final appearance. They are still too small. Indeed,
-Hagen wonders why they have any size at all, after all, the text is empty. The
-reason is that \tikzname\ automatically adds some space around the text. The
-amount is set using the option |inner sep|. So, to increase the size of the
-nodes, Hagen could write:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- [inner sep=2mm,
- place/.style={circle,draw=blue!50,fill=blue!20,thick},
- transition/.style={rectangle,draw=black!50,fill=black!20,thick}]
- \node at ( 0,2) [place] {};
- \node at ( 0,1) [place] {};
- \node at ( 0,0) [place] {};
- \node at ( 1,1) [transition] {};
- \node at (-1,1) [transition] {};
-\end{tikzpicture}
-\end{codeexample}
-
-However, this is not really the best way to achieve the desired effect. It is
-much better to use the |minimum size| option instead. This option allows Hagen
-to specify a minimum size that the node should have. If the node actually needs
-to be bigger because of a longer text, it will be larger, but if the text is
-empty, then the node will have |minimum size|. This option is also useful to
-ensure that several nodes containing different amounts of text have the same
-size. The options |minimum height| and |minimum width| allow you to specify the
-minimum height and width independently.
-
-So, what Hagen needs to do is to provide |minimum size| for the nodes. To be on
-the safe side, he also sets |inner sep=0pt|. This ensures that the nodes will
-really have size |minimum size| and not, for very small minimum sizes, the
-minimal size necessary to encompass the automatically added space.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- [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}]
- \node at ( 0,2) [place] {};
- \node at ( 0,1) [place] {};
- \node at ( 0,0) [place] {};
- \node at ( 1,1) [transition] {};
- \node at (-1,1) [transition] {};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Naming Nodes}
-
-Hagen's next aim is to connect the nodes using arrows. This seems like a tricky
-business since the arrows should not start in the middle of the nodes, but
-somewhere on the border and Hagen would very much like to avoid computing these
-positions by hand.
-
-Fortunately, \pgfname\ will perform all the necessary calculations for him.
-However, he first has to assign names to the nodes so that he can reference
-them later on.
-
-There are two ways to name a node. The first is to use the |name=| option. The
-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.
-%
-\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 (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,
-parentheses, colons, and some other special characters. However, they can
-contain underscores and hyphens.
-
-The syntax for the |node| operation is quite liberal with respect to the order
-in which node names, the |at| specifier, and the options must come. Indeed, you
-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:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \node[place] (waiting 1) at ( 0,2) {};
- \node[place] (critical 1) at ( 0,1) {};
- \node[place] (semaphore) at ( 0,0) {};
- \node[transition] (leave critical) at ( 1,1) {};
- \node[transition] (enter critical) at (-1,1) {};
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Placing Nodes Using Relative Placement}
-
-Although Hagen still wishes to connect the nodes, he first wishes to address
-another problem again: The placement of the nodes. Although he likes the |at|
-syntax, in this particular case he would prefer placing the nodes ``relative to
-each other''. So, Hagen would like to say that the |critical 1| node should be
-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:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}
- \node[place] (waiting) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical] {};
- \node[transition] (leave critical) [right=of critical] {};
- \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
-placed at the distance |node distance| in the specified direction of the given
-direction. The |node distance| is either the distance between the centers of
-the nodes (when the |on grid| option is set to true) or the distance between
-the borders (when the |on grid| option is set to false, which is the default).
-
-Even though the above code has the same effect as the earlier code, Hagen can
-pass it to his colleagues who will be able to just read and understand it,
-perhaps without even having to see the picture.
-
-
-\subsection{Adding Labels Next to Nodes}
-
-Before we have a look at how Hagen can connect the nodes, let us add the
-capacity ``$s \le 3$'' to the bottom node. For this, two approaches are
-possible:
-%
-\begin{enumerate}
- \item Hagen can just add a new node above the |north| anchor of the
- |semaphore| node.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}
- \node[place] (waiting) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical] {};
- \node[transition] (leave critical) [right=of critical] {};
- \node[transition] (enter critical) [left=of critical] {};
-
- \node [red,above] at (semaphore.north) {$s\le 3$};
-\end{tikzpicture}
-\end{codeexample}
- %
- This is a general approach that will ``always work''.
-
- \item Hagen can use the special |label| option. This option is given to a
- |node| and it causes \emph{another} node to be added next to the node
- where the option is given. Here is the idea: When we construct the
- |semaphore| node, we wish to indicate that we want another node with
- the capacity above it. For this, we use the option
- |label=above:$s\le 3$|. This option is interpreted as follows: We want
- a node above the |semaphore| node and this node should read ``$s \le
- 3$''. Instead of |above| we could also use things like |below left|
- before the colon or a number like |60|.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}
- \node[place] (waiting) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical,
- label=above:$s\le3$] {};
- \node[transition] (leave critical) [right=of critical] {};
- \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.
- %
-\begin{codeexample}[]
-\tikz
- \node [circle,draw,label=60:$60^\circ$,label=below:$-90^\circ$] {my circle};
-\end{codeexample}
- %
- Hagen is not fully satisfied with the |label| option since the label
- is not red. To achieve this, he has two options: First, he can
- redefine the |every label| style. Second, he can add options to the
- label's node. These options are given following the |label=|, so he
- would write |label=[red]above:$s\le3$|. However, this does not quite
- work since \TeX\ thinks that the |]| closes the whole option list of
- the |semaphore| node. So, Hagen has to add braces and writes
- |label={[red]above:$s\le3$}|. Since this looks a bit ugly, Hagen
- decides to redefine the |every label| style.
- %
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}[every label/.style={red}]
- \node[place] (waiting) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical,
- label=above:$s\le3$] {};
- \node[transition] (leave critical) [right=of critical] {};
- \node[transition] (enter critical) [left=of critical] {};
-\end{tikzpicture}
-\end{codeexample}
-\end{enumerate}
-
-
-\subsection{Connecting Nodes}
-
-It is now high time to connect the nodes. Let us start with something simple,
-namely with the straight line from |enter critical| to |critical|. We want this
-line to start at the right side of |enter critical| and to end at the left side
-of |critical|. For this, we can use the \emph{anchors} of the nodes. Every node
-defines a whole bunch of anchors that lie on its border or inside it. For
-example, the |center| anchor is at the center of the node, the |west| anchor is
-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:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}
- \node[place] (waiting) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical] {};
- \node[transition] (leave critical) [right=of critical] {};
- \node[transition] (enter critical) [left=of critical] {};
- \draw [->] (enter critical.east) -- (critical.west);
-\end{tikzpicture}
-\end{codeexample}
-
-Next, let us tackle the curve from |waiting| to |enter critical|. This can be
-specified using curves and controls:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}
- \node[place] (waiting) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical] {};
- \node[transition] (leave critical) [right=of critical] {};
- \node[transition] (enter critical) [left=of critical] {};
- \draw [->] (enter critical.east) -- (critical.west);
- \draw [->] (waiting.west) .. controls +(left:5mm) and +(up:5mm)
- .. (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
-of the graphic rather than showing it.
-
-So, let us start improving the code for the edges. First, Hagen can leave out
-the anchors:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}
- \node[place] (waiting) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical] {};
- \node[transition] (leave critical) [right=of critical] {};
- \node[transition] (enter critical) [left=of critical] {};
- \draw [->] (enter critical) -- (critical);
- \draw [->] (waiting) .. controls +(left:8mm) and +(up:8mm)
- .. (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
-borders? Whenever \tikzname\ encounters a whole node name as a ``coordinate'',
-it tries to ``be smart'' about the anchor that it should choose for this node.
-Depending on what happens next, \tikzname\ will choose an anchor that lies on
-the border of the node on a line to the next coordinate or control point. The
-exact rules are a bit complex, but the chosen point will usually be correct --
-and when it is not, Hagen can still specify the desired anchor by hand.
-
-Hagen would now like to simplify the curve operation somehow. It turns out that
-this can be accomplished using a special path operation: the |to| operation.
-This operation takes many options (you can even define new ones yourself). One
-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:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}
- \node[place] (waiting) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical] {};
- \node[transition] (leave critical) [right=of critical] {};
- \node[transition] (enter critical) [left=of critical] {};
- \draw [->] (enter critical) to (critical);
- \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:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}
- \node[place] (waiting) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical] {};
- \node[transition] (leave critical) [right=of critical] {};
- \node[transition] (enter critical) [left=of critical] {};
- \draw [->] (enter critical) to (critical);
- \draw [->] (waiting) to [bend right=45] (enter critical);
- \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|
-operation, but there is one important difference: Like a node the edge
-generated by the |edge| operation is not part of the main path, but is added
-only later. This may not seem very important, but it has some nice
-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:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{positioning}}]
-\begin{tikzpicture}
- \node[place] (waiting) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical] {};
- \node[transition] (leave critical) [right=of critical] {};
- \node[transition] (enter critical) [left=of critical] {}
- edge [->] (critical)
- edge [<-,bend left=45] (waiting)
- 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.
-
-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:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta,positioning}}]
-% Styles place and transition as before
-\begin{tikzpicture}
- [bend angle=45,
- pre/.style={<-,shorten <=1pt,>={Stealth[round]},semithick},
- post/.style={->,shorten >=1pt,>={Stealth[round]},semithick}]
-
- \node[place] (waiting) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical] {};
-
- \node[transition] (leave critical) [right=of critical] {}
- edge [pre] (critical)
- edge [post,bend right] (waiting)
- edge [pre, bend left] (semaphore);
- \node[transition] (enter critical) [left=of critical] {}
- edge [post] (critical)
- edge [pre, bend left] (waiting)
- edge [post,bend right] (semaphore);
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Adding Labels Next to Lines}
-
-The next thing that Hagen needs to add is the ``$2$'' at the arcs. For this
-Hagen can use \tikzname's automatic node placement: By adding the option
-|auto|, \tikzname\ will position nodes on curves and lines in such a way that
-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$};
- \node (b) at (120:1) {$120^\circ$};
- \node (c) at (240:1) {$240^\circ$};
-
- \draw (a) to node {1} node [swap] {1'} (b)
- (b) to node {2} node [swap] {2'} (c)
- (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
-created by the |to| operation. The |auto| option then causes the node to be
-moved in such a way that it does not lie on the curve, but next to it. In the
-example we provide even two nodes on each |to| operation.
-
-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.
-%
-\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) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical] {};
-
- \node[transition] (leave critical) [right=of critical] {}
- edge [pre] (critical)
- edge [post,bend right] node[auto,swap] {2} (waiting)
- edge [pre, bend left] (semaphore);
- \node[transition] (enter critical) [left=of critical] {}
- edge [post] (critical)
- edge [pre, bend left] (waiting)
- 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}
-
-With the node mechanism Hagen can now easily create the two Petri nets. What he
-is unsure of is how he can create the snaked line between the nets.
-
-For this he can use a \emph{decoration}. To draw the snaked line, Hagen only
-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}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- \draw [->,decorate,decoration=snake] (0,0) -- (2,0);
-\end{tikzpicture}
-\end{codeexample}
-
-Well, that does not look quite right, yet. The problem is that the snake
-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}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- \draw [->,decorate,
- decoration={snake,amplitude=.4mm,segment length=2mm,post length=1mm}]
- (0,0) -- (3,0);
-\end{tikzpicture}
-\end{codeexample}
-
-Now Hagen needs to add the text above the snake. This text is a bit challenging
-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}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- \draw [->,decorate,
- decoration={snake,amplitude=.4mm,segment length=2mm,post length=1mm}]
- (0,0) -- (3,0)
- node [above,align=center,midway]
- {
- replacement of\\
- the \textcolor{red}{capacity}\\
- by \textcolor{red}{two places}
- };
-\end{tikzpicture}
-\end{codeexample}
-
-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}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
-\begin{tikzpicture}
- \draw [->,decorate,
- decoration={snake,amplitude=.4mm,segment length=2mm,post length=1mm}]
- (0,0) -- (3,0)
- node [above,text width=3cm,align=center,midway]
- {
- replacement of the \textcolor{red}{capacity} by
- \textcolor{red}{two places}
- };
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Using Layers: The Background Rectangles}
-
-Hagen still needs to add the background rectangles. These are a bit tricky:
-Hagen would like to draw the rectangles \emph{after} the Petri nets are
-finished. The reason is that only then can he conveniently refer to the
-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 |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
-|{tikzpicture}| environment ends, the layers are put on top of each other,
-starting with the background layer. This causes everything drawn on the
-background layer to be behind the main text.
-
-The next tricky question is, how big should the rectangle be? Naturally, Hagen
-can compute the size ``by hand'' or using some clever observations concerning
-the $x$- and $y$-coordinates of the nodes, but it would be nicer to just have
-\tikzname\ compute a rectangle into which all the nodes ``fit''. For this, the
-|fit| library can be used. It defines the |fit| options, which, when given to a
-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.
-%
-% 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) {};
- \node[place] (critical) [below=of waiting] {};
- \node[place] (semaphore) [below=of critical] {};
-
- \node[transition] (leave critical) [right=of critical] {}
- edge [pre] (critical)
- edge [post,bend right] node[auto,swap] {2} (waiting)
- edge [pre, bend left] (semaphore);
- \node[transition] (enter critical) [left=of critical] {}
- edge [post] (critical)
- edge [pre, bend left] (waiting)
- edge [post,bend right] (semaphore);
-
- \begin{scope}[on background layer]
- \node [fill=black!30,fit=(waiting) (critical) (semaphore)
- (leave critical) (enter critical)] {};
- \end{scope}
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{The Complete Code}
-
-Hagen has now finally put everything together. Only then does he learn that
-there is already a library for drawing Petri nets! It turns out that this
-library mainly provides the same definitions as Hagen did. For example, it
-defines a |place| style in a similar way as Hagen did. Adjusting the code so
-that it uses the library shortens Hagen code a bit, as shown in the following.
-
-First, Hagen needs less style definitions, but he still needs to specify the
-colors of places and transitions.
-%
-\begin{codeexample}[code only]
-\begin{tikzpicture}
- [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},
- every label/.style= {red}]
-\end{codeexample}
-
-Now comes the code for the nets:
-%
-\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$] {};
- \node [place] (c2) [below=of s] {};
- \node [place,tokens=1] (w2) [below=of c2] {};
-
- \node [transition] (e1) [left=of c1] {}
- edge [pre,bend left] (w1)
- edge [post,bend right] (s)
- edge [post] (c1);
- \node [transition] (e2) [left=of c2] {}
- edge [pre,bend right] (w2)
- edge [post,bend left] (s)
- edge [post] (c2);
- \node [transition] (l1) [right=of c1] {}
- edge [pre] (c1)
- edge [pre,bend left] (s)
- edge [post,bend right] node[swap] {2} (w1);
- \node [transition] (l2) [right=of c2] {}
- edge [pre] (c2)
- edge [pre,bend right] (s)
- edge [post,bend left] node {2} (w2);
-\end{codeexample}
-
-\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'] {};
- \node [red place] (s1') [below=of c1',xshift=-5mm]
- [label=left:$s$] {};
- \node [red place,tokens=3] (s2') [below=of c1',xshift=5mm]
- [label=right:$\bar s$] {};
- \node [place] (c2') [below=of s1',xshift=5mm] {};
- \node [place,tokens=1] (w2') [below=of c2'] {};
-
- \node [transition] (e1') [left=of c1'] {}
- edge [pre,bend left] (w1')
- edge [post] (s1')
- edge [pre] (s2')
- edge [post] (c1');
- \node [transition] (e2') [left=of c2'] {}
- edge [pre,bend right] (w2')
- edge [post] (s1')
- edge [pre] (s2')
- edge [post] (c2');
- \node [transition] (l1') [right=of c1'] {}
- edge [pre] (c1')
- edge [pre] (s1')
- edge [post] (s2')
- edge [post,bend right] node[swap] {2} (w1');
- \node [transition] (l2') [right=of c2'] {}
- edge [pre] (c2')
- edge [pre] (s1')
- edge [post] (s2')
- edge [post,bend left] node {2} (w2');
- \end{scope}
-\end{codeexample}
-
-The code for the background and the snake is the following:
-%
-\begin{codeexample}[code only]
- \begin{scope}[on background layer]
- \node (r1) [fill=black!10,rounded corners,fit=(w1)(w2)(e1)(e2)(l1)(l2)] {};
- \node (r2) [fill=black!10,rounded corners,fit=(w1')(w2')(e1')(e2')(l1')(l2')] {};
- \end{scope}
-
- \draw [shorten >=1mm,->,thick,decorate,
- decoration={snake,amplitude=.4mm,segment length=2mm,
- pre=moveto,pre length=1mm,post length=2mm}]
- (r1) -- (r2) node [above=1mm,midway,text width=3cm,align=center]
- {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}
-% -----------------------------------------------------------------------------
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial.tex
deleted file mode 100644
index ae2c47cdc9..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-tutorial.tex
+++ /dev/null
@@ -1,1400 +0,0 @@
-% 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{Tutorial: A Picture for Karl's Students}
-
-This tutorial is intended for new users of \tikzname. It does not give an
-exhaustive account of all the features of \tikzname, just of those that you are
-likely to use right away.
-
-Karl is a math and chemistry high-school teacher. He used to create the
-graphics in his worksheets and exams using \LaTeX's |{picture}| environment.
-While the results were acceptable, creating the graphics often turned out to be
-a lengthy process. Also, there tended to be problems with lines having slightly
-wrong angles and circles also seemed to be hard to get right. Naturally, his
-students could not care less whether the lines had the exact right angles and
-they find Karl's exams too difficult no matter how nicely they were drawn. But
-Karl was never entirely satisfied with the result.
-
-Karl's son, who was even less satisfied with the results (he did not have to
-take the exams, after all), told Karl that he might wish to try out a new
-package for creating graphics. A bit confusingly, this package seems to have
-two names: First, Karl had to download and install a package called \pgfname.
-Then it turns out that inside this package there is another package called
-\tikzname, which is supposed to stand for ``\tikzname\ ist \emph{kein}
-Zeichenprogramm''. Karl finds this all a bit strange and \tikzname\ seems to
-indicate that the package does not do what he needs. However, having used
-\textsc{gnu} software for quite some time and ``\textsc{gnu} not being Unix'',
-there seems to be hope yet. His son assures him that \tikzname's name is
-intended to warn people that \tikzname\ is not a program that you can use to
-draw graphics with your mouse or tablet. Rather, it is more like a ``graphics
-language''.
-
-
-\subsection{Problem Statement}
-
-Karl wants to put a graphic on the next worksheet for his students. He is
-currently teaching his students about sine and cosine. What he would like to
-have is something that looks like this (ideally):
-%
-\noindent
-\begin{tikzpicture}
- [scale=3,line cap=round,
- % Styles
- axes/.style=,
- important line/.style={very thick},
- information text/.style={rounded corners,fill=red!10,inner sep=1ex}]
-
- % Local definitions
- \def\costhirty{0.8660256}
-
- % Colors
- \colorlet{anglecolor}{green!50!black}
- \colorlet{sincolor}{red}
- \colorlet{tancolor}{orange!80!black}
- \colorlet{coscolor}{blue}
-
- % The graphic
- \draw[help lines,step=0.5cm] (-1.4,-1.4) grid (1.4,1.4);
-
- \draw (0,0) circle [radius=1cm];
-
- \begin{scope}[axes]
- \draw[->] (-1.5,0) -- (1.5,0) node[right] {$x$};
- \draw[->] (0,-1.5) -- (0,1.5) node[above] {$y$};
-
- \foreach \x/\xtext in {-1, -.5/-\frac{1}{2}, 1}
- \draw[xshift=\x cm] (0pt,1pt) -- (0pt,-1pt) node[below,fill=white] {$\xtext$};
-
- \foreach \y/\ytext in {-1, -.5/-\frac{1}{2}, .5/\frac{1}{2}, 1}
- \draw[yshift=\y cm] (1pt,0pt) -- (-1pt,0pt) node[left,fill=white] {$\ytext$};
- \end{scope}
-
- \filldraw[fill=green!20,draw=anglecolor] (0,0) -- (3mm,0pt) arc(0:30:3mm);
- \draw (15:2mm) node[anglecolor] {$\alpha$};
-
- \draw[important line,sincolor]
- (30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} +(0,-.5);
-
- \draw[important line,coscolor]
- (0,0) -- node[below=2pt,fill=white] {$\cos \alpha$} (\costhirty,0);
-
- \draw[important line,tancolor] (1,0) --
- node [right=1pt,fill=white]
- {
- $\displaystyle \tan \alpha \color{black}=
- \frac{{\color{sincolor}\sin \alpha}}{\color{coscolor}\cos \alpha}$
- } (intersection of 0,0--30:1cm and 1,0--1,1) coordinate (t);
-
- \draw (0,0) -- (t);
-
- \draw[xshift=1.85cm] node [right,text width=6cm,information text]
- {
- The {\color{anglecolor} angle $\alpha$} is $30^\circ$ in the
- example ($\pi/6$ in radians). The {\color{sincolor}sine of
- $\alpha$}, which is the height of the red line, is
- \[
- {\color{sincolor} \sin \alpha} = 1/2.
- \]
- By the Theorem of Pythagoras we have ${\color{coscolor}\cos^2 \alpha} +
- {\color{sincolor}\sin^2\alpha} =1$. Thus the length of the blue
- line, which is the {\color{coscolor}cosine of $\alpha$}, must be
- \[
- {\color{coscolor}\cos\alpha} = \sqrt{1 - 1/4} = \textstyle
- \frac{1}{2} \sqrt 3.
- \]%
- This shows that {\color{tancolor}$\tan \alpha$}, which is the
- height of the orange line, is
- \[
- {\color{tancolor}\tan\alpha} = \frac{{\color{sincolor}\sin
- \alpha}}{\color{coscolor}\cos \alpha} = 1/\sqrt 3.
- \]%
- };
-\end{tikzpicture}
-
-
-\subsection{Setting up the Environment}
-
-In \tikzname, to draw a picture, at the start of the picture you need to tell
-\TeX\ or \LaTeX\ that you want to start a picture. In \LaTeX\ this is done
-using the environment |{tikzpicture}|, in plain \TeX\ you just use
-|\tikzpicture| to start the picture and |\endtikzpicture| to end it.
-
-
-\subsubsection{Setting up the Environment in \LaTeX}
-
-Karl, being a \LaTeX\ user, thus sets up his file as follows:
-%
-\begin{codeexample}[code only]
-\documentclass{article} % say
-\usepackage{tikz}
-\begin{document}
-We are working on
-\begin{tikzpicture}
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
-\end{tikzpicture}.
-\end{document}
-\end{codeexample}
-
-When executed, that is, run via |pdflatex| or via |latex| followed by |dvips|,
-the resulting will contain something that looks like this:
-%
-\begin{codeexample}[width=7cm]
-We are working on
-\begin{tikzpicture}
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
-\end{tikzpicture}.
-\end{codeexample}
-
-Admittedly, not quite the whole picture, yet, but we do have the axes
-established. Well, not quite, but we have the lines that make up the axes
-drawn. Karl suddenly has a sinking feeling that the picture is still some way
-off.
-
-Let's have a more detailed look at the code. First, the package |tikz| is
-loaded. This package is a so-called ``frontend'' to the basic \pgfname\ system.
-The basic layer, which is also described in this manual, is somewhat more,
-well, basic and thus harder to use. The frontend makes things easier by
-providing a simpler syntax.
-
-Inside the environment there are two |\draw| commands. They mean: ``The path,
-which is specified following the command up to the semicolon, should be
-drawn.'' The first path is specified as |(-1.5,0) -- (0,1.5)|, which means ``a
-straight line from the point at position $(-1.5,0)$ to the point at position
-$(0,1.5)$''. Here, the positions are specified within a special coordinate
-system in which, initially, one unit is 1cm.
-
-Karl is quite pleased to note that the environment automatically reserves
-enough space to encompass the picture.
-
-
-\subsubsection{Setting up the Environment in Plain \TeX}
-
-Karl's wife Gerda, who also happens to be a math teacher, is not a \LaTeX\
-user, but uses plain \TeX\ since she prefers to do things ``the old way''. She
-can also use \tikzname. Instead of |\usepackage{tikz}| she has to write
-|\input tikz.tex| and instead of |\begin{tikzpicture}| she writes
-|\tikzpicture| and instead of |\end{tikzpicture}| she writes |\endtikzpicture|.
-
-Thus, she would use:
-%
-\begin{codeexample}[code only]
-%% Plain TeX file
-\input tikz.tex
-\baselineskip=12pt
-\hsize=6.3truein
-\vsize=8.7truein
-We are working on
-\tikzpicture
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
-\endtikzpicture.
-\bye
-\end{codeexample}
-
-Gerda can typeset this file using either |pdftex| or |tex| together with
-|dvips|. \tikzname\ will automatically discern which driver she is using. If
-she wishes to use |dvipdfm| together with |tex|, she either needs to modify the
-file |pgf.cfg| or can write |\def\pgfsysdriver{pgfsys-dvipdfm.def}| somewhere
-\emph{before} she inputs |tikz.tex| or |pgf.tex|.
-
-
-\subsubsection{Setting up the Environment in Con\TeX t}
-
-Karl's uncle Hans uses Con\TeX t. Like Gerda, Hans can also use \tikzname.
-Instead of |\usepackage{tikz}| he says |\usemodule[tikz]|. Instead of
-|\begin{tikzpicture}| he writes |\starttikzpicture| and instead of
-|\end{tikzpicture}| he writes |\stoptikzpicture|.
-
-His version of the example looks like this:
-%
-\begin{codeexample}[code only]
-%% ConTeXt file
-\usemodule[tikz]
-
-\starttext
- We are working on
- \starttikzpicture
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \stoptikzpicture.
-\stoptext
-\end{codeexample}
-
-Hans will now typeset this file in the usual way using |texexec| or |context|.
-
-
-\subsection{Straight Path Construction}
-
-The basic building block of all pictures in \tikzname\ is the path. A
-\emph{path} is a series of straight lines and curves that are connected (that
-is not the whole picture, but let us ignore the complications for the moment).
-You start a path by specifying the coordinates of the start position as a point
-in round brackets, as in |(0,0)|. This is followed by a series of ``path
-extension operations''. The simplest is |--|, which we used already. It must be
-followed by another coordinate and it extends the path in a straight line to
-this new position. For example, if we were to turn the two paths of the axes
-into one path, the following would result:
-%
-\begin{codeexample}[]
-\tikz \draw (-1.5,0) -- (1.5,0) -- (0,-1.5) -- (0,1.5);
-\end{codeexample}
-
-Karl is a bit confused by the fact that there is no |{tikzpicture}|
-environment, here. Instead, the little command |\tikz| is used. This command
-either takes one argument (starting with an opening brace as in
-|\tikz{\draw (0,0) -- (1.5,0)}|, which yields \tikz{\draw (0,0) --(1.5,0);}) or
-collects everything up to the next semicolon and puts it inside a
-|{tikzpicture}| environment. As a rule of thumb, all \tikzname\ graphic drawing
-commands must occur as an argument of |\tikz| or inside a |{tikzpicture}|
-environment. Fortunately, the command |\draw| will only be defined inside this
-environment, so there is little chance that you will accidentally do something
-wrong here.
-
-
-\subsection{Curved Path Construction}
-
-The next thing Karl wants to do is to draw the circle. For this, straight lines
-obviously will not do. Instead, we need some way to draw curves. For this,
-\tikzname\ provides a special syntax. One or two ``control points'' are needed.
-The math behind them is not quite trivial, but here is the basic idea: Suppose
-you are at point $x$ and the first control point is $y$. Then the curve will
-start ``going in the direction of~$y$ at~$x$'', that is, the tangent of the
-curve at $x$ will point toward~$y$. Next, suppose the curve should end at $z$
-and the second support point is $w$. Then the curve will, indeed, end at $z$
-and the tangent of the curve at point $z$ will go through $w$.
-
-Here is an example (the control points have been added for clarity):
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \filldraw [gray] (0,0) circle [radius=2pt]
- (1,1) circle [radius=2pt]
- (2,1) circle [radius=2pt]
- (2,0) circle [radius=2pt];
- \draw (0,0) .. controls (1,1) and (2,1) .. (2,0);
-\end{tikzpicture}
-\end{codeexample}
-
-The general syntax for extending a path in a ``curved'' way is |.. controls|
-\meta{first control point} |and| \meta{second control point} |..|
-\meta{end point}. You can leave out the |and| \meta{second control point},
-which causes the first one to be used twice.
-
-So, Karl can now add the first half circle to the picture:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (-1,0) .. controls (-1,0.555) and (-0.555,1) .. (0,1)
- .. controls (0.555,1) and (1,0.555) .. (1,0);
-\end{tikzpicture}
-\end{codeexample}
-
-Karl is happy with the result, but finds specifying circles in this way to be
-extremely awkward. Fortunately, there is a much simpler way.
-
-
-\subsection{Circle Path Construction}
-
-In order to draw a circle, the path construction operation |circle| can be
-used. This operation is followed by a radius in brackets as in the following
-example: (Note that the previous position is used as the \emph{center} of the
-circle.)
-%
-\begin{codeexample}[]
-\tikz \draw (0,0) circle [radius=10pt];
-\end{codeexample}
-
-You can also append an ellipse to the path using the |ellipse| operation.
-Instead of a single radius you can specify two of them:
-%
-\begin{codeexample}[]
-\tikz \draw (0,0) ellipse [x radius=20pt, y radius=10pt];
-\end{codeexample}
-
-To draw an ellipse whose axes are not horizontal and vertical, but point in an
-arbitrary direction (a ``turned ellipse'' like \tikz \draw[rotate=30] (0,0)
-ellipse [x radius=6pt, y radius=3pt];) you can use transformations, which are
-explained later. The code for the little ellipse is
-|\tikz \draw[rotate=30] (0,0) ellipse [x radius=6pt, y radius=3pt];|, by the
-way.
-
-So, returning to Karl's problem, he can write
-|\draw (0,0) circle [radius=1cm];| to draw the circle:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
-\end{tikzpicture}
-\end{codeexample}
-
-At this point, Karl is a bit alarmed that the circle is so small when he wants
-the final picture to be much bigger. He is pleased to learn that \tikzname\ has
-powerful transformation options and scaling everything by a factor of three is
-very easy. But let us leave the size as it is for the moment to save some
-space.
-
-
-\subsection{Rectangle Path Construction}
-
-The next things we would like to have is the grid in the background. There are
-several ways to produce it. For example, one might draw lots of rectangles.
-Since rectangles are so common, there is a special syntax for them: To add a
-rectangle to the current path, use the |rectangle| path construction operation.
-This operation should be followed by another coordinate and will append a
-rectangle to the path such that the previous coordinate and the next
-coordinates are corners of the rectangle. So, let us add two rectangles to the
-picture:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \draw (0,0) rectangle (0.5,0.5);
- \draw (-0.5,-0.5) rectangle (-1,-1);
-\end{tikzpicture}
-\end{codeexample}
-
-While this may be nice in other situations, this is not really leading anywhere
-with Karl's problem: First, we would need an awful lot of these rectangles and
-then there is the border that is not ``closed''.
-
-So, Karl is about to resort to simply drawing four vertical and four horizontal
-lines using the nice |\draw| command, when he learns that there is a |grid|
-path construction operation.
-
-
-\subsection{Grid Path Construction}
-
-The |grid| path operation adds a grid to the current path. It will add lines
-making up a grid that fills the rectangle whose one corner is the current point
-and whose other corner is the point following the |grid| operation. For
-example, the code |\tikz \draw[step=2pt] (0,0) grid (10pt,10pt);| produces
-\tikz \draw[step=2pt] (0,0) grid (10pt,10pt);. Note how the optional argument
-for |\draw| can be used to specify a grid width (there are also |xstep| and
-|ystep| to define the steppings independently). As Karl will learn soon, there
-are \emph{lots} of things that can be influenced using such options.
-
-For Karl, the following code could be used:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \draw[step=.5cm] (-1.4,-1.4) grid (1.4,1.4);
-\end{tikzpicture}
-\end{codeexample}
-
-Having another look at the desired picture, Karl notices that it would be nice
-for the grid to be more subdued. (His son told him that grids tend to be
-distracting if they are not subdued.) To subdue the grid, Karl adds two more
-options to the |\draw| command that draws the grid. First, he uses the color
-|gray| for the grid lines. Second, he reduces the line width to |very thin|.
-Finally, he swaps the ordering of the commands so that the grid is drawn first
-and everything else on top.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Adding a Touch of Style}
-
-Instead of the options |gray,very thin| Karl could also have said |help lines|.
-\emph{Styles} are predefined sets of options that can be used to organize how a
-graphic is drawn. By saying |help lines| you say ``use the style that I (or
-someone else) has set for drawing help lines''. If Karl decides, at some later
-point, that grids should be drawn, say, using the color |blue!50| instead of
-|gray|, he could provide the following option somewhere:
-%
-\begin{codeexample}[code only]
-help lines/.style={color=blue!50,very thin}
-\end{codeexample}
-%
-The effect of this ``style setter'' is that in the current scope or environment
-the |help lines| option has the same effect as |color=blue!50,very thin|.
-
-Using styles makes your graphics code more flexible. You can change the way
-things look easily in a consistent manner. Normally, styles are defined at the
-beginning of a picture. However, you may sometimes wish to define a style
-globally, so that all pictures of your document can use this style. Then you
-can easily change the way all graphics look by changing this one style. In this
-situation you can use the |\tikzset| command at the beginning of the document
-as in
-%
-\begin{codeexample}[code only]
-\tikzset{help lines/.style=very thin}
-\end{codeexample}
-
-To build a hierarchy of styles you can have one style use another. So in order
-to define a style |Karl's grid| that is based on the |grid| style Karl could
-say
-%
-\begin{codeexample}[code only]
-\tikzset{Karl's grid/.style={help lines,color=blue!50}}
-...
-\draw[Karl's grid] (0,0) grid (5,5);
-\end{codeexample}
-
-Styles are made even more powerful by parametrization. This means that, like
-other options, styles can also be used with a parameter. For instance, Karl
-could parameterize his grid so that, by default, it is blue, but he could also
-use another color.
-%
-\begin{codeexample}[code only]
-\begin{tikzpicture}
- [Karl's grid/.style ={help lines,color=#1!50},
- Karl's grid/.default=blue]
-
- \draw[Karl's grid] (0,0) grid (1.5,2);
- \draw[Karl's grid=red] (2,0) grid (3.5,2);
-\end{tikzpicture}
-\end{codeexample}
-
- In this example, the definition of the style |Karl's grid| is given as an
- optional argument to the |{tikzpicture}| environment. Additional styles for other
- elements would follow after a comma. With many styles in effect, the optional
- argument of the environment may easily happen to be longer than the actual
- contents.
-
-\subsection{Drawing Options}
-
-Karl wonders what other options there are that influence how a path is drawn.
-He saw already that the |color=|\meta{color} option can be used to set the
-line's color. The option |draw=|\meta{color} does nearly the same, only it sets
-the color for the lines only and a different color can be used for filling
-(Karl will need this when he fills the arc for the angle).
-
-He saw that the style |very thin| yields very thin lines. Karl is not really
-surprised by this and neither is he surprised to learn that |thin| yields thin
-lines, |thick| yields thick lines, |very thick| yields very thick lines,
-|ultra thick| yields really, really thick lines and |ultra thin| yields lines
-that are so thin that low-resolution printers and displays will have trouble
-showing them. He wonders what gives lines of ``normal'' thickness. It turns out
-that |thin| is the correct choice, since it gives the same thickness as \TeX's
-|\hrule| command. Nevertheless, Karl would like to know whether there is
-anything ``in the middle'' between |thin| and |thick|. There is: |semithick|.
-
-Another useful thing one can do with lines is to dash or dot them. For this,
-the two styles |dashed| and |dotted| can be used, yielding \tikz[baseline]
-\draw[dashed] (0,.5ex) -- ++(2em,0pt); and \tikz[baseline] \draw[dotted]
-(0,.5ex) -- ++(2em,0pt);. Both options also exist in a loose and a dense
-version, called |loosely dashed|, |densely dashed|, |loosely dotted|, and
-|densely dotted|. If he really, really needs to, Karl can also define much
-more complex dashing patterns with the |dash pattern| option, but his son
-insists that dashing is to be used with utmost care and mostly distracts.
-Karl's son claims that complicated dashing patterns are evil. Karl's students
-do not care about dashing patterns.
-
-
-\subsection{Arc Path Construction}
-
-Our next obstacle is to draw the arc for the angle. For this, the |arc| path
-construction operation is useful, which draws part of a circle or ellipse. This
-|arc| operation is followed by options in brackets that specify the arc. An
-example would be \texttt{arc[start angle=10, end angle=80, radius=10pt]}, which
-means exactly what it says. Karl obviously needs an arc from $0^\circ$ to
-$30^\circ$. The radius should be something relatively small, perhaps around one
-third of the circle's radius. When one uses the arc path construction
-operation, the specified arc will be added with its starting point at the
-current position. So, we first have to ``get there''.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \draw (3mm,0mm) arc [start angle=0, end angle=30, radius=3mm];
-\end{tikzpicture}
-\end{codeexample}
-
-Karl thinks this is really a bit small and he cannot continue unless he learns
-how to do scaling. For this, he can add the |[scale=3]| option. He could add
-this option to each |\draw| command, but that would be awkward. Instead, he
-adds it to the whole environment, which causes this option to apply to
-everything within.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=3]
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \draw (3mm,0mm) arc [start angle=0, end angle=30, radius=3mm];
-\end{tikzpicture}
-\end{codeexample}
-
-As for circles, you can specify ``two'' radii in order to get an elliptical
-arc.
-%
-\begin{codeexample}[]
- \tikz \draw (0,0)
- arc [start angle=0, end angle=315,
- x radius=1.75cm, y radius=1cm];
-\end{codeexample}
-
-
-\subsection{Clipping a Path}
-
-In order to save space in this manual, it would be nice to clip Karl's graphics
-a bit so that we can focus on the ``interesting'' parts. Clipping is pretty
-easy in \tikzname. You can use the |\clip| command to clip all subsequent
-drawing. It works like |\draw|, only it does not draw anything, but uses the
-given path to clip everything subsequently.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=3]
- \clip (-0.1,-0.2) rectangle (1.1,0.75);
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \draw (3mm,0mm) arc [start angle=0, end angle=30, radius=3mm];
-\end{tikzpicture}
-\end{codeexample}
-
-You can also do both at the same time: Draw \emph{and} clip a path. For this,
-use the |\draw| command and add the |clip| option. (This is not the whole
-picture: You can also use the |\clip| command and add the |draw| option. Well,
-that is also not the whole picture: In reality, |\draw| is just a shorthand for
-|\path[draw]| and |\clip| is a shorthand for |\path[clip]| and you could also
-say |\path[draw,clip]|.) Here is an example:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=3]
- \clip[draw] (0.5,0.5) circle (.6cm);
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \draw (3mm,0mm) arc [start angle=0, end angle=30, radius=3mm];
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Parabola and Sine Path Construction}
-
-Although Karl does not need them for his picture, he is pleased to learn that
-there are |parabola| and |sin| and |cos| path operations for adding parabolas
-and sine and cosine curves to the current path. For the |parabola| operation,
-the current point will lie on the parabola as well as the point given after the
-parabola operation. Consider the following example:
-%
-\begin{codeexample}[]
-\tikz \draw (0,0) rectangle (1,1) (0,0) parabola (1,1);
-\end{codeexample}
-
-It is also possible to place the bend somewhere else:
-%
-\begin{codeexample}[]
-\tikz \draw[x=1pt,y=1pt] (0,0) parabola bend (4,16) (6,12);
-\end{codeexample}
-
-The operations |sin| and |cos| add a sine or cosine curve in the interval
-$[0,\pi/2]$ such that the previous current point is at the start of the curve
-and the curve ends at the given end point. Here are two examples:
-%
-\begin{codeexample}[]
-A sine \tikz \draw[x=1ex,y=1ex] (0,0) sin (1.57,1); curve.
-\end{codeexample}
-
-\begin{codeexample}[]
-\tikz \draw[x=1.57ex,y=1ex] (0,0) sin (1,1) cos (2,0) sin (3,-1) cos (4,0)
- (0,1) cos (1,0) sin (2,-1) cos (3,0) sin (4,1);
-\end{codeexample}
-
-
-\subsection{Filling and Drawing}
-
-Returning to the picture, Karl now wants the angle to be ``filled'' with a very
-light green. For this he uses |\fill| instead of |\draw|. Here is what Karl
-does:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=3]
- \clip (-0.1,-0.2) rectangle (1.1,0.75);
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \fill[green!20!white] (0,0) -- (3mm,0mm)
- arc [start angle=0, end angle=30, radius=3mm] -- (0,0);
-\end{tikzpicture}
-\end{codeexample}
-
-The color |green!20!white| means 20\% green and 80\% white mixed together. Such
-color expression are possible since \tikzname\ uses Uwe Kern's |xcolor|
-package, see the documentation of that package for details on color
-expressions.
-
-What would have happened, if Karl had not ``closed'' the path using |--(0,0)|
-at the end? In this case, the path is closed automatically, so this could have
-been omitted. Indeed, it would even have been better to write the following,
-instead:
-%
-\begin{codeexample}[code only]
- \fill[green!20!white] (0,0) -- (3mm,0mm)
- arc [start angle=0, end angle=30, radius=3mm] -- cycle;
-\end{codeexample}
-%
-The |--cycle| causes the current path to be closed (actually the current part
-of the current path) by smoothly joining the first and last point. To
-appreciate the difference, consider the following example:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[line width=5pt]
- \draw (0,0) -- (1,0) -- (1,1) -- (0,0);
- \draw (2,0) -- (3,0) -- (3,1) -- cycle;
- \useasboundingbox (0,1.5); % make bounding box higher
-\end{tikzpicture}
-\end{codeexample}
-
-You can also fill and draw a path at the same time using the |\filldraw|
-command. This will first draw the path, then fill it. This may not seem too
-useful, but you can specify different colors to be used for filling and for
-stroking. These are specified as optional arguments like this:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=3]
- \clip (-0.1,-0.2) rectangle (1.1,0.75);
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \filldraw[fill=green!20!white, draw=green!50!black] (0,0) -- (3mm,0mm)
- arc [start angle=0, end angle=30, radius=3mm] -- cycle;
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Shading}
-
-Karl briefly considers the possibility of making the angle ``more fancy'' by
-\emph{shading} it. Instead of filling the area with a uniform color, a smooth
-transition between different colors is used. For this, |\shade| and
-|\shadedraw|, for shading and drawing at the same time, can be used:
-%
-\begin{codeexample}[]
- \tikz \shade (0,0) rectangle (2,1) (3,0.5) circle (.5cm);
-\end{codeexample}
-%
-The default shading is a smooth transition from gray to white. To specify
-different colors, you can use options:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[rounded corners,ultra thick]
- \shade[top color=yellow,bottom color=black] (0,0) rectangle +(2,1);
- \shade[left color=yellow,right color=black] (3,0) rectangle +(2,1);
- \shadedraw[inner color=yellow,outer color=black,draw=yellow] (6,0) rectangle +(2,1);
- \shade[ball color=green] (9,.5) circle (.5cm);
-\end{tikzpicture}
-\end{codeexample}
-
-For Karl, the following might be appropriate:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=3]
- \clip (-0.1,-0.2) rectangle (1.1,0.75);
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \shadedraw[left color=gray,right color=green, draw=green!50!black]
- (0,0) -- (3mm,0mm)
- arc [start angle=0, end angle=30, radius=3mm] -- cycle;
-\end{tikzpicture}
-\end{codeexample}
-
-However, he wisely decides that shadings usually only distract without adding
-anything to the picture.
-
-
-\subsection{Specifying Coordinates}
-
-Karl now wants to add the sine and cosine lines. He knows already that he can
-use the |color=| option to set the lines' colors. So, what is the best way to
-specify the coordinates?
-
-There are different ways of specifying coordinates. The easiest way is to say
-something like |(10pt,2cm)|. This means 10pt in $x$-direction and 2cm in
-$y$-directions. Alternatively, you can also leave out the units as in |(1,2)|,
-which means ``one times the current $x$-vector plus twice the current
-$y$-vector''. These vectors default to 1cm in the $x$-direction and 1cm in the
-$y$-direction, respectively.
-
-In order to specify points in polar coordinates, use the notation |(30:1cm)|,
-which means 1cm in direction 30 degree. This is obviously quite useful to ``get
-to the point $(\cos 30^\circ,\sin 30^\circ)$ on the circle''.
-
-You can add a single |+| sign in front of a coordinate or two of them as in
-|+(0cm,1cm)| or |++(2cm,0cm)|. Such coordinates are interpreted differently:
-The first form means ``1cm upwards from the previous specified position'' and
-the second means ``2cm to the right of the previous specified position, making
-this the new specified position''. For example, we can draw the sine line as
-follows:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=3]
- \clip (-0.1,-0.2) rectangle (1.1,0.75);
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm)
- arc [start angle=0, end angle=30, radius=3mm] -- cycle;
- \draw[red,very thick] (30:1cm) -- +(0,-0.5);
-\end{tikzpicture}
-\end{codeexample}
-
-Karl used the fact $\sin 30^\circ = 1/2$. However, he very much doubts that his
-students know this, so it would be nice to have a way of specifying ``the point
-straight down from |(30:1cm)| that lies on the $x$-axis''. This is, indeed,
-possible using a special syntax: Karl can write \verb!(30:1cm |- 0,0)!. In
-general, the meaning of |(|\meta{p}\verb! |- !\meta{q}|)| is ``the intersection
-of a vertical line through $p$ and a horizontal line through $q$''.
-
-Next, let us draw the cosine line. One way would be to say
-\verb!(30:1cm |- 0,0) -- (0,0)!. Another way is the following: we ``continue''
-from where the sine ends:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=3]
- \clip (-0.1,-0.2) rectangle (1.1,0.75);
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \draw (-1.5,0) -- (1.5,0);
- \draw (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm)
- arc [start angle=0, end angle=30, radius=3mm] -- cycle;
- \draw[red,very thick] (30:1cm) -- +(0,-0.5);
- \draw[blue,very thick] (30:1cm) ++(0,-0.5) -- (0,0);
-\end{tikzpicture}
-\end{codeexample}
-
-Note that there is no |--| between |(30:1cm)| and |++(0,-0.5)|. In detail, this
-path is interpreted as follows: ``First, the |(30:1cm)| tells me to move my pen
-to $(\cos 30^\circ,1/2)$. Next, there comes another coordinate specification,
-so I move my pen there without drawing anything. This new point is half a unit
-down from the last position, thus it is at $(\cos 30^\circ,0)$. Finally, I move
-the pen to the origin, but this time drawing something (because of the |--|).''
-
-To appreciate the difference between |+| and |++| consider the following
-example:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \def\rectanglepath{-- ++(1cm,0cm) -- ++(0cm,1cm) -- ++(-1cm,0cm) -- cycle}
- \draw (0,0) \rectanglepath;
- \draw (1.5,0) \rectanglepath;
-\end{tikzpicture}
-\end{codeexample}
-
-By comparison, when using a single |+|, the coordinates are different:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \def\rectanglepath{-- +(1cm,0cm) -- +(1cm,1cm) -- +(0cm,1cm) -- cycle}
- \draw (0,0) \rectanglepath;
- \draw (1.5,0) \rectanglepath;
-\end{tikzpicture}
-\end{codeexample}
-
-
-Naturally, all of this could have been written more clearly and more
-economically like this (either with a single or a double |+|):
-%
-\begin{codeexample}[]
-\tikz \draw (0,0) rectangle +(1,1) (1.5,0) rectangle +(1,1);
-\end{codeexample}
-
-
-\subsection{Intersecting Paths}
-
-Karl is left with the line for $\tan \alpha$, which seems difficult to specify
-using transformations and polar coordinates. The first -- and easiest -- thing
-he can do is so simply use the coordinate |(1,{tan(30)})| since \tikzname's
-math engine knows how to compute things like |tan(30)|. Note the added braces
-since, otherwise, \tikzname's parser would think that the first closing
-parenthesis ends the coordinate (in general, you need to add braces around
-components of coordinates when these components contain parentheses).
-
-Karl can, however, also use a more elaborate, but also more ``geometric'' way
-of computing the length of the orange line: He can specify intersections of
-paths as coordinates. The line for $\tan \alpha$ starts at $(1,0)$ and goes
-upward to a point that is at the intersection of a line going ``up'' and a line
-going from the origin through |(30:1cm)|. Such computations are made available
-by the |intersections| library.
-
-What Karl must do is to create two ``invisible'' paths that intersect at the
-position of interest. Creating paths that are not otherwise seen can be done
-using the |\path| command without any options like |draw| or |fill|. Then, Karl
-can add the |name path| option to the path for later reference. Once the paths
-have been constructed, Karl can use the |name intersections| to assign names to
-the coordinate for later reference.
-%
-\begin{codeexample}[code only]
-\path [name path=upward line] (1,0) -- (1,1);
-\path [name path=sloped line] (0,0) -- (30:1.5cm); % a bit longer, so that there is an intersection
-
-% (add `\usetikzlibrary{intersections}' after loading tikz in the preamble)
-\draw [name intersections={of=upward line and sloped line, by=x}]
- [very thick,orange] (1,0) -- (x);
-\end{codeexample}
-
-
-\subsection{Adding Arrow Tips}
-
-Karl now wants to add the little arrow tips at the end of the axes. He has
-noticed that in many plots, even in scientific journals, these arrow tips seem
-to be missing, presumably because the generating programs cannot produce them.
-Karl thinks arrow tips belong at the end of axes. His son agrees. His students
-do not care about arrow tips.
-
-It turns out that adding arrow tips is pretty easy: Karl adds the option |->|
-to the drawing commands for the axes:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
-\begin{tikzpicture}[scale=3]
- \clip (-0.1,-0.2) rectangle (1.1,1.51);
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \draw[->] (-1.5,0) -- (1.5,0);
- \draw[->] (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
- \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm)
- arc [start angle=0, end angle=30, radius=3mm] -- cycle;
- \draw[red,very thick] (30:1cm) -- +(0,-0.5);
- \draw[blue,very thick] (30:1cm) ++(0,-0.5) -- (0,0);
-
- \path [name path=upward line] (1,0) -- (1,1);
- \path [name path=sloped line] (0,0) -- (30:1.5cm);
- \draw [name intersections={of=upward line and sloped line, by=x}]
- [very thick,orange] (1,0) -- (x);
-\end{tikzpicture}
-\end{codeexample}
-
-If Karl had used the option |<-| instead of |->|, arrow tips would have been
-put at the beginning of the path. The option |<->| puts arrow tips at both ends
-of the path.
-
-There are certain restrictions to the kind of paths to which arrow tips can be
-added. As a rule of thumb, you can add arrow tips only to a single open
-``line''. For example, you cannot add tips to, say, a rectangle or a circle.
-However, you can add arrow tips to curved paths and to paths that have several
-segments, as in the following examples:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw [<->] (0,0) arc [start angle=180, end angle=30, radius=10pt];
- \draw [<->] (1,0) -- (1.5cm,10pt) -- (2cm,0pt) -- (2.5cm,10pt);
-\end{tikzpicture}
-\end{codeexample}
-
-Karl has a more detailed look at the arrow that \tikzname\ puts at the end. It
-looks like this when he zooms it: \tikz[baseline] \draw[->,line width=1pt]
-(0pt,.5ex) -- ++(10pt,0pt);. The shape seems vaguely familiar and, indeed, this
-is exactly the end of \TeX's standard arrow used in something like $f\colon A
-\to B$.
-
-Karl likes the arrow, especially since it is not ``as thick'' as the arrows
-offered by many other packages. However, he expects that, sometimes, he might
-need to use some other kinds of arrow. To do so, Karl can say |>=|\meta{kind of
-end arrow tip}, where \meta{kind of end arrow tip} is a special arrow tip
-specification. For example, if Karl says |>=Stealth|, then he tells \tikzname\
-that he would like ``stealth-fighter-like'' arrow tips:
-\todosp{remaining instance of bug \#473}
-%
-\begin{codeexample}[preamble={\usetikzlibrary{arrows.meta}}]
-\begin{tikzpicture}[>=Stealth]
- \draw [->] (0,0) arc [start angle=180, end angle=30, radius=10pt];
- \draw [<<-,very thick] (1,0) -- (1.5cm,10pt) -- (2cm,0pt) -- (2.5cm,10pt);
-\end{tikzpicture}
-\end{codeexample}
-
-Karl wonders whether such a military name for the arrow type is really
-necessary. He is not really mollified when his son tells him that Microsoft's
-PowerPoint uses the same name. He decides to have his students discuss this at
-some point.
-
-In addition to |Stealth| there are several other predefined kinds of arrow tips
-Karl can choose from, see Section~\ref{section-arrows}. Furthermore, he can
-define arrows types himself, if he needs new ones.
-
-
-\subsection{Scoping}
-
-Karl saw already that there are numerous graphic options that affect how paths
-are rendered. Often, he would like to apply certain options to a whole set of
-graphic commands. For example, Karl might wish to draw three paths using a
-|thick| pen, but would like everything else to be drawn ``normally''.
-
-If Karl wishes to set a certain graphic option for the whole picture, he can
-simply pass this option to the |\tikz| command or to the |{tikzpicture}|
-environment (Gerda would pass the options to |\tikzpicture| and Hans passes
-them to |\starttikzpicture|). However, if Karl wants to apply graphic options
-to a local group, he put these commands inside a |{scope}| environment (Gerda
-uses |\scope| and |\endscope|, Hans uses |\startscope| and |\stopscope|). This
-environment takes graphic options as an optional argument and these options
-apply to everything inside the scope, but not to anything outside.
-
-Here is an example:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[ultra thick]
- \draw (0,0) -- (0,1);
- \begin{scope}[thin]
- \draw (1,0) -- (1,1);
- \draw (2,0) -- (2,1);
- \end{scope}
- \draw (3,0) -- (3,1);
-\end{tikzpicture}
-\end{codeexample}
-
-Scoping has another interesting effect: Any changes to the clipping area are
-local to the scope. Thus, if you say |\clip| somewhere inside a scope, the
-effect of the |\clip| command ends at the end of the scope. This is useful
-since there is no other way of ``enlarging'' the clipping area.
-
-Karl has also already seen that giving options to commands like |\draw| apply
-only to that command. It turns out that the situation is slightly more complex.
-First, options to a command like |\draw| are not really options to the command,
-but they are ``path options'' and can be given anywhere on the path. So,
-instead of |\draw[thin] (0,0) -- (1,0);| one can also write
-|\draw (0,0) [thin] -- (1,0);| or |\draw (0,0) -- (1,0) [thin];|; all of these
-have the same effect. This might seem strange since in the last case, it would
-appear that the |thin| should take effect only ``after'' the line from $(0,0)$
-to $(1,0)$ has been drawn. However, most graphic options only apply to the
-whole path. Indeed, if you say both |thin| and |thick| on the same path, the
-last option given will ``win''.
-
-When reading the above, Karl notices that only ``most'' graphic options apply
-to the whole path. Indeed, all transformation options do \emph{not} apply to
-the whole path, but only to ``everything following them on the path''. We will
-have a more detailed look at this in a moment. Nevertheless, all options given
-during a path construction apply only to this path.
-
-
-\subsection{Transformations}
-
-When you specify a coordinate like |(1cm,1cm)|, where is that coordinate
-placed on the page? To determine the position, \tikzname, \TeX, and
-\textsc{pdf} or PostScript all apply certain transformations to the given
-coordinate in order to determine the final position on the page.
-
-\tikzname\ provides numerous options that allow you to transform coordinates in
-\tikzname's private coordinate system. For example, the |xshift| option allows
-you to shift all subsequent points by a certain amount:
-
-\begin{codeexample}[]
-\tikz \draw (0,0) -- (0,0.5) [xshift=2pt] (0,0) -- (0,0.5);
-\end{codeexample}
-
-It is important to note that you can change transformation ``in the middle of a
-path'', a feature that is not supported by \pdf\ or PostScript. The reason is
-that \tikzname\ keeps track of its own transformation matrix.
-
-Here is a more complicated example:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[even odd rule,rounded corners=2pt,x=10pt,y=10pt]
- \filldraw[fill=yellow!80!black] (0,0) rectangle (1,1)
- [xshift=5pt,yshift=5pt] (0,0) rectangle (1,1)
- [rotate=30] (-1,-1) rectangle (2,2);
-\end{tikzpicture}
-\end{codeexample}
-
-The most useful transformations are |xshift| and |yshift| for shifting, |shift|
-for shifting to a given point as in |shift={(1,0)}| or |shift={+(0,0)}| (the
-braces are necessary so that \TeX\ does not mistake the comma for separating
-options), |rotate| for rotating by a certain angle (there is also a
-|rotate around| for rotating around a given point), |scale| for scaling by a
-certain factor, |xscale| and |yscale| for scaling only in the $x$- or
-$y$-direction (|xscale=-1| is a flip), and |xslant| and |yslant| for slanting.
-If these transformation and those that I have not mentioned are not sufficient,
-the |cm| option allows you to apply an arbitrary transformation matrix. Karl's
-students, by the way, do not know what a transformation matrix is.
-
-
-\subsection{Repeating Things: For-Loops}
-
-Karl's next aim is to add little ticks on the axes at positions $-1$, $-1/2$,
-$1/2$, and $1$. For this, it would be nice to use some kind of ``loop'',
-especially since he wishes to do the same thing at each of these positions.
-There are different packages for doing this. \LaTeX\ has its own internal
-command for this, |pstricks| comes along with the powerful |\multido| command.
-All of these can be used together with \tikzname, so if you are familiar with
-them, feel free to use them. \tikzname\ introduces yet another command, called
-|\foreach|, which I introduced since I could never remember the syntax of the
-other packages. |\foreach| is defined in the package |pgffor| and can be used
-independently of \tikzname, but \tikzname\ includes it automatically.
-
-In its basic form, the |\foreach| command is easy to use:
-%
-\begin{codeexample}[]
-\foreach \x in {1,2,3} {$x =\x$, }
-\end{codeexample}
-
-The general syntax is
-|\foreach| \meta{variable}| in {|\meta{list of values}|} |\meta{commands}.
-Inside the \meta{commands}, the \meta{variable} will be assigned to the
-different values. If the \meta{commands} do not start with a brace, everything
-up to the next semicolon is used as \meta{commands}.
-
-For Karl and the ticks on the axes, he could use the following code:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=3]
- \clip (-0.1,-0.2) rectangle (1.1,1.51);
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm)
- arc [start angle=0, end angle=30, radius=3mm] -- cycle;
- \draw[->] (-1.5,0) -- (1.5,0);
- \draw[->] (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
-
- \foreach \x in {-1cm,-0.5cm,1cm}
- \draw (\x,-1pt) -- (\x,1pt);
- \foreach \y in {-1cm,-0.5cm,0.5cm,1cm}
- \draw (-1pt,\y) -- (1pt,\y);
-\end{tikzpicture}
-\end{codeexample}
-
-As a matter of fact, there are many different ways of creating the ticks. For
-example, Karl could have put the |\draw ...;| inside curly braces. He could
-also have used, say,
-%
-\begin{codeexample}[code only]
-\foreach \x in {-1,-0.5,1}
- \draw[xshift=\x cm] (0pt,-1pt) -- (0pt,1pt);
-\end{codeexample}
-
-Karl is curious what would happen in a more complicated situation where there
-are, say, 20 ticks. It seems bothersome to explicitly mention all these numbers
-in the set for |\foreach|. Indeed, it is possible to use |...| inside the
-|\foreach| statement to iterate over a large number of values (which must,
-however, be dimensionless real numbers) as in the following example:
-%
-\begin{codeexample}[]
-\tikz \foreach \x in {1,...,10}
- \draw (\x,0) circle (0.4cm);
-\end{codeexample}
-
-If you provide \emph{two} numbers before the |...|, the |\foreach| statement
-will use their difference for the stepping:
-%
-\begin{codeexample}[]
-\tikz \foreach \x in {-1,-0.5,...,1}
- \draw (\x cm,-1pt) -- (\x cm,1pt);
-\end{codeexample}
-
-We can also nest loops to create interesting effects:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \foreach \x in {1,2,...,5,7,8,...,12}
- \foreach \y in {1,...,5}
- {
- \draw (\x,\y) +(-.5,-.5) rectangle ++(.5,.5);
- \draw (\x,\y) node{\x,\y};
- }
-\end{tikzpicture}
-\end{codeexample}
-
-The |\foreach| statement can do even trickier stuff, but the above gives the
-idea.
-
-
-\subsection{Adding Text}
-
-Karl is, by now, quite satisfied with the picture. However, the most important
-parts, namely the labels, are still missing!
-
-\tikzname\ offers an easy-to-use and powerful system for adding text and, more
-generally, complex shapes to a picture at specific positions. The basic idea is
-the following: When \tikzname\ is constructing a path and encounters the
-keyword |node| in the middle of a path, it reads a \emph{node specification}.
-The keyword |node| is typically followed by some options and then some text
-between curly braces. This text is put inside a normal \TeX\ box (if the node
-specification directly follows a coordinate, which is usually the case,
-\tikzname\ is able to perform some magic so that it is even possible to use
-verbatim text inside the boxes) and then placed at the current position, that
-is, at the last specified position (possibly shifted a bit, according to the
-given options). However, all nodes are drawn only after the path has been
-completely drawn/filled/shaded/clipped/whatever.
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) rectangle (2,2);
- \draw (0.5,0.5) node [fill=yellow!80!black]
- {Text at \verb!node 1!}
- -- (1.5,1.5) node {Text at \verb!node 2!};
-\end{tikzpicture}
-\end{codeexample}
-
-Obviously, Karl would not only like to place nodes \emph{on} the last specified
-position, but also to the left or the right of these positions. For this, every
-node object that you put in your picture is equipped with several
-\emph{anchors}. For example, the |north| anchor is in the middle at the upper
-end of the shape, the |south| anchor is at the bottom and the |north east|
-anchor is in the upper right corner. When you give the option |anchor=north|,
-the text will be placed such that this northern anchor will lie on the current
-position and the text is, thus, below the current position. Karl uses this to
-draw the ticks as follows:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=3]
- \clip (-0.6,-0.2) rectangle (0.6,1.51);
- \draw[step=.5cm,help lines] (-1.4,-1.4) grid (1.4,1.4);
- \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm)
- arc [start angle=0, end angle=30, radius=3mm] -- cycle;
- \draw[->] (-1.5,0) -- (1.5,0); \draw[->] (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
-
- \foreach \x in {-1,-0.5,1}
- \draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north] {$\x$};
- \foreach \y in {-1,-0.5,0.5,1}
- \draw (1pt,\y cm) -- (-1pt,\y cm) node[anchor=east] {$\y$};
-\end{tikzpicture}
-\end{codeexample}
-
-This is quite nice, already. Using these anchors, Karl can now add most of the
-other text elements. However, Karl thinks that, though ``correct'', it is quite
-counter-intuitive that in order to place something \emph{below} a given point,
-he has to use the \emph{north} anchor. For this reason, there is an option
-called |below|, which does the same as |anchor=north|. Similarly, |above right|
-does the same as |anchor=south west|. In addition, |below| takes an optional
-dimension argument. If given, the shape will additionally be shifted downwards
-by the given amount. So, |below=1pt| can be used to put a text label below some
-point and, additionally shift it 1pt downwards.
-
-Karl is not quite satisfied with the ticks. He would like to have $1/2$ or
-$\frac{1}{2}$ shown instead of $0.5$, partly to show off the nice capabilities
-of \TeX\ and \tikzname, partly because for positions like $1/3$ or $\pi$ it is
-certainly very much preferable to have the ``mathematical'' tick there instead
-of just the ``numeric'' tick. His students, on the other hand, prefer $0.5$
-over $1/2$ since they are not too fond of fractions in general.
-
-Karl now faces a problem: For the |\foreach| statement, the position |\x|
-should still be given as |0.5| since \tikzname\ will not know where
-|\frac{1}{2}| is supposed to be. On the other hand, the typeset text should
-really be |\frac{1}{2}|. To solve this problem, |\foreach| offers a special
-syntax: Instead of having one variable |\x|, Karl can specify two (or even
-more) variables separated by a slash as in |\x / \xtext|. Then, the elements in
-the set over which |\foreach| iterates must also be of the form
-\meta{first}|/|\meta{second}. In each iteration, |\x| will be set to
-\meta{first} and |\xtext| will be set to \meta{second}. If no \meta{second} is
-given, the \meta{first} will be used again. So, here is the new code for the
-ticks:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}[scale=3]
- \clip (-0.6,-0.2) rectangle (0.6,1.51);
- \draw[step=.5cm,help lines] (-1.4,-1.4) grid (1.4,1.4);
- \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm)
- arc [start angle=0, end angle=30, radius=3mm] -- cycle;
- \draw[->] (-1.5,0) -- (1.5,0); \draw[->] (0,-1.5) -- (0,1.5);
- \draw (0,0) circle [radius=1cm];
-
- \foreach \x/\xtext in {-1, -0.5/-\frac{1}{2}, 1}
- \draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north] {$\xtext$};
- \foreach \y/\ytext in {-1, -0.5/-\frac{1}{2}, 0.5/\frac{1}{2}, 1}
- \draw (1pt,\y cm) -- (-1pt,\y cm) node[anchor=east] {$\ytext$};
-\end{tikzpicture}
-\end{codeexample}
-
-Karl is quite pleased with the result, but his son points out that this is
-still not perfectly satisfactory: The grid and the circle interfere with the
-numbers and decrease their legibility. Karl is not very concerned by this (his
-students do not even notice), but his son insists that there is an easy
-solution: Karl can add the |[fill=white]| option to fill out the background of
-the text shape with a white color.
-
-The next thing Karl wants to do is to add the labels like $\sin \alpha$. For
-this, he would like to place a label ``in the middle of the line''. To do so,
-instead of specifying the label |node {$\sin\alpha$}| directly after one of
-the endpoints of the line (which would place the label at that endpoint), Karl
-can give the label directly after the |--|, before the coordinate. By default,
-this places the label in the middle of the line, but the |pos=| options can be
-used to modify this. Also, options like |near start| and |near end| can be used
-to modify this position:
-%
-\begin{codeexample}[preamble={\usetikzlibrary{intersections}}]
-\begin{tikzpicture}[scale=3]
- \clip (-2,-0.2) rectangle (2,0.8);
- \draw[step=.5cm,gray,very thin] (-1.4,-1.4) grid (1.4,1.4);
- \filldraw[fill=green!20,draw=green!50!black] (0,0) -- (3mm,0mm)
- arc [start angle=0, end angle=30, radius=3mm] -- cycle;
- \draw[->] (-1.5,0) -- (1.5,0) coordinate (x axis);
- \draw[->] (0,-1.5) -- (0,1.5) coordinate (y axis);
- \draw (0,0) circle [radius=1cm];
-
- \draw[very thick,red]
- (30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} (30:1cm |- x axis);
- \draw[very thick,blue]
- (30:1cm |- x axis) -- node[below=2pt,fill=white] {$\cos \alpha$} (0,0);
- \path [name path=upward line] (1,0) -- (1,1);
- \path [name path=sloped line] (0,0) -- (30:1.5cm);
- \draw [name intersections={of=upward line and sloped line, by=t}]
- [very thick,orange] (1,0) -- node [right=1pt,fill=white]
- {$\displaystyle \tan \alpha \color{black}=
- \frac{{\color{red}\sin \alpha}}{\color{blue}\cos \alpha}$} (t);
-
- \draw (0,0) -- (t);
-
- \foreach \x/\xtext in {-1, -0.5/-\frac{1}{2}, 1}
- \draw (\x cm,1pt) -- (\x cm,-1pt) node[anchor=north,fill=white] {$\xtext$};
- \foreach \y/\ytext in {-1, -0.5/-\frac{1}{2}, 0.5/\frac{1}{2}, 1}
- \draw (1pt,\y cm) -- (-1pt,\y cm) node[anchor=east,fill=white] {$\ytext$};
-\end{tikzpicture}
-\end{codeexample}
-
-You can also position labels on curves and, by adding the |sloped| option, have
-them rotated such that they match the line's slope. Here is an example:
-%
-\begin{codeexample}[]
-\begin{tikzpicture}
- \draw (0,0) .. controls (6,1) and (9,1) ..
- node[near start,sloped,above] {near start}
- node {midway}
- node[very near end,sloped,below] {very near end} (12,0);
-\end{tikzpicture}
-\end{codeexample}
-
-It remains to draw the explanatory text at the right of the picture. The main
-difficulty here lies in limiting the width of the text ``label'', which is
-quite long, so that line breaking is used. Fortunately, Karl can use the option
-|text width=6cm| to get the desired effect. So, here is the full code:
-%
-\begin{codeexample}[code only]
-\begin{tikzpicture}
- [scale=3,line cap=round,
- % Styles
- axes/.style=,
- important line/.style={very thick},
- information text/.style={rounded corners,fill=red!10,inner sep=1ex}]
-
- % Colors
- \colorlet{anglecolor}{green!50!black}
- \colorlet{sincolor}{red}
- \colorlet{tancolor}{orange!80!black}
- \colorlet{coscolor}{blue}
-
- % The graphic
- \draw[help lines,step=0.5cm] (-1.4,-1.4) grid (1.4,1.4);
-
- \draw (0,0) circle [radius=1cm];
-
- \begin{scope}[axes]
- \draw[->] (-1.5,0) -- (1.5,0) node[right] {$x$} coordinate(x axis);
- \draw[->] (0,-1.5) -- (0,1.5) node[above] {$y$} coordinate(y axis);
-
- \foreach \x/\xtext in {-1, -.5/-\frac{1}{2}, 1}
- \draw[xshift=\x cm] (0pt,1pt) -- (0pt,-1pt) node[below,fill=white] {$\xtext$};
-
- \foreach \y/\ytext in {-1, -.5/-\frac{1}{2}, .5/\frac{1}{2}, 1}
- \draw[yshift=\y cm] (1pt,0pt) -- (-1pt,0pt) node[left,fill=white] {$\ytext$};
- \end{scope}
-
- \filldraw[fill=green!20,draw=anglecolor] (0,0) -- (3mm,0pt)
- arc [start angle=0, end angle=30, radius=3mm];
- \draw (15:2mm) node[anglecolor] {$\alpha$};
-
- \draw[important line,sincolor]
- (30:1cm) -- node[left=1pt,fill=white] {$\sin \alpha$} (30:1cm |- x axis);
-
- \draw[important line,coscolor]
- (30:1cm |- x axis) -- node[below=2pt,fill=white] {$\cos \alpha$} (0,0);
-
- \path [name path=upward line] (1,0) -- (1,1);
- \path [name path=sloped line] (0,0) -- (30:1.5cm);
- \draw [name intersections={of=upward line and sloped line, by=t}]
- [very thick,orange] (1,0) -- node [right=1pt,fill=white]
- {$\displaystyle \tan \alpha \color{black}=
- \frac{{\color{red}\sin \alpha}}{\color{blue}\cos \alpha}$} (t);
-
- \draw (0,0) -- (t);
-
- \draw[xshift=1.85cm]
- node[right,text width=6cm,information text]
- {
- The {\color{anglecolor} angle $\alpha$} is $30^\circ$ in the
- example ($\pi/6$ in radians). The {\color{sincolor}sine of
- $\alpha$}, which is the height of the red line, is
- \[
- {\color{sincolor} \sin \alpha} = 1/2.
- \]
- By the Theorem of Pythagoras ...
- };
-\end{tikzpicture}
-\end{codeexample}
-
-
-\subsection{Pics: The Angle Revisited}
-
-Karl expects that the code of certain parts of the picture he created might be
-so useful that he might wish to reuse them in the future. A natural thing to do
-is to create \TeX\ macros that store the code he wishes to reuse. However,
-\tikzname\ offers another way that is integrated directly into its parser:
-pics!
-
-A ``pic'' is ``not quite a full picture'', hence the short name. The idea is
-that a pic is simply some code that you can add to a picture at different
-places using the |pic| command whose syntax is almost identical to the |node|
-command. The main difference is that instead of specifying some text in curly
-braces that should be shown, you specify the name of a predefined picture that
-should be shown.
-
-Defining new pics is easy enough, see Section~\ref{section-pics}, but right now
-we just want to use one such predefined pic: the |angle| pic. As the name
-suggests, it is a small drawing of an angle consisting of a little wedge and an
-arc together with some text (Karl needs to load the |angles| library and the
-|quotes| for the following examples). What makes this pic useful is the fact
-that the size of the wedge will be computed automatically.
-
-The |angle| pic draws an angle between the two lines $BA$ and $BC$, where $A$,
-$B$, and $C$ are three coordinates. In our case, $B$ is the origin, $A$ is
-somewhere on the $x$-axis and $C$ is somewhere on a line at $30^\circ$.
-%
-\begin{codeexample}[preamble={\usetikzlibrary{angles,quotes}}]
-\begin{tikzpicture}[scale=3]
- \coordinate (A) at (1,0);
- \coordinate (B) at (0,0);
- \coordinate (C) at (30:1cm);
-
- \draw (A) -- (B) -- (C)
- pic [draw=green!50!black, fill=green!20, angle radius=9mm,
- "$\alpha$"] {angle = A--B--C};
-\end{tikzpicture}
-\end{codeexample}
-
-Let us see, what is happening here. First we have specified three
-\emph{coordinates} using the |\coordinate| command. It allows us to name a
-specific coordinate in the picture. Then comes something that starts as a
-normal |\draw|, but then comes the |pic| command. This command gets lots of
-options and, in curly braces, comes the most important point: We specify that
-we want to add an |angle| pic and this angle should be between the points we
-named |A|, |B|, and |C| (we could use other names). Note that the text that we
-want to be shown in the pic is specified in quotes inside the options of the
-|pic|, not inside the curly braces.
-
-To learn more about pics, please see Section~\ref{section-pics}.
diff --git a/graphics/pgf/base/doc/text-en/pgfmanual-en-xxcolor.tex b/graphics/pgf/base/doc/text-en/pgfmanual-en-xxcolor.tex
deleted file mode 100644
index de910e8292..0000000000
--- a/graphics/pgf/base/doc/text-en/pgfmanual-en-xxcolor.tex
+++ /dev/null
@@ -1,85 +0,0 @@
-% 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{Extended Color Support}
-
-This section documents the package \texttt{xxcolor}, which is currently
-distributed as part of \pgfname. This package extends the \texttt{xcolor}
-package, written by Uwe Kern, which in turn extends the \texttt{color} package.
-I hope that the commands in \texttt{xxcolor} will some day migrate to
-\texttt{xcolor}, such that this package becomes superfluous.
-
-The main aim of the \texttt{xxcolor} package is to provide an environment
-inside which all colors are ``washed out'' or ``dimmed''. This is useful in
-numerous situations and must typically be achieved in a roundabout manner if
-such an environment is not available.
-
-\begin{environment}{{colormixin}\marg{mix-in specification}}
- The mix-in specification is applied to all colors inside the environment.
- At the beginning of the environment, the mix-in is applied to the current
- color, i.e., the color that was in effect before the environment started.
- A mix-in specification is a number between 0 and 100 followed by an
- exclamation mark and a color name. When a |\color| command is encountered
- inside a mix-in environment, the number states what percentage of the
- desired color should be used. The rest is ``filled up'' with the color
- given in the mix-in specification. Thus, a mix-in specification like
- |90!blue| will mix in 10\% of blue into everything, whereas |25!white| will
- make everything nearly white.
- %
-\begin{codeexample}[width=4cm,preamble={\usepackage{xxcolor}}]
-\begin{minipage}{3.5cm}\raggedright
-\color{red}Red text,%
-\begin{colormixin}{25!white}
- washed-out red text,
- \color{blue} washed-out blue text,
- \begin{colormixin}{25!black}
- dark washed-out blue text,
- \color{green} dark washed-out green text,%
- \end{colormixin}
- back to washed-out blue text,%
-\end{colormixin}
-and back to red.
-\end{minipage}%
-\end{codeexample}
- %
-\end{environment}
-
-Note that the environment only changes colors that have been installed using
-the standard \LaTeX\ |\color| command. In particular, the colors in images are
-not changed. There is, however, some support offered by the commands
-|\pgfuseimage| and |\pgfuseshading|. If the first command is invoked inside a
-|colormixin| environment with the parameter, say, |50!black| on an image with
-the name |foo|, the command will first check whether there is also a defined
-image with the name |foo.!50!black|. If so, this image is used instead. This
-allows you to provide a different image for this case. If you nest |colormixin|
-environments, the different mix-ins are all appended. For example, inside the
-inner environment of the above example, |\pgfuseimage{foo}| would first check
-whether there exists an image named |foo.!25!white!25!black|.
-
-\begin{command}{\colorcurrentmixin}
- Expands to the current accumulated mix-in. Each nesting of a |colormixin|
- adds a mix-in to this list.
- %
-\begin{codeexample}[preamble={\usepackage{xxcolor}
-\usepackage{calc}}]
-\begin{minipage}{\linewidth-6pt}\raggedright
-\begin{colormixin}{75!white}
- \colorcurrentmixin\ should be ``!75!white''\par
- \begin{colormixin}{75!black}
- \colorcurrentmixin\ should be ``!75!black!75!white''\par
- \begin{colormixin}{50!white}
- \colorcurrentmixin\ should be ``!50!white!75!black!75!white''\par
- \end{colormixin}
- \end{colormixin}
-\end{colormixin}
-\end{minipage}
-\end{codeexample}
- %
-\end{command}
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-asymptotic-example.gnuplot b/graphics/pgf/base/doc/text-en/plots/pgf-asymptotic-example.gnuplot
deleted file mode 100644
index fca2b3fd23..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-asymptotic-example.gnuplot
+++ /dev/null
@@ -1,2 +0,0 @@
-set table "plots/pgf-asymptotic-example.table"; set format "%.5f"
-set samples 200; set parametric; plot [t=0.4:1.5] (t*t*t)*sin(1/(t*t*t)),(t*t*t)*cos(1/(t*t*t))
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-asymptotic-example.table b/graphics/pgf/base/doc/text-en/plots/pgf-asymptotic-example.table
deleted file mode 100644
index 173ab5e9c7..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-asymptotic-example.table
+++ /dev/null
@@ -1,204 +0,0 @@
-#Curve 0, 200 points
-#x y type
-0.00530 -0.06378 i
-0.04363 -0.05043 i
-0.06711 -0.01790 i
-0.06896 0.02170 i
-0.05014 0.05606 i
-0.01712 0.07631 i
--0.02110 0.07849 i
--0.05579 0.06337 i
--0.08032 0.03512 i
--0.09097 -0.00029 i
--0.08696 -0.03664 i
--0.06987 -0.06850 i
--0.04284 -0.09192 i
--0.00982 -0.10460 i
-0.02515 -0.10585 i
-0.05841 -0.09629 i
-0.08703 -0.07749 i
-0.10892 -0.05162 i
-0.12282 -0.02111 i
-0.12828 0.01163 i
-0.12547 0.04436 i
-0.11507 0.07518 i
-0.09810 0.10255 i
-0.07579 0.12534 i
-0.04948 0.14280 i
-0.02048 0.15454 i
--0.00995 0.16043 i
--0.04065 0.16063 i
--0.07063 0.15545 i
--0.09905 0.14536 i
--0.12521 0.13092 i
--0.14860 0.11273 i
--0.16882 0.09143 i
--0.18562 0.06764 i
--0.19885 0.04197 i
--0.20848 0.01500 i
--0.21454 -0.01276 i
--0.21712 -0.04083 i
--0.21637 -0.06879 i
--0.21247 -0.09627 i
--0.20565 -0.12295 i
--0.19613 -0.14858 i
--0.18415 -0.17294 i
--0.16996 -0.19585 i
--0.15379 -0.21718 i
--0.13589 -0.23682 i
--0.11647 -0.25471 i
--0.09576 -0.27080 i
--0.07396 -0.28508 i
--0.05126 -0.29753 i
--0.02783 -0.30819 i
--0.00384 -0.31707 i
-0.02057 -0.32421 i
-0.04526 -0.32967 i
-0.07011 -0.33350 i
-0.09502 -0.33576 i
-0.11989 -0.33651 i
-0.14463 -0.33582 i
-0.16917 -0.33376 i
-0.19345 -0.33040 i
-0.21741 -0.32580 i
-0.24100 -0.32003 i
-0.26418 -0.31315 i
-0.28691 -0.30524 i
-0.30918 -0.29634 i
-0.33096 -0.28653 i
-0.35222 -0.27585 i
-0.37297 -0.26437 i
-0.39318 -0.25213 i
-0.41285 -0.23918 i
-0.43197 -0.22557 i
-0.45056 -0.21134 i
-0.46860 -0.19654 i
-0.48611 -0.18119 i
-0.50309 -0.16535 i
-0.51954 -0.14904 i
-0.53547 -0.13229 i
-0.55090 -0.11514 i
-0.56582 -0.09761 i
-0.58026 -0.07972 i
-0.59422 -0.06150 i
-0.60772 -0.04298 i
-0.62076 -0.02416 i
-0.63336 -0.00508 i
-0.64554 0.01425 i
-0.65729 0.03382 i
-0.66864 0.05361 i
-0.67960 0.07361 i
-0.69018 0.09381 i
-0.70039 0.11420 i
-0.71024 0.13475 i
-0.71975 0.15548 i
-0.72892 0.17636 i
-0.73778 0.19739 i
-0.74632 0.21857 i
-0.75456 0.23989 i
-0.76251 0.26134 i
-0.77018 0.28291 i
-0.77759 0.30461 i
-0.78473 0.32643 i
-0.79162 0.34837 i
-0.79826 0.37042 i
-0.80468 0.39258 i
-0.81087 0.41485 i
-0.81684 0.43723 i
-0.82261 0.45972 i
-0.82817 0.48232 i
-0.83354 0.50502 i
-0.83872 0.52782 i
-0.84372 0.55073 i
-0.84855 0.57374 i
-0.85321 0.59686 i
-0.85772 0.62009 i
-0.86206 0.64342 i
-0.86626 0.66685 i
-0.87032 0.69040 i
-0.87423 0.71405 i
-0.87801 0.73781 i
-0.88167 0.76169 i
-0.88520 0.78567 i
-0.88861 0.80977 i
-0.89191 0.83398 i
-0.89510 0.85831 i
-0.89818 0.88276 i
-0.90115 0.90733 i
-0.90403 0.93202 i
-0.90682 0.95683 i
-0.90951 0.98177 i
-0.91211 1.00683 i
-0.91463 1.03202 i
-0.91707 1.05735 i
-0.91942 1.08280 i
-0.92171 1.10839 i
-0.92391 1.13411 i
-0.92605 1.15998 i
-0.92812 1.18598 i
-0.93012 1.21213 i
-0.93205 1.23842 i
-0.93393 1.26485 i
-0.93575 1.29143 i
-0.93751 1.31817 i
-0.93921 1.34505 i
-0.94086 1.37209 i
-0.94246 1.39929 i
-0.94401 1.42664 i
-0.94552 1.45415 i
-0.94697 1.48183 i
-0.94838 1.50967 i
-0.94975 1.53767 i
-0.95108 1.56584 i
-0.95236 1.59418 i
-0.95361 1.62270 i
-0.95482 1.65138 i
-0.95600 1.68025 i
-0.95713 1.70928 i
-0.95824 1.73850 i
-0.95931 1.76790 i
-0.96035 1.79748 i
-0.96136 1.82725 i
-0.96234 1.85720 i
-0.96329 1.88735 i
-0.96422 1.91768 i
-0.96511 1.94820 i
-0.96598 1.97892 i
-0.96683 2.00983 i
-0.96765 2.04094 i
-0.96845 2.07225 i
-0.96922 2.10376 i
-0.96998 2.13547 i
-0.97071 2.16739 i
-0.97142 2.19952 i
-0.97211 2.23185 i
-0.97278 2.26439 i
-0.97344 2.29714 i
-0.97407 2.33010 i
-0.97469 2.36328 i
-0.97529 2.39667 i
-0.97588 2.43028 i
-0.97644 2.46411 i
-0.97700 2.49817 i
-0.97754 2.53244 i
-0.97806 2.56694 i
-0.97857 2.60166 i
-0.97906 2.63661 i
-0.97955 2.67179 i
-0.98001 2.70720 i
-0.98047 2.74284 i
-0.98092 2.77871 i
-0.98135 2.81482 i
-0.98177 2.85117 i
-0.98218 2.88775 i
-0.98258 2.92457 i
-0.98297 2.96163 i
-0.98335 2.99894 i
-0.98372 3.03649 i
-0.98408 3.07428 i
-0.98443 3.11232 i
-0.98477 3.15061 i
-0.98511 3.18914 i
-0.98543 3.22793 i
-
-
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-exp.gnuplot b/graphics/pgf/base/doc/text-en/plots/pgf-exp.gnuplot
deleted file mode 100644
index 8109ea408c..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-exp.gnuplot
+++ /dev/null
@@ -1,2 +0,0 @@
-set table "plots/pgf-exp.table"; set format "%.5f"
-set samples 25; plot [x=0:4] 0.05*exp(x)
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-exp.table b/graphics/pgf/base/doc/text-en/plots/pgf-exp.table
deleted file mode 100644
index 8e72857039..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-exp.table
+++ /dev/null
@@ -1,29 +0,0 @@
-#Curve 0, 25 points
-#x y type
-0.00000 0.05000 i
-0.16667 0.05907 i
-0.33333 0.06978 i
-0.50000 0.08244 i
-0.66667 0.09739 i
-0.83333 0.11505 i
-1.00000 0.13591 i
-1.16667 0.16056 i
-1.33333 0.18968 i
-1.50000 0.22408 i
-1.66667 0.26472 i
-1.83333 0.31274 i
-2.00000 0.36945 i
-2.16667 0.43646 i
-2.33333 0.51561 i
-2.50000 0.60912 i
-2.66667 0.71960 i
-2.83333 0.85010 i
-3.00000 1.00428 i
-3.16667 1.18641 i
-3.33333 1.40158 i
-3.50000 1.65577 i
-3.66667 1.95606 i
-3.83333 2.31082 i
-4.00000 2.72991 i
-
-
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-parametric-example.gnuplot b/graphics/pgf/base/doc/text-en/plots/pgf-parametric-example.gnuplot
deleted file mode 100644
index 2c366fe529..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-parametric-example.gnuplot
+++ /dev/null
@@ -1,2 +0,0 @@
-set table "plots/pgf-parametric-example.table"; set format "%.5f"
-set samples 25; set parametric; plot [t=-3.141:3.141] t*sin(t),t*cos(t)
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-parametric-example.table b/graphics/pgf/base/doc/text-en/plots/pgf-parametric-example.table
deleted file mode 100644
index de0c383ddd..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-parametric-example.table
+++ /dev/null
@@ -1,29 +0,0 @@
-#Curve 0, 25 points
-#x y type
-0.00186 3.14100 i
-0.74672 2.78074 i
-1.30987 2.26617 i
-1.66651 1.66503 i
-1.81387 1.04628 i
-1.76998 0.47361 i
-1.57050 -0.00047 i
-1.26407 -0.33904 i
-0.90663 -0.52368 i
-0.55517 -0.55534 i
-0.26171 -0.45339 i
-0.06773 -0.25283 i
-0.00000 -0.00000 i
-0.06773 0.25283 i
-0.26171 0.45339 i
-0.55517 0.55534 i
-0.90663 0.52368 i
-1.26407 0.33904 i
-1.57050 0.00047 i
-1.76998 -0.47361 i
-1.81387 -1.04628 i
-1.66651 -1.66503 i
-1.30987 -2.26617 i
-0.74672 -2.78074 i
-0.00186 -3.14100 i
-
-
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-sin.gnuplot b/graphics/pgf/base/doc/text-en/plots/pgf-sin.gnuplot
deleted file mode 100644
index 48df575630..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-sin.gnuplot
+++ /dev/null
@@ -1,2 +0,0 @@
-set table "plots/pgf-sin.table"; set format "%.5f"
-set samples 25; plot [x=0:4] sin(x)
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-sin.table b/graphics/pgf/base/doc/text-en/plots/pgf-sin.table
deleted file mode 100644
index 9ab8f2c8d5..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-sin.table
+++ /dev/null
@@ -1,29 +0,0 @@
-#Curve 0, 25 points
-#x y type
-0.00000 0.00000 i
-0.16667 0.16590 i
-0.33333 0.32719 i
-0.50000 0.47943 i
-0.66667 0.61837 i
-0.83333 0.74018 i
-1.00000 0.84147 i
-1.16667 0.91944 i
-1.33333 0.97194 i
-1.50000 0.99749 i
-1.66667 0.99541 i
-1.83333 0.96573 i
-2.00000 0.90930 i
-2.16667 0.82766 i
-2.33333 0.72309 i
-2.50000 0.59847 i
-2.66667 0.45727 i
-2.83333 0.30340 i
-3.00000 0.14112 i
-3.16667 -0.02507 i
-3.33333 -0.19057 i
-3.50000 -0.35078 i
-3.66667 -0.50128 i
-3.83333 -0.63788 i
-4.00000 -0.75680 i
-
-
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-tan-example.gnuplot b/graphics/pgf/base/doc/text-en/plots/pgf-tan-example.gnuplot
deleted file mode 100644
index 0b0a1ad8ff..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-tan-example.gnuplot
+++ /dev/null
@@ -1,2 +0,0 @@
-set table "plots/pgf-tan-example.table"; set format "%.5f"
-set samples 100.0; plot [x=-3.141:3.141] [-3:3]tan(x)
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-tan-example.table b/graphics/pgf/base/doc/text-en/plots/pgf-tan-example.table
deleted file mode 100644
index 63beeda4b7..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-tan-example.table
+++ /dev/null
@@ -1,104 +0,0 @@
-
-#Curve 0 of 1, 100 points
-#x y type
--3.14100 0.00059 i
--3.07755 0.06413 i
--3.01409 0.12820 i
--2.95064 0.19331 i
--2.88718 0.26005 i
--2.82373 0.32902 i
--2.76027 0.40094 i
--2.69682 0.47663 i
--2.63336 0.55704 i
--2.56991 0.64335 i
--2.50645 0.73701 i
--2.44300 0.83989 i
--2.37955 0.95436 i
--2.31609 1.08360 i
--2.25264 1.23197 i
--2.18918 1.40553 i
--2.12573 1.61314 i
--2.06227 1.86816 i
--1.99882 2.19188 i
--1.93536 2.62036 i
--1.87191 3.22003 o
--1.80845 4.12820 o
--1.74500 5.68222 o
--1.68155 8.99247 o
--1.61809 21.12830 o
--1.55464 -61.87594 o
--1.49118 -12.53398 o
--1.42773 -6.94188 o
--1.36427 -4.77302 o
--1.30082 -3.61357 o
--1.23736 -2.88713 i
--1.17391 -2.38590 i
--1.11045 -2.01664 i
--1.04700 -1.73126 i
--0.98355 -1.50245 i
--0.92009 -1.31351 i
--0.85664 -1.15368 i
--0.79318 -1.01569 i
--0.72973 -0.89443 i
--0.66627 -0.78621 i
--0.60282 -0.68828 i
--0.53936 -0.59856 i
--0.47591 -0.51542 i
--0.41245 -0.43755 i
--0.34900 -0.36390 i
--0.28555 -0.29357 i
--0.22209 -0.22582 i
--0.15864 -0.15998 i
--0.09518 -0.09547 i
--0.03173 -0.03174 i
-0.03173 0.03174 i
-0.09518 0.09547 i
-0.15864 0.15998 i
-0.22209 0.22582 i
-0.28555 0.29357 i
-0.34900 0.36390 i
-0.41245 0.43755 i
-0.47591 0.51542 i
-0.53936 0.59856 i
-0.60282 0.68828 i
-0.66627 0.78621 i
-0.72973 0.89443 i
-0.79318 1.01569 i
-0.85664 1.15368 i
-0.92009 1.31351 i
-0.98355 1.50245 i
-1.04700 1.73126 i
-1.11045 2.01664 i
-1.17391 2.38590 i
-1.23736 2.88713 i
-1.30082 3.61357 o
-1.36427 4.77302 o
-1.42773 6.94188 o
-1.49118 12.53398 o
-1.55464 61.87594 o
-1.61809 -21.12830 o
-1.68155 -8.99247 o
-1.74500 -5.68222 o
-1.80845 -4.12820 o
-1.87191 -3.22003 o
-1.93536 -2.62036 i
-1.99882 -2.19188 i
-2.06227 -1.86816 i
-2.12573 -1.61314 i
-2.18918 -1.40553 i
-2.25264 -1.23197 i
-2.31609 -1.08360 i
-2.37955 -0.95436 i
-2.44300 -0.83989 i
-2.50645 -0.73701 i
-2.56991 -0.64335 i
-2.63336 -0.55704 i
-2.69682 -0.47663 i
-2.76027 -0.40094 i
-2.82373 -0.32902 i
-2.88718 -0.26005 i
-2.95064 -0.19331 i
-3.01409 -0.12820 i
-3.07755 -0.06413 i
-3.14100 -0.00059 i
-
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-x.gnuplot b/graphics/pgf/base/doc/text-en/plots/pgf-x.gnuplot
deleted file mode 100644
index 0e57c0571a..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-x.gnuplot
+++ /dev/null
@@ -1,2 +0,0 @@
-set table "plots/pgf-x.table"; set format "%.5f"
-set samples 25; plot [x=0:4] x
diff --git a/graphics/pgf/base/doc/text-en/plots/pgf-x.table b/graphics/pgf/base/doc/text-en/plots/pgf-x.table
deleted file mode 100644
index 329b9fa56b..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgf-x.table
+++ /dev/null
@@ -1,29 +0,0 @@
-#Curve 0, 25 points
-#x y type
-0.00000 0.00000 i
-0.16667 0.16667 i
-0.33333 0.33333 i
-0.50000 0.50000 i
-0.66667 0.66667 i
-0.83333 0.83333 i
-1.00000 1.00000 i
-1.16667 1.16667 i
-1.33333 1.33333 i
-1.50000 1.50000 i
-1.66667 1.66667 i
-1.83333 1.83333 i
-2.00000 2.00000 i
-2.16667 2.16667 i
-2.33333 2.33333 i
-2.50000 2.50000 i
-2.66667 2.66667 i
-2.83333 2.83333 i
-3.00000 3.00000 i
-3.16667 3.16667 i
-3.33333 3.33333 i
-3.50000 3.50000 i
-3.66667 3.66667 i
-3.83333 3.83333 i
-4.00000 4.00000 i
-
-
diff --git a/graphics/pgf/base/doc/text-en/plots/pgfmanual-sine.gnuplot b/graphics/pgf/base/doc/text-en/plots/pgfmanual-sine.gnuplot
deleted file mode 100644
index cff802be0a..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgfmanual-sine.gnuplot
+++ /dev/null
@@ -1,4 +0,0 @@
-set table "pgfmanual-sine.table"
-set format "%.5f"
-set samples 20
-plot [x=0:10] sin(x)
diff --git a/graphics/pgf/base/doc/text-en/plots/pgfmanual-sine.table b/graphics/pgf/base/doc/text-en/plots/pgfmanual-sine.table
deleted file mode 100644
index 9d5d248a56..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgfmanual-sine.table
+++ /dev/null
@@ -1,24 +0,0 @@
-#Curve 0, 20 points
-#x y type
-0.00000 0.00000 i
-0.52632 0.50235 i
-1.05263 0.86873 i
-1.57895 0.99997 i
-2.10526 0.86054 i
-2.63158 0.48819 i
-3.15789 -0.01630 i
-3.68421 -0.51638 i
-4.21053 -0.87669 i
-4.73684 -0.99970 i
-5.26316 -0.85212 i
-5.78947 -0.47390 i
-6.31579 0.03260 i
-6.84211 0.53027 i
-7.36842 0.88441 i
-7.89474 0.99917 i
-8.42105 0.84348 i
-8.94737 0.45948 i
-9.47368 -0.04889 i
-10.00000 -0.54402 i
-
-
diff --git a/graphics/pgf/base/doc/text-en/plots/pgfplotgnuplot-example.gnuplot b/graphics/pgf/base/doc/text-en/plots/pgfplotgnuplot-example.gnuplot
deleted file mode 100644
index ebac36dd23..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgfplotgnuplot-example.gnuplot
+++ /dev/null
@@ -1,2 +0,0 @@
-set table "plots/pgfplotgnuplot-example.table"; set format "%.5f"
-plot [x=0:3.5] x*sin(x)
diff --git a/graphics/pgf/base/doc/text-en/plots/pgfplotgnuplot-example.table b/graphics/pgf/base/doc/text-en/plots/pgfplotgnuplot-example.table
deleted file mode 100644
index a4e517898a..0000000000
--- a/graphics/pgf/base/doc/text-en/plots/pgfplotgnuplot-example.table
+++ /dev/null
@@ -1,104 +0,0 @@
-#Curve 0, 100 points
-#x y type
-0.00000 0.00000 i
-0.03535 0.00125 i
-0.07071 0.00500 i
-0.10606 0.01123 i
-0.14141 0.01993 i
-0.17677 0.03108 i
-0.21212 0.04466 i
-0.24747 0.06062 i
-0.28283 0.07893 i
-0.31818 0.09954 i
-0.35354 0.12240 i
-0.38889 0.14745 i
-0.42424 0.17463 i
-0.45960 0.20387 i
-0.49495 0.23509 i
-0.53030 0.26822 i
-0.56566 0.30318 i
-0.60101 0.33986 i
-0.63636 0.37817 i
-0.67172 0.41803 i
-0.70707 0.45932 i
-0.74242 0.50194 i
-0.77778 0.54577 i
-0.81313 0.59069 i
-0.84848 0.63660 i
-0.88384 0.68337 i
-0.91919 0.73086 i
-0.95455 0.77896 i
-0.98990 0.82753 i
-1.02525 0.87643 i
-1.06061 0.92554 i
-1.09596 0.97471 i
-1.13131 1.02381 i
-1.16667 1.07269 i
-1.20202 1.12121 i
-1.23737 1.16923 i
-1.27273 1.21661 i
-1.30808 1.26320 i
-1.34343 1.30886 i
-1.37879 1.35345 i
-1.41414 1.39682 i
-1.44949 1.43884 i
-1.48485 1.47937 i
-1.52020 1.51826 i
-1.55556 1.55537 i
-1.59091 1.59059 i
-1.62626 1.62376 i
-1.66162 1.65477 i
-1.69697 1.68348 i
-1.73232 1.70977 i
-1.76768 1.73353 i
-1.80303 1.75463 i
-1.83838 1.77296 i
-1.87374 1.78841 i
-1.90909 1.80089 i
-1.94444 1.81028 i
-1.97980 1.81650 i
-2.01515 1.81946 i
-2.05051 1.81906 i
-2.08586 1.81524 i
-2.12121 1.80792 i
-2.15657 1.79704 i
-2.19192 1.78252 i
-2.22727 1.76433 i
-2.26263 1.74240 i
-2.29798 1.71671 i
-2.33333 1.68720 i
-2.36869 1.65386 i
-2.40404 1.61667 i
-2.43939 1.57560 i
-2.47475 1.53066 i
-2.51010 1.48184 i
-2.54545 1.42915 i
-2.58081 1.37260 i
-2.61616 1.31223 i
-2.65152 1.24805 i
-2.68687 1.18011 i
-2.72222 1.10845 i
-2.75758 1.03312 i
-2.79293 0.95418 i
-2.82828 0.87170 i
-2.86364 0.78576 i
-2.89899 0.69642 i
-2.93434 0.60380 i
-2.96970 0.50797 i
-3.00505 0.40904 i
-3.04040 0.30713 i
-3.07576 0.20235 i
-3.11111 0.09482 i
-3.14646 -0.01533 i
-3.18182 -0.12796 i
-3.21717 -0.24292 i
-3.25253 -0.36007 i
-3.28788 -0.47926 i
-3.32323 -0.60032 i
-3.35859 -0.72308 i
-3.39394 -0.84739 i
-3.42929 -0.97305 i
-3.46465 -1.09990 i
-3.50000 -1.22774 i
-
-