[plotting] annotations and an important box

plotting/lecture/plotting.tex

@@ -502,6 +502,45 @@ used cells of the grid by passing a vector as the third argument to
 
 \subsection{Annotations, text}
 
+Sometimes want to highlight certain parts of a plot or simply add an
+annotation that does not fit or belong to the legend. In these cases
+we can use the \code[text()]{text()} or
+\code[annotation()]{annotation()} function to add this information to
+the plot. While \varcode{text} simply prints out the given text string
+at the defined position (for example line in
+listing\,\ref{regularsubplotlisting}) the \varcode{annotation}
+function allows to add some more advanced highlights like arrows,
+lines, elipses, or rectangles. Figure\,\ref{annotationsplot} shows
+some examples, the respective code can be found in
+listing\,\ref{annoationsplotlisting}. For more options consult the
+documentation.
+
+\begin{figure}[ht]
+  \includegraphics[width=0.5\linewidth]{annotations}
+  \titlecaption{Annotations in a plot.}{See
+    listing\,\ref{annotationsplotlisting}}\label{annotationsplot}
+\end{figure}
+
+\lstinputlisting[caption={Adding annotations to figures. Script that
+    creates \figref{annotationsplot}.},
+  label=annotationsplotlisting,
+  basicstyle=\ttfamily\scriptsize]{annotations.m}
+
+\begin{important}[Positions in data or figure coordinates.]
+  A very confusing pitfall are the different coordinate systems used
+  by \varcode{text} and \varcode{annotation}. While text expects the
+  positions to be in data coordinates, i.e.\,in the limits of the x-
+  and y-axis, \varcode{annotation} requires the positions to be given
+  in normalized figure coordinates. Normalized means that the width
+  and height of the figure are expressed by numbers in the range 0 to
+  1. The bottom/left corner then has the coordinates $(0,0)$ and the
+  top/right corner the $(1,1)$.
+
+  Why different coordinate systems? Using data coordinates is
+  convenient for annotations within a plot, but what about an arrow
+  that should be drawn between two subplots? 
+\end{important}
+
 \subsection{Error bars and error areas}
 
 \subsection{Scatter plot}