summaryrefslogtreecommitdiff
path: root/graphics/pgf/base/doc/pgfmanual-en-tikz-design.tex
diff options
context:
space:
mode:
Diffstat (limited to 'graphics/pgf/base/doc/pgfmanual-en-tikz-design.tex')
-rw-r--r--graphics/pgf/base/doc/pgfmanual-en-tikz-design.tex274
1 files changed, 274 insertions, 0 deletions
diff --git a/graphics/pgf/base/doc/pgfmanual-en-tikz-design.tex b/graphics/pgf/base/doc/pgfmanual-en-tikz-design.tex
new file mode 100644
index 0000000000..7c6a435d15
--- /dev/null
+++ b/graphics/pgf/base/doc/pgfmanual-en-tikz-design.tex
@@ -0,0 +1,274 @@
+% 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 trees: 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.