added codeexample plus some text to the decorations library manua…

…l as suggested in pull request pgf-tikz#872

doc/generic/pgf/text-en/pgfmanual-en-library-decorations.tex

@@ -106,6 +106,28 @@ \subsection{Overview and Common Options}
 \end{key}
 
 
+\subsection{Handling ``Dimension too large error''s}
+
+In case you should run into a ``Dimension too large error'' when using the
+|decorations| libraries, there is a pretty high chance that you can resolve
+this by using the |fpu| library in combination with
+|/pgf/fpu/install only={reciprocal}|. Please note that this key should only be
+applied locally to avoid other errors (see also at the definition of this key
+on page~\pageref{fpu-install-only}).
+%
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.markings,fpu}}]
+\begin{tikzpicture}
+  \begin{scope}[/pgf/fpu/install only={reciprocal}]
+    \draw[postaction=decorate,decoration={
+        markings,mark=at position 0.52 with {
+            \draw circle[radius=2pt];
+        }},
+    ] plot[smooth,variable=\x,domain=-1:1] (\x*\x*\x,\x*\x);
+  \end{scope}
+\end{tikzpicture}
+\end{codeexample}
+
+
 \subsection{Path Morphing Decorations}
 
 \begin{pgflibrary}{decorations.pathmorphing}

doc/generic/pgf/text-en/pgfmanual-en-library-fpu.tex

@@ -148,25 +148,30 @@ \subsection{Usage}
 \end{command}
 
 \begin{key}{/pgf/fpu/install only=\marg{list of names}}
+    \label{fpu-install-only}
     Unfortunately, the FPU is currently incompatible with drawing operations.
     However, it can still be useful to replace single definitions with FPU
-    counterparts to avoid errors of the kind |Dimension too large| which tend to
-    happen when transformation matrices are inverted.
+    counterparts to avoid errors of the kind |Dimension too large| which tend
+    to happen when transformation matrices are inverted.
 
-    This key allows to specify a list of definitions to be pulled into the current
-    scope.  \emph{Note that there is no reverse operation to uninstall these
-      definitions at the moment}, so it is advisable to do this in a group.
-    Conveniently, \tikzname\ paths form an implicit group, so you can use this key
-    on a path as well.
+    This key allows to specify a list of definitions to be pulled into the
+    current scope.  \emph{Note that there is no reverse operation to uninstall
+    these definitions at the moment}, so it is advisable to do this in a group.
+    Conveniently, \tikzname{} paths form an implicit group, so you can use this
+    key on a path as well.
 
     You have to be aware of the limitations that the FPU imposes.  It will not
-    magically give TeX better precision, but it will avoid overflow or underflow
-    situation for large or small operands by rescaling them.  In the following
-    example, in the first case the FPU variant performs much better than the
-    normal variant, however, in the second case where a rescaling would not in
-    fact be needed the rescaling introduces a small round-off error.
-    %
-\begin{codeexample}[preamble={\usepgflibrary{fpu}},pre={\pgfkeys{/pgf/fpu=false}}]
+    magically give \TeX{} better precision, but it will avoid overflow or
+    underflow situation for large or small operands by rescaling them.  In the
+    following example, in the first case the FPU variant performs much better
+    than the normal variant, however, in the second case where a rescaling
+    would not in fact be needed the rescaling introduces a small round-off
+    error.
+    %
+\begin{codeexample}[
+    preamble={\usepgflibrary{fpu}},
+    pre={\pgfkeys{/pgf/fpu=false}},
+]
 \begingroup
 \pgfkeys{/pgf/fpu/install only={divide}}
 \pgfmathparse{12.34/0.001234}\pgfmathresult (good)