pgfplots (26oct12)

git-svn-id: svn://tug.org/texlive/trunk@28094 c570f23f-e606-0410-a88d-b1316a301751

1 files changed, 50 insertions, 27 deletions

diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex
index b6da2d73a6d..a5013fd13b0 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.specifyrange.tex
@@ -124,48 +124,43 @@ Enlarges the axis size for one axis (or all of them for |enlargelimits|) somewha
 
 You can set |xmin|, |xmax| and |ymin|, |ymax| to the minimum/maximum values of your data and |enlarge x limits| will enlarge the canvas such that the axis doesn't touch the plots.
 
-\begin{itemize}
-	\item The value \declaretext{true} enlarges the lower and upper limit.
-	\item The value \declaretext{false} uses tight axis limits as specified by the user (or read from input coordinates).
-	\item The value \declaretext{auto} will enlarge limits only for axis for which axis limits have been determined automatically.
+	 The value \declaretext{true} enlarges the lower and upper limit.
 
-	For three--dimensional figures, the \declaretext{auto} mechanism applies only for the $z$ axis. The $x$ and $y$ axis won't be enlarged. 
-	\item The value \declaretext{upper} enlarges only the upper axis limit while \declaretext{lower} enlarges only the lower axis limit.
-	\item Values like `|enlarge x limits=0.1|' will enlarge lower and upper axis limit relatively (in this example, $10\%$ of the axis limits will be added on both sides).
-	\item It is also possible to change just the relative threshold using the \declaretext{value=}\marg{val} key. It can be combined with any of the other possible values. For example, 
-
-		|\pgfplotsset{enlarge x limits={value=0.2,upper}}|
-	
-	will enlarge (only) the upper axis limit by $20\%$ of the axis range. Another example is
-
-		|\pgfplotsset{enlarge x limits={value=0.2,auto}}|
-
-	which changes the default threshold of the \declaretext{auto} value to $20\%$.
-	\item While |value| uses relative thresholds, \declaretext{abs value} is used in the same way with absolute values.
+	 The value \declaretext{false} uses tight axis limits as specified by the user (or read from input coordinates).
 
-	\paragraph{Attention:} |abs value| is applied \emph{multiplicative} for logarithmic axes! That means |abs value=10| for a logarithmic axis adds $\log 10$ to upper and/or lower axis limits.
-
-	\item Finally, \declaretext{abs=}\marg{value} is the same as |true,abs value=|\marg{value} and \declaretext{rel=}\marg{value} is the same as |true,value=|\marg{value}.
-\end{itemize}
+	 The value \declaretext{auto} will enlarge limits only for axis for which axis limits have been determined automatically.
+	For three--dimensional figures, the \declaretext{auto} mechanism applies only for the $z$ axis. The $x$ and $y$ axis won't be enlarged. 
 \begin{codeexample}[]
 \begin{tikzpicture}
-	\begin{axis}
+	\begin{axis}[small]
 		\addplot {5 * x^3 - x^2 + 4*x -2};
 	\end{axis}
 \end{tikzpicture}
 \end{codeexample}
 
+
+	 Specifying a number \declaretext{val}ue like `|enlarge x limits=0.2|' will enlarge lower and upper axis limit relatively. The following example adds $20\%$ of the axis limits on both sides:
 \begin{codeexample}[]
 \begin{tikzpicture}
-	\begin{axis}[enlarge x limits=0.2]
+	\begin{axis}[small,enlarge x limits=0.2]
 		\addplot {5 * x^3 - x^2 + 4*x -2};
 	\end{axis}
 \end{tikzpicture}
 \end{codeexample}
+	\noindent The choice \declaretext{rel=}\marg{value} is the same as |true,value=|\marg{value}, i.e.\ it activates relative enlargement for both |upper| and |lower| limit.
+
+	 The value \declaretext{upper} enlarges only the upper axis limit while \declaretext{lower} enlarges only the lower axis limit. In this case, the amount added to the respective limit can be specified using the \declaretext{value=}\marg{val} key. It can be combined with any of the other possible values. For example, 
+
+		|\pgfplotsset{enlarge x limits={value=0.2,upper}}|
+	
+	will enlarge (only) the upper axis limit by $20\%$ of the axis range. Another example is
 
+		|\pgfplotsset{enlarge x limits={value=0.2,auto}}|
+
+	which changes the default threshold of the \declaretext{auto} value to $20\%$.
 \begin{codeexample}[]
 \begin{tikzpicture}
