doc: block with a group of Primitives

1 files changed, 33 insertions, 2 deletions

diff --git a/doc/primitives-with-arguments.md b/doc/primitives-with-arguments.md
index 1a2552b..a65af0b 100644
--- a/doc/primitives-with-arguments.md
+++ b/doc/primitives-with-arguments.md
@@ -42,8 +42,7 @@ state the first one, the argument type, explicitly:
             Primitive.plus, return_type=TYPE_NUMBER,
                 arg_descs=[ConstantArg(Primitive(
                     Turtle.get_pen_color, return_type=TYPE_NUMBER)),
-                    ArgSlot(TYPE_NUMBER)]))],
-        call_afterwards=self.after_uturn)
+                ArgSlot(TYPE_NUMBER)]))])
 
     self.tw.lc.def_prim('inc_color', 0, prim_inc_color)
 
@@ -57,3 +56,35 @@ block),   then that Primitive's return value  is matched against
 the required type. If Turtle Art doesn't know how to convert the
 attached value to the required type,  it shows the user an error
 message during execution.
+
+
+# TODO slot wrappers
+
+
+Example 3: Block with a Group of Primitives
+-------------------------------------------
+
+Blocks  like the 'clean' block  need to do  several things  in a
+row.  E.g., the 'clean' block needs to tell the plugins that the
+screen is being cleared, it needs to stop media execution, clear
+the screen, and reset all turtles.  It takes no block arguments,
+so it looks like this in Turtle Art:
+
+     ,---.___,---.
+    /             \
+    |   clean     |
+    \             /
+     `---.___,---´
+
+To execute a series  of several Primitives,  we need to define a
+'group' of Primitives. This 'group' is itself a Primitive, using
+the special function `Primitive.group`.   When called,  it loops
+over its arguments  and calls them successively.   The Primitive
+object for the 'clean' block looks like this:
+
+    Primitive(Primitive.group, arg_descs=[ConstantArg([
+        Primitive(self.tw.clear_plugins),
+        Primitive(self.tw.lc.prim_clear_helper,
+                  export_me=False),
+        Primitive(self.tw.canvas.clearscreen),
+        Primitive(self.tw.turtles.reset_turtles)])])