Pimp codeexamples (issue #640)

doc/generic/pgf/extract.lua

@@ -149,18 +149,19 @@ local function walk(sourcedir, targetdir)
                     goto continue
                 end
 
-                -- Skip those that say "code only"
-                if not options["code only"] then
+                -- Skip those that say "code only" or "setup code"
+                if not options["code only"] and not options["setup code"] then
                     local newname = name .. "-" .. n .. ".tex"
                     local examplefile = io.open(targetdir .. newname, "w")
 
-                    examplefile:write"\\documentclass{article}\n"
+                    examplefile:write"\\documentclass{standalone}\n"
                     examplefile:write"\\usepackage{fp,pgf,tikz,xcolor}\n"
-                    examplefile:write(preamble) -- TODO: this has to go
+--                    examplefile:write(preamble) -- TODO: this has to go
+                    examplefile:write(setup_code)
                     examplefile:write(options["preamble"] and options["preamble"] .. "\n" or "")
                     examplefile:write"\\begin{document}\n"
-                    examplefile:write"\\makeatletter\n" -- TODO: this has to go
-                    examplefile:write(setup_code)
+--                    examplefile:write"\\makeatletter\n" -- TODO: this has to go
+
                     local pre = options["pre"] or ""
                     pre = pre:gsub("##", "#")
                     examplefile:write(pre .. "\n")

doc/generic/pgf/text-en/pgfmanual-en-base-actions.tex

@@ -348,7 +348,7 @@ \subsection{Arrow Tips on a Path}
 
     To ``clear'' the start arrow, say |\pgfsetarrowsstart{}|.
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}]
 \begin{pgfpicture}
   \pgfsetarrowsstart{Latex[length=10pt]}
   \pgfpathmoveto{\pgfpointorigin}
@@ -368,7 +368,7 @@ \subsection{Arrow Tips on a Path}
 \begin{command}{\pgfsetarrowsend\marg{end arrow tip specification}}
     Sets the arrow tip kind used at the end of a path.
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}]
 \begin{pgfpicture}
   \pgfsetarrowsstart{Latex[length=10pt]}
   \pgfsetarrowsend{Computer Modern Rightarrow}
@@ -385,7 +385,7 @@ \subsection{Arrow Tips on a Path}
     specification}|-|\meta{end arrow tip specification}. In this case, both the
     start and the end arrow specification are set:
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}]
 \begin{pgfpicture}
   \pgfsetarrows{Latex[length=10pt]->>}
   \pgfpathmoveto{\pgfpointorigin}
@@ -409,7 +409,7 @@ \subsection{Arrow Tips on a Path}
     This command is useful if you wish arrows or lines to ``stop shortly
     before'' a given point.
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usepgflibrary{arrows.meta}}]
 \begin{pgfpicture}
   \pgfpathcircle{\pgfpointorigin}{5mm}
   \pgfusepath{stroke}

doc/generic/pgf/text-en/pgfmanual-en-base-animations.tex

@@ -15,6 +15,10 @@ \section{Animations}
     This module contains the basic layer support of animations, which is
     documented in the following.
 \end{pgfmodule}
+%
+\begin{codeexample}[setup code,hidden]
+    \usepgfmodule{animations}
+\end{codeexample}
 
 This section described the basic layer support of animations, the \tikzname\
 support is described in Section~\ref{section-tikz-animations}. As always,
@@ -65,7 +69,11 @@ \subsection{Overview}
 you to create ``snapshots'' of animations. As an example, the following code
 shows how the same drawing is shown at different ``time snapshots'':
 %
-\begin{codeexample}[width=3.9cm]
+\begin{codeexample}[
+    width=3.9cm,
+    preamble={\usetikzlibrary{animations}
+\def\pgfname{\textsc{pgf}}
+}]
 \tikz [make snapshot of=0.5s] \scoped :rotate = { 0s = "0", 2s = "90" }
   \node [draw=blue, very thick] {\pgfname};
 \tikz [make snapshot of=1s]   \scoped :rotate = { 0s = "0", 2s = "90" }
