From 0c8e05979d3dd08a11078c4cfd68d176b2ccab74 Mon Sep 17 00:00:00 2001
From: Hanson Char <hanson.char@gmail.com>
Date: Wed, 5 Jun 2024 18:49:47 -0700
Subject: [PATCH] Additional changes in response to the feedback at

  https://github.com/pgf-tikz/pgf/pull/1335

Signed-off-by: Hanson Char <hanson.char@gmail.com>
---
 .../graphdrawing/lua/pgf/gd/control/doc.lua   | 66 ++++++++++++++-----
 .../pgf/graphdrawing/lua/pgf/gd/doc.lua       |  7 +-
 .../pgf/graphdrawing/lua/pgf/gd/trees/doc.lua |  8 ++-
 3 files changed, 58 insertions(+), 23 deletions(-)

diff --git a/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/doc.lua b/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/doc.lua
index 19bfd52fd..1bad4117f 100644
--- a/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/doc.lua
+++ b/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/doc.lua
@@ -98,12 +98,12 @@ sense that some nodes are ``nailed to the canvas'' while other
 nodes can ``move freely''.
 ]]
 
---[[
-% TODOsp: codeexamples: the following 3 examples need these libraries
-%    \usetikzlibrary{graphs,graphdrawing}
-%    \usegdlibrary{force}
---]]
-example
+example({options =
+[[
+  preamble=\usetikzlibrary{graphs,graphdrawing}
+    \usegdlibrary{force}
+]],
+code =
 [[
 \begin{tikzpicture}
   \draw [help lines] (0,0) grid (3,2);
@@ -114,8 +114,14 @@ example
   };
 \end{tikzpicture}
 ]]
+})
 
-example
+example({options =
+[[
+  preamble=\usetikzlibrary{graphs,graphdrawing}
+    \usegdlibrary{force}
+]],
+code =
 [[
 \begin{tikzpicture}
   \draw [help lines] (0,0) grid (3,2);
@@ -126,8 +132,14 @@ example
   };
 \end{tikzpicture}
 ]]
+})
 
-example
+example({options =
+[[
+  preamble=\usetikzlibrary{graphs,graphdrawing}
+    \usegdlibrary{force}
+]],
+code =
 [[
 \begin{tikzpicture}
   \draw [help lines] (0,0) grid (3,2);
@@ -138,6 +150,7 @@ example
   };
 \end{tikzpicture}
 ]]
+})
 --------------------------------------------------------------------
 
 
@@ -167,20 +180,26 @@ Note how in the last example |c| is placed at |(1,1)| rather than
 |b| as would happen by default.
 ]]
 
---[[
-% TODOsp: codeexamples: the following 4 examples need these libraries
-%    \usetikzlibrary{graphs,graphdrawing}
-%    \usegdlibrary{layered}
---]]
-example
+example({options =
+[[
+  preamble=\usetikzlibrary{graphs,graphdrawing}
+    \usegdlibrary{layered}
+]],
+code =
 [[
 \tikz \draw (0,0)
   -- (1,0.5) graph [edges=red,  layered layout, anchor node=a] { a -> {b,c} }
   -- (1.5,0) graph [edges=blue, layered layout,
                     anchor node=y, anchor at={(2,0)}]          { x -> {y,z} };
 ]]
+})
 
-example
+example({options =
+[[
+  preamble=\usetikzlibrary{graphs,graphdrawing}
+    \usegdlibrary{layered}
+]],
+code =
 [[
 \begin{tikzpicture}
   \draw [help lines] (0,0) grid (3,2);
@@ -189,6 +208,7 @@ example
     { a -- {b [x=1,y=1], c [x=1,y=1] } -- d -- a};
 \end{tikzpicture}
 ]]
+})
 --------------------------------------------------------------------
 
 
@@ -203,7 +223,12 @@ The coordinate at which the graph should be anchored when no
 explicit anchor is given for any node. The initial value is the origin.
 ]]
 
-example
+example({options =
+[[
+  preamble=\usetikzlibrary{graphs,graphdrawing}
+    \usegdlibrary{layered}
+]],
+code =
 [[
 \begin{tikzpicture}
   \draw [help lines] (0,0) grid (2,2);
@@ -212,6 +237,7 @@ example
     { a -- {b, c [anchor here] } -- d -- a};
 \end{tikzpicture}
 ]]
+})
 --------------------------------------------------------------------
 
 
@@ -233,7 +259,12 @@ In the example, |c| is placed at the origin since this is the
 default |anchor at| position.
 ]]
 
-example
+example({options =
+[[
+  preamble=\usetikzlibrary{graphs,graphdrawing}
+    \usegdlibrary{layered}
+]],
+code =
 [[
 \begin{tikzpicture}
   \draw [help lines] (0,0) grid (2,2);
@@ -242,4 +273,5 @@ example
     { a -- {b, c [anchor here] } -- d -- a};
 \end{tikzpicture}
 ]]
+})
 --------------------------------------------------------------------
diff --git a/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua b/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua
index 78b68bbcb..857306d5f 100644
--- a/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua
+++ b/tex/generic/pgf/graphdrawing/lua/pgf/gd/doc.lua
@@ -112,11 +112,10 @@ end
 -- Adds an example to the |examples| field of the last key selected
 -- through the |key| command.
 --
--- @param string An additional example string.
-
-function doc.example (string)
+-- @param input either a string of example or a table with two fields - "code" and "options".
+function doc.example (input)
   local examples = rawget(current_key, "examples") or {}
-  examples[#examples + 1] = string
+  examples[#examples + 1] = input
   current_key.examples = examples
 end
 
diff --git a/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/doc.lua b/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/doc.lua
index f09b3dd3f..edc758b3c 100644
--- a/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/doc.lua
+++ b/tex/generic/pgf/graphdrawing/lua/pgf/gd/trees/doc.lua
@@ -293,9 +293,12 @@ example
   };
 ]]
 
-example
+example({options =
+[[
+  preamble=\usetikzlibrary{shapes.misc, arrows.meta, decorations.pathmorphing}
+]],
+code =
 [[
-\usetikzlibrary{shapes.misc, arrows.meta, decorations.pathmorphing}
 \tikz \graph [binary tree layout] {
   Knuth -> {
     Beeton -> Kellermann [second] -> Carnes,
@@ -313,6 +316,7 @@ example
     }
   };
 ]]
+})
 --------------------------------------------------------------------