-	\begin{axis}[minor x tick num=4,
+	\begin{axis}[small,minor x tick num=1,
 		enlarge x limits={rel=0.5,upper}
 	]
 		\addplot {5 * x^3 - x^2 + 4*x -2};
@@ -173,27 +168,55 @@ You can set |xmin|, |xmax| and |ymin|, |ymax| to the minimum/maximum values of y
 \end{tikzpicture}
 \end{codeexample}
 
+
+	 While |value| uses relative thresholds, \declaretext{abs value} accepts absolute values: it adds an absolute value to the selected axis. The choice \declaretext{abs=}\marg{value} is the same as |true,abs value=|\marg{value}, i.e.\ it adds an absolute value to both |upper| and |lower| limit:
 \begin{codeexample}[]
 \begin{tikzpicture}
-	\begin{axis}[minor x tick num=4,
+	\begin{axis}[small,minor x tick num=1,
 		enlarge x limits={abs=3}
 	]
 		\addplot {5 * x^3 - x^2 + 4*x -2};
 	\end{axis}
 \end{tikzpicture}
 \end{codeexample}
+	\noindent Here, we enlarged by $3$ units of the $x$ axis. Note that you can also specify \emph{dimensions} like |1cm|:
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\begin{axis}[small,minor x tick num=1,
+		enlarge x limits={abs=1cm}
+	]
+		\addplot {5 * x^3 - x^2 + 4*x -2}
+		  coordinate[pos=0] (first)
+		  coordinate[pos=1] (last);
+
+		\draw[red,->] (first) -- ++(-1cm,0pt);
+		\draw[red,->] (last) --  ++(1cm,0pt);
+	\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+	\noindent Technically, the use of absolute dimensions is a little bit different. For example, it allows to enlarge by more than |width| which is impossible for all other choices. \PGFPlots\ will try to fulfill both the provided |width|/|height| and the absolute axis enlargements. If it fails to do so, it will give up on |width|/|height| constraints and print a warning message to your log file. See also the key |enlargelimits respects figure size|.\index{Errors!enlargelimits respects figure size=true: could not respect the prescribed width/height}
 
+	\paragraph{Attention:} |abs value| is applied \emph{multiplicatively} for logarithmic axes! That means |abs value=10| for a logarithmic axis adds $\log 10$ to upper and/or lower axis limits.
 \begin{codeexample}[]
 \begin{tikzpicture}
-	\begin{loglogaxis}[enlarge x limits={abs=11}]
+	\begin{loglogaxis}[small,enlarge x limits={abs=11}]
 		\addplot+[domain=1:100000] {x^-2};
 	\end{loglogaxis}
 \end{tikzpicture}
 \end{codeexample}
 
-	Note that |enlargelimits| is applied before any changes to axis limits are considered as part of |scale mode|: |enlargelimits| will always be applied. Afterwards, the choice |scale mode=scale uniformly| will enlarge limits once more in order to satisfy all scaling constraints. The two limit enlargements are independent of each other, i.e.\ even if you say |enlargelimits=false|, |scale mode| will still increase axis limits if this seems to be necessary. See |scale mode| (especially |scale mode=units only|) and |unit rescale keep size| for detail on how to disable limit enlargement caused by |scale mode|.
+
+	Note that |enlargelimits| is applied before any changes to axis limits are considered as part of |scale mode|: |enlargelimits| will always be applied. Afterwards, the choice |scale mode=scale uniformly| will enlarge limits once more in order to satisfy all scaling constraints. The two limit enlargements are independent of each other, i.e.\ even if you say |enlargelimits=false|, |scale mode| will still increase axis limits if this seems to be necessary. An exception for this rule is enlarge-by-dimension, i.e.\ something like |abs=1cm| (see |enlargelimits respects figure size| for this case).
+	See |scale mode| (especially |scale mode=units only|) and |unit rescale keep size| for detail on how to disable limit enlargement caused by |scale mode|. 
 \end{pgfplotsxykeylist}
 
+\begin{pgfplotskey}{enlargelimits respects figure size=\mchoice{true,false} (initially true)}
+	A key which is \emph{only} used for something like |enlarge x limits={abs=1cm}|, i.e.\ for enlarge-by-dimension. It controls if \PGFPlots\ will try to respect |width|/|height|. You should probably always leave it as its default unless you run into problems.
+
+	If \PGFPlots\ fails to respect the figure size, it will print a warning message of sorts ``enlargelimits respects figure size=true: could not respect the prescribed width/height'' to your log file\index{Errors!enlargelimits respects figure size=true: could not respect the prescribed width/height}. 
+	
+\end{pgfplotskey}
+
 \begin{pgfplotsxykeylist}{%
 	log origin \x=\mchoice{0,infty} (initially infty),%
 	log origin=\mchoice{0,infty} (initially infty)}%