expanded documentation.

1 files changed, 56 insertions, 39 deletions

diff --git a/module/tex/context/third/simpleslides/simpleslides-s-Automata.tex b/module/tex/context/third/simpleslides/simpleslides-s-Automata.tex
index d0c1d73..a7a079d 100644
--- a/module/tex/context/third/simpleslides/simpleslides-s-Automata.tex
+++ b/module/tex/context/third/simpleslides/simpleslides-s-Automata.tex
@@ -35,7 +35,7 @@
 
 \unprotect
 
-%D First, we change the page layout to have more space all around
+%D First, we change the page layout to have more space all around.
 
 \setuplayout [              width=fit,
                            margin=2cm,
@@ -59,7 +59,7 @@
     [width=\paperwidth,
     height=\paperheight,x=20mm]
 
-%D Next we a generic frames, which will be used by other macros to
+%D Next we define generic frames, which will be used by other macros to
 %D get a consistent look and feel.
 
 \defineframed[simpleslides:framed:small]
@@ -78,6 +78,10 @@
 \define\PictureFrameWidth   {.46\textwidth}
 
 %D This module has two color schemes, a blue one and a red one.
+%D “backgroundoutside” and “backgroundscreen” -- obvioulsly -- determine how
+%D the background will look like, whereas “contrastcolor” is used to draw the
+%D automaton {\em onto} the background. Transparancy of the automaton is
+%D adjusted via the “opacity” factor in your automatarc.
 
 \startsetups simpleslides:setups:blue
 \definecolor [simpleslides:contrastcolor]      [r=0.7,g=0.7,b=0.9]
@@ -93,7 +97,7 @@
 \definecolor [simpleslides:textcolor]         [s=1]
 \stopsetups
 
-%D Now we choose the scheme that the user asked for
+%D Now we choose the scheme that the user asked for.
 
 \doifsetupselse
     {simpleslides:setups:\moduleparameter{simpleslides}{color}}
@@ -102,21 +106,24 @@
 
 \setupcolors[textcolor={simpleslides:textcolor}]
 
-%D Set the initial snapshot (from file) and the rule, if given.
+%D Setting up the automata part. Note that the precedence of settings is:
+%D \type{kpse:automatarc-global.lua} < \type{./automatrc.lua} < \type{setupmodule},
+%D but some options (such as the color scheme) can only be specified via
+%D \type{setupmodule[…]}.
+%D First, we check for the automaton type.
 
-\doifsomethingelse{\moduleparameter{simpleslides}{mode}}
-{\ctxlua{
-mplife.setup.current.mode = "\luaescapestring{\moduleparameter{simpleslides}{mode}}"
-if mplife.setup.current.mode == "life" then
-    mplife.successive = mplife.gol_successive
-else
-    environment.loadluafile("automata-eca")
-    mplife.successive = mplife.eca_successive
-end}}
-{\ctxlua{mplife.successive = mplife.gol_successive}}
+\doifsomethingelse{\moduleparameter{simpleslides}{mode}}{\ctxlua{
+    mplife.setup.current.mode = "\luaescapestring{\moduleparameter{simpleslides}{mode}}"
+    if mplife.setup.current.mode == "life" then
+        mplife.successive = mplife.gol_successive
+    else
+        environment.loadluafile("automata-eca")
+        mplife.successive = mplife.eca_successive
+    end}}
+    {\ctxlua{mplife.successive = mplife.gol_successive}}
 
 %D The number of dead cells to add left and right / before and after
-%D the initial frame.
+%D the initial frame. (Makes sense only for Game of Life.)
 
 \doifsomething{\moduleparameter{simpleslides}{extendxy}}{\ctxlua
     {mplife.setup.current.extendx = tonumber("\luaescapestring{\moduleparameter{simpleslides}{extendxy}}")
@@ -128,9 +135,29 @@ end}}
 \doifsomething{\moduleparameter{simpleslides}{extendy}}{\ctxlua
     {mplife.setup.current.extendy = tonumber("\luaescapestring{\moduleparameter{simpleslides}{extendy}}") }}
 
-\doifsomething{\moduleparameter{simpleslides}{file}}{\ctxlua{
-mplife.setup.current.file = "\luaescapestring{\moduleparameter{simpleslides}{file}}"
-}}
+%D Initial “tape”, i.e. the first frame with respect to Game of Life automata
+%D and the first line for Elementary automata. Filenames without suffix expand
+%D to \type{file .. ".gol"}.
+
+\doifsomething{\moduleparameter{simpleslides}{file}}{\ctxlua
+    {mplife.setup.current.file = "\luaescapestring{\moduleparameter{simpleslides}{file}}" }}
+
+%D Clipping is essential to cope with left/right propagation of
+%D patterns. E.g. with rule 158 the total propagation at iteration
+%D n is itself n to the left and n to the right. Whereas rule 102 
+%D (a Sierpiński fractal generator) protrudes only to the left at
+%D a rate of n.
+%D Frames cannot be simply cut off at the borders with adjacient 
+%D cells treated as “dead” because it would distort the pattern.
+%D Therefore, frames are generated as complete sections which are 
+%D clipped to the desired size, as specified by the initial row.
+%D To determine whether to clip your pattern to the left, right, 
+%D or in both directions, check the propagation at
+%D \type{string.format("http://mathworld.wolfram.com/Rule%s.html", rule)}
+%D or consult Wolfram's “A New Kind of Science” but beware not to
+%D buy everything he claims…
+%D
+%D Accepts values: \type{left}, \type{right} and \type{both}.
 
 \doifsomething{\moduleparameter{simpleslides}{clip}}{\ctxlua
     {mplife.setup.current.clip = "\luaescapestring{\moduleparameter{simpleslides}{clip}}" }}
@@ -145,20 +172,6 @@ do
         c.init      = eca.parse_file(c.file)
         c.framesize = math.floor(c.aspect * c.init:len())
         c.pages     = structure.counters.record("realpage")["last"]
-        -- Clipping is essential to cope with left/right propagation of
-        -- patterns. E.g. with rule 158 the total propagation at iteration
-        -- n is itself n to the left and n to the right. Whereas rule 102 
-        -- (a Sierpiński fractal generator) protrudes only to the left at
-        -- a rate of n.
-        -- Frames cannot be simply cut off at the borders with adjacient 
-        -- cells treated as “dead” because it would distort the pattern.
-        -- Therefore, frames are generated as complete sections which are 
-        -- clipped to the desired size, as specified by the initial row.
-        -- To determine whether to clip your pattern to the left, right, 
-        -- or in both directions, check the propagation at
-        -- string.format("http://mathworld.wolfram.com/Rule%s.html", rule)
-        -- or consult Wolfram's “A New Kind of Science” but beware not to
-        -- buy everything he claims…
         if c.clip then
             c.xneeded   =   c.pages * c.framesize
             if c.clip == "both" then -- Assume initial pattern is centered.
@@ -184,13 +197,17 @@ do
 end
 \stopluacode
 
-\doifsomething{\moduleparameter{simpleslides}{rule}}{\ctxlua{
-if mplife.setup.current.mode == "life" then
-    mplife.setup.current.rule = gol.parse_rule("\luaescapestring{\moduleparameter{simpleslides}{rule}}") 
-else
-    mplife.setup.current.rule = eca.gen_rule(tonumber("\luaescapestring{\moduleparameter{simpleslides}{rule}}")) 
-end
-}}
+%D Rules determine the transformation from one iteration to the next.
+%D {\em Life} rules take the form \type{B3/S23}, the separator being any of \type{/},
+%D \type{.} and \type{-}.
+%D Rules for elementary cellular automata are given in decimal: \type{1}--\type{255}.
+
+\doifsomething{\moduleparameter{simpleslides}{rule}}{\ctxlua
+   {if mplife.setup.current.mode == "life" then
+        mplife.setup.current.rule = gol.parse_rule("\luaescapestring{\moduleparameter{simpleslides}{rule}}") 
+    else
+        mplife.setup.current.rule = eca.gen_rule(tonumber("\luaescapestring{\moduleparameter{simpleslides}{rule}}")) 
+    end}}
 
 %D We also use \METAPOST\ to draw the horizontal and vertical page backgrounds.
 %D Backgrounds will be of solid color, the ornament gets the transparency.