summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex')
-rw-r--r--Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex48
1 files changed, 32 insertions, 16 deletions
diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
index a51bcaed5b8..e81c8fcb7d2 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.basic.reference.tex
@@ -39,12 +39,25 @@ All collected = \allcollected.
\paragraph{Remark: } The special syntax \meta{list}=\meta{$x_0$}|,|\meta{$x_1$}|,...,|\meta{$x_n$}, i.e.\ with two leading elements, followed by dots and a final element, invokes the math parser for the loop. Thus, it allows larger number ranges than any other syntax if |/pgf/fpu| is active. In all other cases, |\pgfplotsforeachungrouped| invokes |\foreach| and provides the results without \TeX\ groups.
+ Keep in mind that inside of an axis environment, all loop constructions (including custom loops, |\foreach| and |\pgfplotsforeachungrouped|) need to be handled with care: loop arguments can only be used in places where they are immediately evaluated; but \PGFPlots\ postpones the evaluation of many macros. For example, to loop over something and to generate axis descriptions of the form |\node at (axis cs:\i,0.5)....|, the loop macro |\i| will be evaluated in |\end{axis}| -- but at that time, the loop is over and its value is lost. The correct way to handle such an application is to \emph{expand} the loop variable \emph{explicitly}. For example:
+\begin{codeexample}[code only]
+\pgfplotsforeachungrouped \i/\j in {
+ 1 / a,
+ 2 / b,
+ 3 / c
+}{
+ \edef\temp{\noexpand\node at (axis cs: \i,0.5) {\j};}
+ % \show\temp % lets TeX show you what \temp contains
+ \temp
+}
+\end{codeexample}
+ The example generates three loop iterations: |\i=1|, |\j=a|; then |\i=2|, |j=b|; then |\i=3|, |\j=c|. Inside of the loop body, it expands them and assigns the result to a macro using an ``expanded definition'', |\edef|. The result no longer contains either |\i| or |\j| (since these have been expanded). Then, it invokes the resulting macro. Details about the \TeX\ command |\edef| and expansion control can be found in the document \href{file:TeX-programming-notes.pdf}{TeX-programming-notes.pdf} which comes with \PGFPlots.
\end{command}
\begin{command}{\pgfplotsinvokeforeach\marg{list} \marg{command}}
A variant of |\pgfplotsforeachungrouped| (and such also of |\foreach|) which replaces any occurrence of |#1| inside of \meta{command} once for every element in \meta{list}. Thus, it actually assumes that \marg{command} is like a |\newcommand| body.
- In other words, \marg{command} is invoked for every element of \marg{list}. The actual element of \marg{list} is available as |#1|.
+ In other words, \meta{command} is invoked for every element of \meta{list}. The actual element of \meta{list} is available as |#1|.
As |\pgfplotsforeachungrouped|, this command does \emph{not} introduce extra scopes (i.e.\ it is ungrouped as well).
@@ -97,10 +110,10 @@ The result is `\pgfmathresult'.
\end{command}
\begin{command}{\pgfplotsiffileexists\marg{filename}\marg{true code}\marg{false code}}
- Invokes \marg{true code} if \marg{filename} exists and \marg{false code} if not. Can be used in looping macros, for example to plot every data file until there are no more of them.
+ Invokes \meta{true code} if \meta{filename} exists and \meta{false code} if not. Can be used in looping macros, for example to plot every data file until there are no more of them.
\end{command}
\begin{command}{\pgfplotsutilifstringequal\marg{first}\marg{second}\marg{true code}\marg{false code}}
- A simple ``strcmp'' tool which invokes \marg{true code} if \marg{first} $=$\marg{second} and \marg{false code} otherwise. This does not expand macros.
+ A simple ``strcmp'' tool which invokes \meta{true code} if \meta{first} $=$\meta{second} and \meta{false code} otherwise. This does not expand macros.
\end{command}
@@ -114,15 +127,15 @@ The result is `\pgfmathresult'.
\subsection[Commands Inside Of PGFPlots Axes]{Commands Inside Of {\normalfont\PGFPlots} Axes}
\begin{command}{\autoplotspeclist}
-This command should no longer be used, although it will be kept as technical implementation detail. Please use the `|cycle list|' option, section~\ref{sec:cycle:list}.
+This command should no longer be used, although it will be kept as technical implementation detail. Please use the `|cycle list|' option, Section~\ref{sec:cycle:list}.
\end{command}
\begin{command}{\logten}
-Expands to the constant $\log(10)$. Useful for logplots because $\log(10^i) = i\log(10)$. This command is only available inside of an \Tikz-picture.
+Expands to the constant $\log(10)$. Useful for logplots because $\log(10^i) = i\log(10)$. This command is only available inside of a \Tikz-picture.
\end{command}
\begin{command}{\pgfmathprintnumber\marg{number}}
-Generates pretty--printed output\footnote{This method was previously \texttt{\textbackslash prettyprintnumber}. It's functionality has been included into \PGF\ and the old command is now deprecated.} for \marg{number}. This method is used for every tick label.
+Generates pretty--printed output\footnote{This method was previously \texttt{\textbackslash prettyprintnumber}. Its functionality has been included into \PGF\ and the old command is now deprecated.} for \meta{number}. This method is used for every tick label.
The number is printed using the current number printing options, see the manual of \PGFPlotstable\ which comes with this package for the different number styles, rounding precision and rounding methods.
\end{command}
@@ -139,13 +152,13 @@ The number is printed using the current number printing options, see the manual
\end{command}
\begin{command}{\plotnumofactualtype}
- Like |\plotnum|, but it returns the number among all plots of the same type (see |\numplotsofactualtype|).
+ Like |\plotnum|, but it returns the number among all plots of the same type. The number of all such plots is available using |\numplotsofactualtype|.
\end{command}
\begin{command}{\coordindex}
Inside of an |\addplot| command, this macro expands to the number of the actual coordinate (starting with~$0$).
- It is useful together with |x filter| or |y filter| to (de-)select coordinates.
+ It is useful together with |x filter| or |y filter| to (de)select coordinates.
\end{command}
\subsection{Path Operations}
@@ -174,12 +187,12 @@ The number is printed using the current number printing options, see the manual
}
\begin{keylist}{/tikz/xshift=\marg{dimension},/tikz/yshift=\marg{dimension}}
- These \Tikz\ keys allow to shift something by \marg{dimension} which is any \TeX\ size (or expression).
+ These \Tikz\ keys allow to shift something by \meta{dimension} which is any \TeX\ size (or expression).
\end{keylist}
\begin{command}{\pgfplotsextra\marg{low-level path commands}}
- A command to execute \marg{low-level path commands} in a \PGFPlots\ axis. Since any drawing commands inside of an axis need to be postponed until the axis is complete and the scaling has been initialised, it is not possible to simply draw any paths.
+ A command to execute \meta{low-level path commands} in a \PGFPlots\ axis. Since any drawing commands inside of an axis need to be postponed until the axis is complete and the scaling has been initialised, it is not possible to simply draw any paths.
Instead, it is necessary to draw them as soon as the axis is finished. This is done automatically for every \Tikz\ path -- and it is also done manually if you write |\pgfplotsextra|\marg{commands}.
\begin{codeexample}[]
\begin{tikzpicture}
@@ -192,7 +205,7 @@ The number is printed using the current number printing options, see the manual
\end{axis}
\end{tikzpicture}
\end{codeexample}
- The example above initialises an axis and executes the basic level path commands as soon as the axis is ready. The execution of multiple |\path|, |\addplot| and |\pgfplotsextra| commands is in the same sequence as they occur in the environment\footnote{Except for stacked plots where the sequence may be reverse, see the key \texttt{reverse stack plots}.}.%
+ The example above initializes an axis and executes the basic level path commands as soon as the axis is ready. The execution of multiple |\path|, |\addplot| and |\pgfplotsextra| commands is in the same sequence as they occur in the environment\footnote{Except for stacked plots where the sequence may be reverse, see the key \texttt{reverse stack plots}.}.%
\end{command}
\subsection{Specifying Basic Coordinates}
@@ -202,7 +215,7 @@ The number is printed using the current number printing options, see the manual
\pgfplotspointaxisxyz\marg{x coordinate}\marg{y coordinate}\marg{z coordinate}}
Point commands like |\pgfpointxy| which take logical, absolute coordinates and return a low--level point. Every transformation from user transformations to logarithms are applied.
- Since the transformations are initialised after the axis is complete, this command needs to be postponed (see |\pgfplotsextra|).
+ Since the transformations are initialized after the axis is complete, this command needs to be postponed (see |\pgfplotsextra|).
\end{commandlist}
\begin{commandlist}{%
@@ -218,9 +231,9 @@ The number is printed using the current number printing options, see the manual
\begin{commandlist}{%
\pgfplotspointdescriptionxy\marg{$x$ fraction}\marg{$y$ fraction},%
\pgfplotsqpointdescriptionxy\marg{$x$ fraction}\marg{$y$ fraction}}%
- Point commands such that |{0}{0}| is the lower left corner of the axis' bounding box and |{1}{1}| the upper right one; everything else is in-between. The `|q|' variant is quicker as it doesn't invoke the math parser on its arguments.
+ Point commands such that |{0}{0}| is the lower left corner of the axis' bounding box and |{1}{1}| the upper right one; everything else is in between. The `|q|' variant is quicker as it doesn't invoke the math parser on its arguments.
- They are used for |axis description cs|, see section~\ref{pgfplots:sec:axis:description:cs}.
+ They are used for |axis description cs|, see Section~\ref{pgfplots:sec:axis:description:cs}.
\end{commandlist}
\begin{commandlist}{%
@@ -257,7 +270,7 @@ The number is printed using the current number printing options, see the manual
The desired axis is uniquely identified by a three character string, provided as first argument to the command. The first of the three characters is `|0|' if the $x$ coordinate of the specified axis passes through the lower axis limit. It is `|1|', if the $x$ coordinate of the specified axis passes through the upper axis limit. Furthermore, it is `|2|' if it passes through the origin. The second character is also either |0|, |1| or |2| and it characterizes the position on the $y$ axis. The third character is for the third dimension, the $z$ axis. It should be left at `|0|' for two dimensional plots. However, \emph{one} of the three characters should be `|v|', meaning the axis \underline varies. For example, |v01| denotes $\{ (x,y_{\text{min}},z_{\text{max}}) \vert x \in \R \}$.
- The second argument, \meta{coordinate} is the logical coordinate on that axis. Since two coordinate of the axis are fixed, \meta{coordinate} refers to the \underline varying component of the axis. It must be a number without unit; no math expressions are supported here.
+ The second argument, \meta{coordinate} is the logical coordinate on that axis. Since two coordinates of the axis are fixed, \meta{coordinate} refers to the \underline varying component of the axis. It must be a number without unit; no math expressions are supported here.
The third argument \meta{normal distance} is a dimension like |10pt|. It shifts the coordinate away from the designated axis in direction of the outer normal vector. The outer normal vector always points away from the axis. It is computed using
|\pgfplotspointouternormalvectorofaxis|.
@@ -323,7 +336,7 @@ The number is printed using the current number printing options, see the manual
It is possible to use the result as arguments for the |\pgfpointxyz| commands.
- The effect is to multiply \marg{dimension} with the inverse length of the unit vector for the specified axis. These lengths are precomputed in \PGFPlots\ so the operation is fast.
+ The effect is to multiply \meta{dimension} with the inverse length of the unit vector for the specified axis. These lengths are precomputed in \PGFPlots\ so the operation is fast.
\begin{codeexample}[code only]
\pgfplotsconvertunittocoordinate{x}{5pt}
% now, the command uses exactly 5pt in x direction:
@@ -345,3 +358,6 @@ The number is printed using the current number printing options, see the manual
\begin{texif}{pgfplotsthreedim}
A \TeX\ |\if| which evaluates the \meta{true code} if the axis is three dimensional and the \meta{else code} if not.
\end{texif}
+
+\subsection{Accessing Axis Limits}
+It is also possible to access axis limits during the visualization phase, i.e.\ during |\end{axis}|. Please refer to the reference documentation for |xmin| on page~\pageref{page:access:limits}.