diff options
Diffstat (limited to 'Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex')
-rw-r--r-- | Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex | 86 |
1 files changed, 42 insertions, 44 deletions
diff --git a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex index ea145e8fb06..92da9d37342 100644 --- a/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex +++ b/Master/texmf-dist/doc/generic/pgf/text-en/pgfmanual-en-base-decorations.tex @@ -48,10 +48,9 @@ The workflow for using decorations is the following: \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 starting ``walking + 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 as its - output new path construction commands (or even other outputs). These + 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. @@ -80,7 +79,7 @@ automata are presented. \subsubsection{The Different Paths} -In order to prevent confusion with different types of path, such +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: @@ -118,14 +117,14 @@ 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 extend by -the output path. This means that first time e |\pgfusepath| command is +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 part of the +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 @@ -134,17 +133,17 @@ text along a path. \subsubsection{Segments and States} -The most common use a decoration is to ``repeat something along a +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 be repeated: a decoration +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 +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 @@ -157,10 +156,10 @@ defined using the following code: \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 +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 setup automatically. +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 @@ -182,7 +181,7 @@ 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 state later, \pgfname\ first +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 @@ -193,7 +192,7 @@ 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 width parameter attached to each state. \pgfname\ then +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 @@ -225,16 +224,16 @@ this command describes the decoration automaton. 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 + 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 traveled along the second + 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 note that the computation of the path lengths has only a low + 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). @@ -251,15 +250,15 @@ this command describes the decoration automaton. happen: \begin{enumerate} \item - The \meta{options} are parsed. This may lead, see below, to a - state switch. When this happens, the following steps are not + 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 setup in such a way that the origin is on + 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 @@ -268,7 +267,7 @@ this command describes the decoration automaton. 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, which is extends the + decoration will produce an output path, that is, it extends the preexisting path. Here is an example: \begin{codeexample}[] @@ -295,7 +294,7 @@ this command describes the decoration automaton. \end{codeexample} Alternatively, the \meta{code} can also contain the - |\pgfusepath| command. This will use the path in usual manner, + |\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 @@ -332,13 +331,13 @@ this command describes the decoration automaton. 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}| to |\meta{new state}} + \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}| to |\meta{new state}} + \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 @@ -395,7 +394,7 @@ this command describes the decoration automaton. 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, the a closepath operation is used to + \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. @@ -403,11 +402,11 @@ this command describes the decoration automaton. \end{key} \begin{key}{/pgf/decoration automaton/auto corner on length=\meta{dimension}} - This key has the following effect: Firstly, the \TeX-if + 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 + 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. @@ -421,10 +420,10 @@ this command describes the decoration automaton. next state. For this, the following two options are useful: \begin{key}{/pgf/decoration automaton/persistent precomputation=\meta{precode}} - If the \meta{code} of state is executed, the \meta{precode} is - executed first and it executed outside the \TeX-group of the + 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 setup. + transformation matrix is not set up. \end{key} \begin{key}{/pgf/decoration automaton/persistent postcomputation=\meta{postcode}} @@ -588,7 +587,7 @@ Once a decoration has been declared, it can be used. \item The decoration automata move along the input paths, thus creating (and possibly using) the output paths. These output paths extend - (unless they are used) the current path. + the current path (unless they are used). \end{enumerate} Some important points should be noted regarding the use of this @@ -597,18 +596,18 @@ Once a decoration has been declared, it can be used. \begin{itemize} \item If \meta{environment contents} does not begin with - |\pgfpathmoveto|, he last known point on the preexisting path is + |\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 end of \meta{environment contents} are + 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, + 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 @@ -617,16 +616,16 @@ Once a decoration has been declared, it can be used. 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 commences with a line-to or curve-to when the + 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 commences. + 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} - When the decoration automata ``work on'' their respective input - paths, before the automaton starts, \meta{before code} is +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. @@ -733,7 +732,7 @@ Once a decoration has been declared, it can be used. \end{command} The following style is executed each time a decoration is used. You - may use it to setup default options for decorations. + 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} @@ -822,8 +821,7 @@ 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, before a -meta-decoration can be used it must be declared. +their own decoration. Like ordinary decorations, a meta-decoration must be declared before it can be used. \subsubsection{Declaring Meta-Decorations} @@ -886,7 +884,7 @@ meta-decoration can be used it must be declared. \end{command} \begin{command}{\beforedecoration\marg{before code}} - Defines \marg{before code} as (typically) \pgfname{} commands to be + 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 @@ -895,7 +893,7 @@ meta-decoration can be used it must be declared. \end{command} \begin{command}{\afterdecoration\marg{after code}} - Defines \marg{after code} as commands to be executed after the + 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} |