Support applying options to multiple examples as suggested in #640

[hansonchar]

Motivation for this change

The conversation at #640 on the possibility of supporting the specification of options that can be applied to multiple examples.

To demonstrate the usage of this feature, I've modified ControlElectric.lua, while simplifying the code by removing unnecessary double quotes at the same time.

Checklist

• Code changes are licensed under GPLv2 + LPPLv1.3c
• Documentation changes are licensed under FDLv1.2

[hansonchar]

This PR is also related to #971

[Mo-Gul]

Awesome!

[hansonchar]

I found bugs in this version of pull request. It doesn't work in all cases. Please do not merge this PR for now. The fix is coming along in due course.

[Mo-Gul]

I am not sure if I understand your message right, but also the actual version (without your PR) doesn't work in all cases so far.
(I think I listed some/all of them in some comment ...)

[hansonchar]

Oops, never mind my last comment. My bad checking out the wrong source from the wrong branch locally.

[Mo-Gul]

For the record: Here are other examples that could make use of this PR:

• pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/doc.lua

  Lines 101 to 140 in 12f1783

  	--[[
  	% TODOsp: codeexamples: the following 3 examples need these libraries
  	% \usetikzlibrary{graphs,graphdrawing}
  	% \usegdlibrary{force}
  	--]]
  	example
  	[[
  	\begin{tikzpicture}
  	\draw [help lines] (0,0) grid (3,2);
  	\graph [spring layout]
  	{
  	a[x=1] -- { b, c, d, e -- {f,g,h} };
  	{ h, g } -- a;
  	};
  	\end{tikzpicture}
  	]]
  	example
  	[[
  	\begin{tikzpicture}
  	\draw [help lines] (0,0) grid (3,2);
  	\graph [spring layout]
  	{
  	a -- { b, c, d[x=0], e -- {f[x=2], g, h[x=1]} };
  	{ h, g } -- a;
  	};
  	\end{tikzpicture}
  	]]
  	example
  	[[
  	\begin{tikzpicture}
  	\draw [help lines] (0,0) grid (3,2);
  	\graph [spring layout]
  	{
  	a -- { b, c, d[x=0], e -- {f[x=2,y=1], g, h[x=1]} };
  	{ h, g } -- a;
  	};
  	\end{tikzpicture}
  	]]

• pgf/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/doc.lua

  Lines 170 to 191 in 12f1783

  	--[[
  	% TODOsp: codeexamples: the following 4 examples need these libraries
  	% \usetikzlibrary{graphs,graphdrawing}
  	% \usegdlibrary{layered}
  	--]]
  	example
  	[[
  	\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
  	[[
  	\begin{tikzpicture}
  	\draw [help lines] (0,0) grid (3,2);
  	\graph [layered layout, anchor node=c, edges=rounded corners]
  	{ a -- {b [x=1,y=1], c [x=1,y=1] } -- d -- a};
  	\end{tikzpicture}
  	]]

[hansonchar]

For the record: Here are other examples that could make use of this PR:

* [ ]  https://github.com/pgf-tikz/pgf/blob/12f17834c849a659b8829bbc9122bc459f585917/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/doc.lua#L101-L140

* [ ]  https://github.com/pgf-tikz/pgf/blob/12f17834c849a659b8829bbc9122bc459f585917/tex/generic/pgf/graphdrawing/lua/pgf/gd/control/doc.lua#L170-L191

Indeed. I am working on my forked branch (specifically main) fixing most, if not all of the missing preambles. And there are lots of them. The two you pointed out are indeed covered.

[hansonchar]

After fixing all the missing preambles and extending the existing extractor.lua (in my forked main branch), it extracted 2,503 tex documents. I managed to compile them all successfully. The generated pgfmanual.pdf is also looking good. (You should be able to download the updated pdf from https://github.com/hansonchar/pgf/actions/runs/9750355245 once the workflow has completed. See here and scroll to the bottom if you want to replicate the extract-compile process from my main branch.)

I plan to submit two pull requests - one for fixing the preamble, etc. so that readers of the manual can copy-and-paste any of the examples in the pdf and have them successfully compiled, and another for the extended extractors and scripts.

(I've got other miscellaneous things fixed as well, but I'll delay those to future pull requests.)

However, these changes presume the fixes in this pull request #1339 have been merged. Any chance that can be done any time soon?

[Mo-Gul]

That sounds awesome.

Unfortunately I am a Windows child with almost no knowledge about bash scripts. After modifying it a bit so I could run it in Git Bash it extracted 2391 files. I assume it is my fault that I couldn't replicate 2503 extractions as you. I didn't run the compilations until the end, because in series this takes "forever"
😴.

Merging usually is done by the master chief @hmenke, but I haven't seem him for a while (at least I can't remember ...). Have you (@muzimuzhi) seen him?

[hansonchar]

2391 sounds significantly on the low side. Did you specify both the pgf/tex and pgf/doc (of the forked main branch) as the source directories during the extraction ? For example,

texlua ~/github.com/pgf/doc/generic/pgf/extract.lua ~/github.com/pgf/tex ~/github.com/pgf/doc ~/tmp/mwe

(Running in parallel is an optimization that can be done later on.)

[Mo-Gul]

Sorry, forgot that the main branch is called "master" so I didn't run the script on your "main" branch. Now I also extracted 2305 TEX files.

[hansonchar]

I think you meant 2503, but yeah.

[Mo-Gul]

Of course. It seems I really need holidays :)