document tutorial script machinery

doc/Makefile

@@ -129,6 +129,9 @@ doctest:
 %.pdf: %.svg
 	inkscape --export-pdf=$@ $<
 
+#### Tutorial and figure script generation machinery ####
+# See source/code/README for an explanation.
+
 # Make tutorial scripts by extracting the (complete!) context of the "patches".
 # We make sure not to use 'wiggle' here.
 .SECONDARY:

doc/source/code/README

+This directory contains the code examples from the documentation.
+Most scripts are present in three related but different versions that
+correspond to three different usages.
+
+* Subdirectory 'figure': scripts used for figure generation.  Figures
+  are not displayed but saved to disk.
+
+* Subdirectory 'include': scripts that display figures on screen.
+  They contain commented marks for including snippets in the
+  documentation.
+
+* Subdirectory 'download': complete scripts to be offered for download
+  by readers.  Like 'include' but with the include marks removed.
+
+Most scripts are extracted from corresponding '*.py.diff' files inside
+'figure/'.  These are patches from the 'include' version to the
+'figure' version.  The patches include complete context and as such
+can be used to recreate both files.  It's these patches that are kept
+under version control.
+
+running 'make html' or 'make latex' inside '/doc' will automatically
+update all these scripts according to the following scheme:
+
+            ---->------------->------
+           /                         \
+          /         download/x.py     \
+figure/x.py.diff         ^             \
+     ^           \       |              \
+     |            -> include/x.py ---(patch)---> figure/x.py
+     |                   |                          |
+     |                   |                          |
+      \                  v                         /
+       ----<----------(diff)--------------<--------
+
+Thus, it is possible to update figure/x.py.diff, include/x.py or
+figure/x.py and any changes will be propagated automatically when
+'make' is run.  (Only download/x.py is a dead end.)  The user will be
+informed about any conflicts.  The makefile will only update files
+that are older than their sources and is careful to propagate time
+stamps in order to avoid infinite loops.
+
+Editing only figure/x.py.diff is a sure way to avoid any conflicts.