Initial commit

1 files changed, 694 insertions, 0 deletions

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
new file mode 100644
index 0000000000..cf20bc8476
--- /dev/null
+++ b/graphics/pgf/base/doc/text-en/pgfmanual-en-library-plot-handlers.tex
@@ -0,0 +1,694 @@
+% Copyright 2006 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}
+
+\label{key-bar-interval-shift}%
+\begin{key}{/pgf/bar interval shift=\marg{factor} (initially 0.5)}
+\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}
+
+\label{key-bar-interval-width}%
+\begin{key}{/pgf/bar interval width=\marg{scale} (initially 1)}
+\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: