improve tutorial on how to add new blocks in tabasics

1 files changed, 39 insertions, 31 deletions

diff --git a/TurtleArt/tabasics.py b/TurtleArt/tabasics.py
index 11fe1c0..7876652 100644
--- a/TurtleArt/tabasics.py
+++ b/TurtleArt/tabasics.py
@@ -20,12 +20,13 @@
 #THE SOFTWARE.
 
 '''
-This file contains the constants that by-in-large determine the
-behavior of Turtle Art. Notably, the block palettes are defined
-below. If you want to add a new block to Turtle Art, you could
+This file contains the constants  that by-in-large determine the
+behavior of Turtle Art.  Notably, the block palettes are defined
+below.  If you want to add a new block to Turtle Art,  you could
 simply add a block of code to this file or to
-../plugins/turtle_blocks_extras/turtle_blocks_extras.py,
-which contains additional blocks. (Even better, write your own plugin!!)
+../plugins/turtle_blocks_extras/turtle_blocks_extras.py ,
+which contains additional blocks.  (Even better,  write your own
+plugin!!)
 
 
 Adding a new palette is simply a matter of:
@@ -34,8 +35,8 @@ Adding a new palette is simply a matter of:
                            colors=["#00FF00", "#00A000"],
                            help_string=_('Palette of my custom commands'))
 
-For example, if we want to add a new turtle command, 'uturn', we'd use the
-add_block method in the Palette class.
+For example,  if we want to add  a new turtle command,  'uturn',
+we'd use the `add_block` method in the Palette class.
 
     palette.add_block('uturn',  # the name of your block
                       style='basic-style',  # the block style
@@ -43,18 +44,24 @@ add_block method in the Palette class.
                       prim_name='uturn',  # code reference (see below)
                       help_string=_('turns the turtle 180 degrees'))
 
-Next, you need to define what your block will do:
-def_prim takes 3 arguments: the primitive name, the number of
-arguments -- 0 in this case -- and a callable -- in this
-case, we define the _prim_uturn function to set heading += 180.
-If you want your block to be exportable to Python code, use a Primitive
-object as the callable. A Primitive object consists of a function, its return
-type, and descriptions of its arguments. In this case, we know in advance
-which arguments each function gets, so we can use ConstantArgs as argument
-descriptions. If we want the arguments to come from other blocks, we would
-use ArgSlot objects to describe the (open) argument slots. Note that Primitive
-objects can be arguments to other Primitive objects. This leads to the
-following tree-like structure for our u-turn block:
+Next, you need to define what your block will do: def_prim takes
+3 arguments: the primitive name, the number of arguments -- 0 in
+this case  --   and a Primitive object.   A Primitive object re-
+presents the statement to be executed when the block is executed
+in Turtle Art.  For the 'uturn' block,  we would like the state-
+ment to look roughly like this:
+
+    Turtle.set_heading(plus(Turtle.get_heading(), 180))
+
+Formally, a Primitive object consists of a function,  its return
+type,  and descriptions  of its arguments and keyword arguments.
+In this case,  we know in advance  which arguments each function
+gets,   so we can use  ConstantArg objects  as argument descrip-
+tions. (For examples where the arguments come from other blocks,
+please refer to ../doc/primitives-with-arguments.md .) Note that
+Primitive objects  can be arguments  to other Primitive objects.
+This leads to the following tree-like structure  for our 'uturn'
+block:
 
     prim_uturn = Primitive(Turtle.set_heading,
         arg_descs=[ConstantArg(Primitive(
@@ -62,27 +69,28 @@ following tree-like structure for our u-turn block:
                 arg_descs=[ConstantArg(Primitive(
                     Turtle.get_heading, return_type=TYPE_NUMBER)),
                     ConstantArg(180)]))],
-        call_afterwards=after_uturn)
+        call_afterwards=self.after_uturn)
 
     self.tw.lc.def_prim('uturn', 0, prim_uturn)
 
+    # somewhere else in the same class:
     def after_uturn(self, value):
         if self.tw.lc.update_values:
             self.tw.lc.update_label_value('heading', value)
 
-In simplified form, the Primitive looks like this:
+The `call_afterwards` attribute  is  a simple function   that is
+called  just after executing  the block.   It is often used  for
+updating GUI labels.
 
-    Turtle.set_heading(plus(Turtle.get_heading, 180))
+That's it. When you next run Turtle Art, you will have a 'uturn'
+block on the 'mypalette' palette.
 
-That's it. When you next run Turtle Art, you will have a 'uturn' block
-on the 'mypalette' palette.
-
-You will have to create icons for the palette-selector buttons. These
-are kept in the icons subdirectory. You need two icons:
-mypaletteoff.svg and mypaletteon.svg, where 'mypalette' is the same
-string as the entry you used in instantiating the Palette class. Note
-that the icons should be the same size (55x55) as the others. (This is
-the default icon size for Sugar toolbars.)
+You will have to create icons  for the palette-selector buttons.
+These are kept in the 'icons' subdirectory.  You need two icons:
+mypaletteoff.svg and mypaletteon.svg,   where 'mypalette' is the
+same string  as the entry  you used in instantiating the Palette
+object.  Note  that the icons should be the same size (55x55) as
+the others. (This is the default icon size for Sugar toolbars.)
 '''
 
 from time import time, sleep