From 0c242425bcb89cc3af3064b8b895608a7f5ec3bb Mon Sep 17 00:00:00 2001
From: Karl Berry <karl@freefriends.org>
Date: Fri, 16 Jul 2010 23:47:14 +0000
Subject: pgfplots 1.4 (14jul10)

git-svn-id: svn://tug.org/texlive/trunk@19488 c570f23f-e606-0410-a88d-b1316a301751
---
 .../pgfplots/pgfplots.reference.alignment.tex      | 301 ++++++++++++++++-----
 1 file changed, 233 insertions(+), 68 deletions(-)

(limited to 'Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex')

diff --git a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex
index 9386714999c..593f7961b80 100644
--- a/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex
+++ b/Master/texmf-dist/doc/latex/pgfplots/pgfplots.reference.alignment.tex
@@ -128,7 +128,37 @@ And finally, we have origin anchors which are especially useful when axis lines
 				\showit{origin}{135}
 			\end{tikzpicture}
 		\end{center}
-The default value is |anchor=south west|. You can use anchors in conjunction with the \Tikz\ |baseline| option and/or |\begin{pgfinterruptboundingbox}| to perform alignment.
+
+		\noindent There is a fifth anchor which is not directly related to the axis: you can provide the anchor of \emph{a named inner node}. Thus, you can define your own anchor, by writing |\node (|\meta{name}|) at |\parg{point coordinate}| {};| as follows (using the |baseline| option described below):
+\begin{codeexample}[]
+Aligning at .......
+\begin{tikzpicture}[baseline]
+\begin{axis}[small,anchor=aninnernode.center]
+	\addplot {sin(deg(x))};
+	\node
+		[pin=-90:(aninnernode),fill=black,circle,scale=0.3] 
+		(aninnernode) at (axis cs:-2,0.75) {};
+	\draw[help lines] (axis cs:-6,0.75) -- (axis cs:6,0.75);
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+\noindent What happens is that a node is placed at |(axis cs:-2,0.75)|. Note that the options |[pin=...]| are merely to show the |\node| (the pin style has been defined by the \PGFPlots\ manual). Since a name can also be assigned using |name=|\meta{node's name} and since any \PGFPlots\ description is also a |\node|, you can align your plot at selected axis descriptions:
+\begin{codeexample}[]
+Aligning at .......
+\begin{tikzpicture}[baseline]
+\begin{axis}[
+	small,
+	title={The function $\sin x$ is very pretty.},
+	title style={name=MyTitleNode},
+	anchor=MyTitleNode.base,
+]
+	\addplot {sin(deg(x))};
+\end{axis}
+\end{tikzpicture}
+\end{codeexample}
+
+The default value is |anchor=south west|. 
+You can use anchors in conjunction with the \Tikz\ |baseline| option and/or |\begin{pgfinterruptboundingbox}| to perform alignment.
 
 \paragraph{Remarks:} Each of the anchors on the axis rectangle has an equivalent to a coordinate in the |axis description cs| described in section~\ref{pgfplots:sec:axis:description:cs}. That means the first set of anchors actually lives on the \emph{tight bounding box around the axis} (without any ticks or descriptions). The |south west| anchor will always be the lower left corner of this bounding box, even in case of a rotated or skewed coordinate system\footnote{Note that this is only true for versions since 1.3.}. Similar statements hold for the other anchors.
 }
@@ -180,7 +210,14 @@ The |baseline| key is related to |\begin{minipage}|\oarg{align how} or |\begin{t
 
 \subsubsection{Horizontal Alignment}
 \label{sec:halign}%
-If you place multiple |axes| into a single |tikzpicture| and use the `|anchor|'-option, you can control horizontal alignment:
+Horizontal alignment can be done in two ways:
+\begin{enumerate}
+	\item Using separate |tikzpicture| environments which have reduced bounding boxes or
+	\item A single |tikzpicture| environment in which the complete alignment is done.
+\end{enumerate}
+The first approach requires the use of reduced bounding boxes and is discussed in Section~\ref{sec:bb}.
+
+The second approach, a single |tikzpicture| environment, employs the |at| and |anchor| keys to align parts of the images. For example, if you place multiple |axes| into a single |tikzpicture| and use the `|anchor|'-option, you can control horizontal alignment:
 \begin{codeexample}[]
 \begin{tikzpicture}
 \pgfplotsset{every axis/.append style={
@@ -202,11 +239,8 @@ cycle list={
 	(0.109967,	1.000027)};
 \end{axis}
 
-% introduce named coordinate:
-\path (main plot.below south west) ++(0,-0.1cm) 
-	coordinate (lower plot position);
-
-\begin{axis}[at={(lower plot position)},
+\begin{axis}[
+	at={(main plot.below south west)},yshift=-0.1cm,
 	anchor=north west,
 	width=4cm,scale only axis,height=0.8cm,
 	ytick=\empty]
@@ -220,13 +254,153 @@ cycle list={
 \end{codeexample}
 
 
+\subsubsection{Alignment In Array Form (Subplots)}
+\label{sec:pgfplots:arrayform}
+\index{Subplots}%
+\index{Alignment!Subplots}%
+\index{Alignment!Array}%
+\index{array!Array Alignment}%
+\pgfmanualpdflabel{\textbackslash matrix}{}%
+Sometimes multiple alignment axes in array form are desired. \PGFPlots\ supports this task in several ways which are described in the following. There are basically three related, yet different, approaches:
+\begin{enumerate}
+	\item Simply place |\begin{tikzpicture}...\end{tikzpicture}| into a \LaTeX\ table.
+	This is straight--forward; you would do the very same thing with |\includegraphics|. 
+
+	In addition to |\includegraphics|, the |baseline| feature allows simple yet effective vertical alignment. At the time of this writing, the experimental \PGF\ version available from |texexample.net| also supports the |trim left| and |trim right| features which allow simple yet effective horizontal alignment (see below).
+
+	\item Use a \emph{single} picture which contains an array of axes, i.e.\ a pattern like
+
+	|\begin{tikzpicture} \matrix{ |\meta{multiple axes}|}; \end{tikzpicture}|.
+
+	This allows considerably simpler alignment! Alas, it needs special handling for |legend entries| due to a weakness of |\matrix|. If you use the |external| library (which is recommended), it takes more time since the picture gets larger.
+
+	\item Use the |groupplots| library shipped with \PGFPlots. It is specialized on axes in array form with particular strength if the axes are closely related (for example if they share axis descriptions like |xlabel| or even tick labels). Note, however, that the other approaches are better when it comes to automatic handling of bounding boxes.
+\end{enumerate}
+The |groupplots| library is discussed in all detail in Section~\ref{sec:group:plot}. This section discusses the other two approaches.
+
+
+\paragraph{Array Alignment using \LaTeX\ Tables}
+The idea is simple: use a \LaTeX\ table and provide one |tikzpicture| for every cell. You are probably familiar with this sort of alignment, perhaps together with |\includegraphics|. It works in the very same way for \PGFPlots. The approach is the simplest one since it doesn't need special knowledge. Its disadvantage, however, is more difficulty to control positions \emph{inside} of the image (like differently sized axis descriptions).
+
+Is is strongly recommended to employ the |baseline| option for each cell picture, which simplifies vertical alignment considerably. If you want a simple solution to place separate axes in array form, and you prefer to use one |tikzpicture| for every axis, the probably most simple and most effective way to realize horizontal alignment is the |trim left| and |trim right| feature. Unfortunately, it will only be available as part of the \emph{next} stable \PGF\ release (or available as part of the experimental \PGF\ version from |texample.net|). Since I am aware of many users who downloaded the experimental \PGF\ version, I document it here as well. 
+
+The |trim left| feature can be used to exclude axis descriptions on the left from the bounding box, and the |trim right| can exclude axis descriptions on the right from the bounding box. Thus, alignment is done using the vertical axis lines. Since both keys effectively modify the bounding box, they are documented in Section~\ref{sec:bb} ``Bounding Box Restrictions''. Here is just a small example for array alignment by means of |tabular|, |baseline| and the |trim| features:
+
+\begin{codeexample}[vbox]
+\pgfplotsset{
+	small,
+	title=Requires experimental PGF!
+}
+\begin{center}
+\begin{tabular}{rl}
+	\begin{tikzpicture}[baseline,trim axis left]
+		\begin{axis}
+			\addplot {x};
+		\end{axis}
+	\end{tikzpicture}
+	&
+	\begin{tikzpicture}[baseline,trim axis right]
+	\begin{axis}[
+		ylabel={$f(x)=x^2$},
+		yticklabel pos=right,
+		ylabel style={font=\Huge}]
+		\addplot {x^2};
+	\end{axis}
+	\end{tikzpicture}
+	\\
+	%
+	\begin{tikzpicture}[baseline,trim axis left]
+	\begin{axis}[xlabel=$x$,xlabel style={font=\Huge}]
+		\addplot {x^3};
+	\end{axis}
+	\end{tikzpicture}%
+	&
+	\begin{tikzpicture}[baseline,trim axis right]
+	\begin{axis}[yticklabel pos=right]
+		\addplot {x^4};
+	\end{axis}
+	\end{tikzpicture}%
+	\\
+\end{tabular}%
+\end{center}
+\end{codeexample}
+\noindent The example has $2 \times 2$ axes. The |baseline| feature controls the vertical alignment: the lower axis lines are always on the same height. The |trim axis left| key is a style which tells \Tikz\ to trim everything which is left of the left axis line. Similarly, the |trim axis right| key does not include picture parts right of the right axis line. Together with |\begin{center}| and the |yticklabel pos=right| key, we get correct horizontal and vertical alignment together with centering at the left- and right axis lines (without descriptions).
+
+A strong advantage is that this type of alignment requires almost no changes to your pictures. Thus, you can copy--paste existing images (\TeX\ code) relatively simple.
+
+Note that the approach is fully compatible with the image |external|ization library: each picture is exported separately, and the bounding box restrictions (and the |baseline| offset) are stored in separate |.dpth| files. The |trim left| / |trim right| approach for horizontal alignment is the \emph{only} supported way for reduced bounding boxes and image externalization.
+
+Unfortunately, |trim left| and |trim right| are not shipped with \PGFPlots\ and will be part of the next stable \Tikz\ release.
+
+
+\paragraph{Array Alignment using \Tikz\ Matrices}
+While it is possible to use (for example) |tabular| combined with the vertical and horizontal alignment methods discussed above, it might be better to use a \Tikz\ |matrix| since it automatically handles the size of axis descriptions.
+
+A \Tikz\ matrix is some sort of ``graphical'' table. It knows everything about picture alignment and it has more flexibility than |tabular| when it comes to graphics. The idea is to pack the complete array into a \emph{single} picture.
+
+The complete documentation of a \Tikz\ matrix is beyond the scope of this manual, please refer to \cite{tikz} for details. But we provide an example here:
+\pgfmanualpdflabel{/tikz/matrix}{}%
+\begin{codeexample}[]
+\begin{tikzpicture}
+	\pgfplotsset{small}
+	\matrix {
+		\begin{axis}
+			\addplot {x};
+		\end{axis}
+		&
+		% differently large labels are aligned automatically:
+		\begin{axis}[ylabel={$f(x)=x^2$},ylabel style={font=\Huge}]
+			\addplot {x^2};
+		\end{axis}
+		\\
+		%
+		\begin{axis}[xlabel=$x$,xlabel style={font=\Huge}]
+			\addplot {x^3};
+		\end{axis}
+		&
+		\begin{axis}
+			\addplot {x^4};
+		\end{axis}
+		\\
+	};
+\end{tikzpicture}
+\end{codeexample}
+\noindent So, a matrix is a picture element inside of |tikzpicture|. Its cells are separated by `|&|' as in tabular (or, if `|&|' causes problems, with |\pgfmatrixnextcell|). Its rows are separated by `|\\|'. Each cell is aligned using the cells' anchor. Since, by default, the anchor of an axis is placed at the lower left corner, the example above is completely aligned, without the need for any bounding box modifications -- even the labels are aligned correctly. If another anchor shall be used, simply place 
+\begin{codeexample}[code only]
+\pgfplotsset{anchor=....}
+\matrix {
+  ...
+};
+\end{codeexample}
+\noindent in front of the matrix. This will use the same configuration for every sub-plot.
+
+\paragraph{Attention:} Unfortunately, the array alignment with |\matrix| need special \emph{attention with legends}. A legend is also a |\matrix| and \Tikz\ matrizes can't be nested. You will need to use the |legend to name| feature (or to assemble a legend by means of |\label| and |\ref|) to overcome this weakness (see Section~\ref{pgfplots:legend:labelref} for details). 
+
+
+\subsubsection{Miscellaneous for Alignment}
+
+\begin{predefinednode}{current axis}
+	A node which refers to the current axis or the last typeset axis.
+
+	You can use this node in axis descriptions, for example to place axis labels or titles.
+
+	\paragraph{Remark:} If you use |current axis| inside of axis descriptions, the ``current axis'' is not yet finished. That means you \emph{can't use any outer anchor} inside of axis descriptions.
+
+	It is also possible to use |current axis| in any drawing or plotting commands inside of an axis (but no outer anchor as these are not defined when drawing commands are processed). This usage is similar to the |axis description cs|.
+\end{predefinednode}
+
 \subsubsection{Bounding box restrictions}
+\label{sec:bb}
 Bounding box restrictions can be realized with several methods of \PGF:
 \begin{enumerate}
 	\item The |overlay| option,
 	\item The |pgfinterruptboundingbox| environment,
-	\item The |\useasboundingbox| path.
+	\item The |\pgfresetboundingbox| command,
+	\item The |\useasboundingbox| path,
+	\item The |trim left| and |trim right| feature (which is the \emph{only} supported way of restricted bounding boxes and image externalization; at least for pdf output). 
 \end{enumerate}
+Note that image externalization (the |external| library) is more or less incompatible with methods (1.)--(4.). The problem is that |pdflatex| crops everything outside of the bounding box away. There are only two safe ways to ``restrict'' bounding boxes of external |.pdf| images: the first is the mentioned |trim left| / |trim right| feature and the second is to use negative |\hspace| or |\vspace| commands (or options to |\includegraphics|). Unfortunately, the |trim left| / |trim right| feature is currently unavailable, it needs a more recent \PGF\ version than the current stable release \PGF\ $2.00$ (I only mention the method here because many users downloaded a more recent \PGF\ from \url{http://www.texample.net/tikz/builds/}).
+
 \begin{key}{/tikz/overlay}
 \index{Bounding Box Control!Excluding Image Parts}
 	A special key of \PGF\ which disables bounding box updates for (parts of) the image. The effect is that those parts are an ``overlay'' over the document.
@@ -277,6 +451,36 @@ The following example places a legend somewhere without affecting the bounding b
 	More information about the |overlay| option can be found in the \PGF\ manual~\cite{tikz}.
 \end{key}
 
+\begin{command}{\pgfresetboundingbox}
+	This command of \pgfname\ resets the bounding box of the current picture. The computation starts from scratch afterwards, allowing to compute a user--defined bounding box.
+	
+\begin{codeexample}[]
+\setlength{\fboxsep}{0pt}%
+\fbox{%
+\begin{tikzpicture}%
+	\begin{axis}[
+		title=A title,
+		xlabel={$x$},
+		ylabel={$y$},
+		legend style={at={(0.5,0.97)},
+			anchor=north,legend columns=-1},
+		domain=-2:2
+	]
+	\addplot {x^2};
+	\addplot {x^3};
+	\addplot {x^4};
+	\legend{$x^2$,$x^3$,$x^4$}
+	\end{axis}
+
+	\pgfresetboundingbox
+	\path
+			  (current axis.south west)
+	rectangle (current axis.north east);
+\end{tikzpicture}%
+}%
+\end{codeexample}%
+	The example draws a normal picture, containing an axis. Afterwards, it throws the bounding box away and creates a new one based on the |current axis| node and its anchors.
+\end{command}
 
 \begin{environment}{{pgfinterruptboundingbox}}
 \label{sec:bounding:box:example}%
@@ -284,14 +488,13 @@ The following example places a legend somewhere without affecting the bounding b
 \index{Bounding Box Control!pgfinterruptboundingbox}
 {%
 \pgfmanualpdflabel{\textbackslash useasboundingbox}{}%
-An alternative to |overlay| is shown below: the figure has a truncated bounding box with is shown using |\fbox|.
+	Yet another approach with the same effect is shown below: the bounding box is interrupted manually, and resumed afterwards.
 \begin{codeexample}[]
 \setlength{\fboxsep}{0pt}%
 \fbox{%
 \begin{tikzpicture}%
 	\begin{pgfinterruptboundingbox}
 	\begin{axis}[
-		name=my plot,
 		title=A title,
 		xlabel={$x$},
 		ylabel={$y$},
@@ -307,8 +510,8 @@ An alternative to |overlay| is shown below: the figure has a truncated bounding
 	\end{pgfinterruptboundingbox}
 
 	\useasboundingbox 
-			  (my plot.below south west)
-	rectangle (my plot.above north east);
+			  (current axis.below south west)
+	rectangle (current axis.above north east);
 \end{tikzpicture}%
 }%
 \end{codeexample}%
@@ -316,68 +519,30 @@ An alternative to |overlay| is shown below: the figure has a truncated bounding
 The |pgfinterruptboundingbox| environment does not include its content into the image's bounding box, and |\useasboundingbox| sets the pictures bounding box to the following argument (see~\cite{tikz}).
 \end{environment}
 
-\end{pgfplotskey}
+\begin{keylist}{%
+	/tikz/trim left=\marg{$x$ coordinate or point} (default 0pt),
+	/tikz/trim right=\marg{$x$ coordinate or point}}
+	These two keys allow to reduce the size of the bounding box.
 
-\subsubsection{Alignment In Array Form (Subplots)}
-\index{Subplots}%
-\index{Alignment!Subplots}%
-\index{Alignment!Array}%
-\index{array!Array Alignment}%
-\pgfmanualpdflabel{\textbackslash matrix}{}%
-Sometimes alignment in array form is desired. One can use the following approach or use the library |groupplots| on page \ref{sec:group:plot} which does
-not utilize \Tikz\ matrices. 
+	{\bfseries They are only available in the experimental version of \PGF, not in \PGF\ 2.00! You may need the \PGF\ version from |texexample.net|!}
 
-While it is possible to use (for example) |tabular| combined with the vertical and horizontal alignment methods discussed above, it might be better to use a \Tikz\ |matrix|.
+	The |trim left| key expects either a single $x$ coordinate like |1cm| or a point like |(current axis.west)|. If a point is provided, is uses only the $x$ coordinate of that point. Then, the left end of the bounding box is set to the resulting $x$ coordinate and everything left of it is outside of the bounding box.
 
-A \Tikz\ matrix is some sort of ``graphical'' table. It knows everything about picture alignment and it has more flexibility than |tabular|. The complete documentation of a \Tikz\ matrix is beyond the scope of this manual, please refer to \cite{tikz} for details. But we provide an example here:
-\pgfmanualpdflabel{/tikz/matrix}{}%
-\begin{codeexample}[]
-\begin{tikzpicture}
-	\matrix {
-		\begin{axis}
-			\addplot {x};
-		\end{axis}
-		&
-		% differently large labels are aligned automatically:
-		\begin{axis}[ylabel={$f(x)=x^2$},ylabel style={font=\Huge}]
-			\addplot {x^2};
-		\end{axis}
-		\\
-		%
-		\begin{axis}[xlabel=$x$,xlabel style={font=\Huge}]
-			\addplot {x^3};
-		\end{axis}
-		&
-		\begin{axis}
-			\addplot {x^4};
-		\end{axis}
-		\\
-	};
-\end{tikzpicture}
-\end{codeexample}
-\noindent So, a matrix is a picture element inside of |tikzpicture|. Its cells are separated by `|&|' as in tabular (or, if `|&|' causes problems, with |\pgfmatrixnextcell|). Its rows are separated by `|\\|'. Each cell is aligned using the cells' anchor. Since, by default, the anchor of an axis is placed at the lower left corner, the example above is completely aligned, without the need for any bounding box modifications -- even the labels are aligned correctly. If another anchor shall be used, simply place 
-\begin{codeexample}[code only]
-\pgfplotsset{anchor=....}
-\matrix {
-  ...
-};
-\end{codeexample}
-\noindent in front of the matrix. This will use the same configuration for every sub-plot.
-
-\paragraph{Attention:} Unfortunately, the array alignment with |\matrix| is \emph{incompatible} with legends. A legend is also a matrix and, unfortunately,
-\Tikz\ matrizes can't be nested. Of course, this does not affect the manually created legends by means of |\label| and |\ref|, see
-section~\ref{pgfplots:legend:labelref} for details. 
+	The |trim right| key has the same effect, only for the right end of the bounding box.
 
-If one wishes to have an easier approach of aligning one should refer to the library |groupplots| on p. \ref{sec:group:plot}.
 
-\subsubsection{Miscellaneous for Alignment}
+	More detailed documentation can be found in the \Tikz\ manual.
+\end{keylist}
 
-\begin{predefinednode}{current axis}
-	A node which refers to the current axis or the last typeset axis.
+\begin{stylekey}{/tikz/trim axis left}
+	A style with value |trim left=(current axis.south west)|.
 
-	You can use this node in axis descriptions, for example to place axis labels or titles.
+	The style needs to be provided as argument to |\begin{tikzpicture}[trim axis left]|. It expects (at least) one \PGFPlots\ environment in the picture. The effect is to trim everything which is left of the last axis' anchor |south west| (i.e.\ everything left of the left axis boundary).
+\end{stylekey}
 
-	\paragraph{Remark:} If you use |current axis| inside of axis descriptions, the ``current axis'' is not yet finished. That means you \emph{can't use any outer anchor} inside of axis descriptions.
+\begin{stylekey}{/tikz/trim axis right}
+	A style with value |trim right=(current axis.south east)|.
 
-	It is also possible to use |current axis| in any drawing or plotting commands inside of an axis (but no outer anchor as these are not defined when drawing commands are processed). This usage is similar to the |axis description cs|.
-\end{predefinednode}
+	It works similarly to |trim axis left|: the effect is that everything right of the right axis line of the last axis environment is truncated from the bounding box.
+\end{stylekey}
+\end{pgfplotskey}
-- 
cgit v1.2.3