@@ -464,7 +472,7 @@ \subsubsection{``Anti-Animations'': Snapshots}
     is used in a \TeX\ scope, no animation is created and no support by the
     driver is needed (so, it works with \textsc{pdf}).
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{animations}}]
 \tikz [make snapshot of=1s,
        animate = { myself: = {
          :rotate = { 0s = "0", 2s = "90" },
@@ -1113,11 +1121,15 @@ \subsection{Animating Transformations  and Views}
 
     In order to use a view, you first need to create a view, which is done
     using a |{pgfviewboxscope}|, see Section~\ref{section-base-view}, which is
-    used by the |view| library internally. You can then animate the view using
+    used by the |views| library internally. You can then animate the view using
     the |view| attribute. The values passed to the |entry| key must be two
     \pgfname-points, each surrounded by parentheses.
     %
-\begin{codeexample}[animation list={0.5,1,1.5,2},animation bb={(1.1,-0.9) rectangle (2.9,0.9)}]
+\begin{codeexample}[
+    preamble={\usetikzlibrary{views}},
+    animation list={0.5,1,1.5,2},
+    animation bb={(1.1,-0.9) rectangle (2.9,0.9)},
+]
 \tikz [very thick] {
   \pgfanimateattribute{view}{
     whom = me.view, begin on = {click, of next=node}, freeze at end,
@@ -1133,7 +1145,7 @@ \subsection{Animating Transformations  and Views}
 }
 \end{codeexample}
 
-\begin{codeexample}[width=2cm]
+\begin{codeexample}[width=2cm,preamble={\usetikzlibrary{views}}]
 \tikz [very thick] {
   \pgfanimateattribute{view}{
     whom = me.view, begin on = {click, of next=n1}, freeze at end,

doc/generic/pgf/text-en/pgfmanual-en-base-arrows.tex

@@ -567,10 +567,66 @@ \subsection{Declaring an Arrow Tip Kind}
   },
   defaults = { length = 4cm }
 }
-\begin{codeexample}[]
+\begin{codeexample}[
+    preamble={\usetikzlibrary{arrows.meta}},
+    pre={\pgfdeclarearrow{
+  name = foo,
+  parameters = { \the\pgfarrowlength },
+  setup code = {
+    % The different end values:
+    \pgfarrowssettipend{.25\pgfarrowlength}
+    \pgfarrowssetlineend{-.25\pgfarrowlength}
+    \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
+    \pgfarrowssetbackend{-.75\pgfarrowlength}
+    % The hull
+    \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
+    \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
+    \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
+    % Saves: Only the length:
+    \pgfarrowssavethe\pgfarrowlength
+  },
+  drawing code = {
+    \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}}
+    \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}}
+    \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}}
+    \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}}
+    \pgfpathclose
+    \pgfusepathqfill
+  },
+  defaults = { length = 4cm }
+}},
+]
 \tikz \draw [-foo] (0,0) -- (8,0);
 \end{codeexample}
-\begin{codeexample}[]
+\begin{codeexample}[
+    preamble={\usetikzlibrary{arrows.meta,bending}},
+    pre={\pgfdeclarearrow{
+  name = foo,
+  parameters = { \the\pgfarrowlength },
+  setup code = {
+    % The different end values:
+    \pgfarrowssettipend{.25\pgfarrowlength}
+    \pgfarrowssetlineend{-.25\pgfarrowlength}
+    \pgfarrowssetvisualbackend{-.5\pgfarrowlength}
+    \pgfarrowssetbackend{-.75\pgfarrowlength}
+    % The hull
+    \pgfarrowshullpoint{.25\pgfarrowlength}{0pt}
+    \pgfarrowshullpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}
+    \pgfarrowshullpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}
+    % Saves: Only the length:
+    \pgfarrowssavethe\pgfarrowlength
+  },
+  drawing code = {
+    \pgfpathmoveto{\pgfqpoint{.25\pgfarrowlength}{0pt}}
+    \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{.5\pgfarrowlength}}
+    \pgfpathlineto{\pgfqpoint{-.5\pgfarrowlength}{0pt}}
+    \pgfpathlineto{\pgfqpoint{-.75\pgfarrowlength}{-.5\pgfarrowlength}}
+    \pgfpathclose
+    \pgfusepathqfill
+  },
+  defaults = { length = 4cm }
+}},
+]
 \tikz \draw [-{foo[length=2cm,bend]}] (0,0) to [bend left] (3,0);
 \end{codeexample}
 
@@ -846,10 +902,13 @@ \subsubsection{Defining New Arrow Keys}
     |\pgfarrowstheparameters|. Here is an example, where |\showvalueofmacro| is
     used in this example to show the value stored in a macro:
     %
