summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex')
-rw-r--r--Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex309
1 files changed, 152 insertions, 157 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex
index 48a2f06a467..607a55fb434 100644
--- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex
+++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-tikz-design.tex
@@ -7,157 +7,155 @@
%
% 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
+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 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.
+ \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)|.
+\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''.
-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.
-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.
-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)|.
-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)|.
-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)|.
-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
+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.
+%
+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;
+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:
+
+\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.''
+%
+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}|.
+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.
+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.
+\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}
@@ -168,11 +166,11 @@ children in turn.
};
\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:
-
+%
+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}[]
\begin{tikzpicture}
[edge from parent fork down, sibling distance=15mm, level distance=15mm,
@@ -203,43 +201,42 @@ redrawn with different options:
\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.
-
+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}[]
\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.
+%
+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}.
+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:
-
+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]
@@ -255,25 +252,23 @@ lines, two green lines, and one blue line are drawn:
\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.
+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}.)
+\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.
+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.