+\begin{codeexample}[setup code,hidden]
     \makeatletter
     \def\showvalueofmacro#1{%
         \texttt{\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\expandafter\pgfutil@gobble\expandafter\expandafter\expandafter\string\expandafter\csname#1\endcsname}
     }
+\end{codeexample}
+%
 \begin{codeexample}[]
 \pgfarrowsthreeparameters{2pt 1}
 \showvalueofmacro\pgfarrowstheparameters

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

@@ -16,6 +16,10 @@ \section{Decorations}
     need to load this module to use decorations. This module is automatically
     loaded by the different decoration libraries.
 \end{pgfmodule}
+%
+\begin{codeexample}[setup code,hidden]
+    \usetikzlibrary{decorations}
+\end{codeexample}
 
 
 \subsection{Overview}
@@ -24,14 +28,14 @@ \subsection{Overview}
 and, while doing so, either drawing something or constructing a new path. This
 could be as simple as extending a path with a ``zigzagged'' line\ldots
 %
-\begin{codeexample}[preamble={\usetikzlibrary{decorations,decorations.pathmorphing}}]
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
 \tikz \draw decorate[decoration=zigzag] {(0,0) -- (3,0)};
 \end{codeexample}
 %
 \ldots but could also be as complex as typesetting text along a path:
 %
 {\catcode`\|12
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.text}}]
 \tikz \path decorate [decoration={text along path,
      text={Some text along a path}}]
    { (0,2) .. controls (2,2) and (1,0) .. (3,0) };
@@ -285,7 +289,7 @@ \subsection{Declaring Decorations}
                 parts of the rest of the output path for the following
                 invocation. Here is an example:
                 %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{shapes.geometric}}]
 \pgfdeclaredecoration{stars}{initial}{
   \state{initial}[width=15pt]
   {
@@ -306,7 +310,6 @@ \subsection{Declaring Decorations}
         .. controls (0,-5) and (3,-5) .. (3,-3);
 \end{codeexample}
                 %
-
             \item After the \meta{code} has been executed (possibly more than
                 once, if the |repeat state| option is used), the state switches
                 to whatever state has been specified inside the \meta{options}
@@ -604,7 +607,7 @@ \subsection{Using Decorations}
     \meta{before code} is executed. After the decoration automaton has
     finished, \meta{after code} is executed.
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
 \begin{tikzpicture}[decoration={segment length=5pt}]
   \draw [help lines] grid (3,2);
   \begin{pgfdecoration}{{curveto}{1cm},{zigzag}{2cm},{curveto}{1cm}}
@@ -622,7 +625,7 @@ \subsection{Using Decorations}
     path. Thus, it is possible to specify lengths like
     |\pgfdecoratedpathlength/3|.
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
 \begin{tikzpicture}[decoration={segment length=5pt}]
   \draw [help lines] grid (3,2);
   \begin{pgfdecoration}{
@@ -653,7 +656,7 @@ \subsection{Using Decorations}
     This means that if decorations do not use their own path, it is possible to
     do something with them and continue from the correct place.
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
 \begin{tikzpicture}
   \draw [help lines] grid (3,2);
   \begin{pgfdecoration}{
@@ -764,7 +767,7 @@ \subsection{Using Decorations}
     Note when applying multiple decorations, this will be reset between
     decorations, so it needs to be specified for each segment.
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
 \begin{tikzpicture}
   \draw [help lines] grid (3,2);
   \begin{pgfdecoration}{
@@ -906,7 +909,7 @@ \subsubsection{Declaring Meta-Decorations}
 
     Here is a complete example of a meta-decoration:
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{decorations.pathmorphing}}]
 \pgfdeclaremetadecoration{arrows}{initial}{
   \state{initial}[width=0pt, next state=arrow]
   {

doc/generic/pgf/text-en/pgfmanual-en-base-images.tex

@@ -159,7 +159,7 @@ \subsection{Using an Image}
     The following example demonstrates the effect of using |\pgfuseimage|
     inside a colormixin environment.
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usepackage{xxcolor}}]
 \pgfdeclareimage[interpolate=true,width=1cm,height=1cm]
   {image1.!25!white}{brave-gnu-world-logo.25}
 \pgfdeclareimage[interpolate=true,width=1cm]
@@ -194,7 +194,7 @@ \subsection{Using an Image}
     You can ``save'' the image for later usage by invoking |\pgfaliasimage| on
     |pgflastimage|.
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usepackage{xxcolor}}]
 \begin{colormixin}{25!white}
 \begin{pgfpicture}
   \pgftext[at=\pgfpoint{1cm}{5cm},left,base]

doc/generic/pgf/text-en/pgfmanual-en-base-nodes.tex

@@ -212,7 +212,7 @@ \subsubsection{Creating Multi-Part Nodes}
     Finally, when the node is drawn, the boxes are placed at the anchor
     positions |text| and |lower|.
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{shapes}}]
 \setbox\pgfnodeparttextbox=\hbox{$q_1$}
 \setbox\pgfnodepartlowerbox=\hbox{01}
 \begin{pgfpicture}
@@ -552,7 +552,7 @@ \subsubsection{Referencing Anchors of Nodes in the Same Picture}
     |\pgfpointanchor| without any transformations in force. Here is an example:
     %
 \makeatletter
-\begin{codeexample}[]
+\begin{codeexample}[pre={\makeatletter}]
 \begin{pgfpicture}
   \pgftransformrotate{30}
   \pgfnode{rectangle}{center}{Hello World!}{x}{\pgfusepath{stroke}}
@@ -726,7 +726,7 @@ \subsection{Special Nodes}
     area. Note that excessive use of this option (keeping track of dozens of
     bounding boxes at the same time) will slow things down.
     %
-\begin{codeexample}[]
+\begin{codeexample}[preamble={\usetikzlibrary{scopes}}]
 \begin{tikzpicture}
   \draw [help lines] (0,0) grid (3,2);
   { [local bounding box=outer box]
@@ -1240,7 +1240,10 @@ \subsubsection{Command for Declaring New Shapes}
     on inheritance:
     %
 \makeatletter
-\begin{codeexample}[]
+\begin{codeexample}[
+    preamble={\usetikzlibrary{shapes.geometric}},
+    pre={\makeatletter},
+]
 \pgfdeclareshape{document}{
   \inheritsavedanchors[from=rectangle] % this is nearly a rectangle
   \inheritanchorborder[from=rectangle]

doc/generic/pgf/text-en/pgfmanual-en-base-patterns.tex

@@ -18,6 +18,10 @@ \subsection{Overview}
 shading, which means that the color changes smoothly between two (or more)
 different colors. Third, you can fill it using a tiling pattern and it is
 explained in the following how this is done.
+%
+\begin{codeexample}[setup code,hidden]
+    \usetikzlibrary{patterns}
+\end{codeexample}
 
 A tiling pattern can be imagined as a rectangular tile (hence the name) on
 which a small picture is painted. There is not a single tile, but
@@ -214,7 +218,34 @@ \subsection{Setting a Pattern}
     the \meta{color} parameter is ignored. For form-only patterns, the
     \meta{color} parameter specifies the color to be used for the pattern.
     %
-\begin{codeexample}[]
+\begin{codeexample}[
+    preamble={\pgfdeclarepatternformonly{stars}
+{\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
+{\pgfpoint{1cm}{1cm}}
+{
+  \pgftransformshift{\pgfpoint{.5cm}{.5cm}}
+  \pgfpathmoveto{\pgfpointpolar{0}{4mm}}
+  \pgfpathlineto{\pgfpointpolar{144}{4mm}}
+  \pgfpathlineto{\pgfpointpolar{288}{4mm}}
+  \pgfpathlineto{\pgfpointpolar{72}{4mm}}
+  \pgfpathlineto{\pgfpointpolar{216}{4mm}}
+  \pgfpathclose%
+  \pgfusepath{fill}
+}
+\pgfdeclarepatterninherentlycolored{green stars}
+{\pgfpointorigin}{\pgfpoint{1cm}{1cm}}
+{\pgfpoint{1cm}{1cm}}
+{
+  \pgfsetfillcolor{green!50!black}
+  \pgftransformshift{\pgfpoint{.5cm}{.5cm}}
+  \pgfpathmoveto{\pgfpointpolar{0}{4mm}}
+  \pgfpathlineto{\pgfpointpolar{144}{4mm}}
+  \pgfpathlineto{\pgfpointpolar{288}{4mm}}
+  \pgfpathlineto{\pgfpointpolar{72}{4mm}}
+  \pgfpathlineto{\pgfpointpolar{216}{4mm}}
+  \pgfpathclose%
+  \pgfusepath{stroke,fill}
+}}]
 \begin{tikzpicture}
   \pgfsetfillpattern{stars}{red}
   \filldraw (0,0) rectangle (1.5,2);