Working on docs.

docs/sphinx_docs/notebooks/Newton-Raphson.rst

@@ -2,6 +2,8 @@
 `Newton's method <https://en.wikipedia.org/wiki/Newton%27s_method>`__
 =====================================================================
 
+Newton-Raphson for finding the root of an equation.
+
 .. code:: ipython2
 
     from notebook_preamble import J, V, define
@@ -9,9 +11,12 @@
 Cf. `"Why Functional Programming Matters" by John
 Hughes <https://www.cs.kent.ac.uk/people/staff/dat/miranda/whyfp90.pdf>`__
 
-:math:`a_{i+1} = \frac{(a_i+\frac{n}{a_i})}{2}`
+Finding the Square-Root of a Number
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Let's define a function that computes the above equation:
+Let's define a function that computes this equation:
+
+:math:`a_{i+1} = \frac{(a_i+\frac{n}{a_i})}{2}`
 
 ::
 
@@ -35,6 +40,9 @@ We want it to leave n but replace a, so we execute it with ``unary``:
 
     define('Q == [tuck / + 2 /] unary')
 
+Compute the Error
+^^^^^^^^^^^^^^^^^
+
 And a function to compute the error:
 
 ::
@@ -53,6 +61,9 @@ below the error.
 
     define('err == [sqr - abs] nullary')
 
+``square-root``
+^^^^^^^^^^^^^^^
+
 Now we can define a recursive program that expects a number ``n``, an
 initial estimate ``a``, and an epsilon value ``ε``, and that leaves on
 the stack the square root of ``n`` to within the precision of the
@@ -75,14 +86,22 @@ next approximation and the error on the stack below the epsilon.
     n a'  err ε 
     n a' e    ε
 
-Let's define the recursive function from here. Start with ``ifte``; the
-predicate and the base case behavior are obvious:
+Let's define a recursive function ``K`` from here.
 
 ::
 
-    n a' e ε [<] [popop popd] [J] ifte
+    n a' e ε K
+
+    K == [P] [E] [R0] [R1] genrec
 
 Base-case
+~~~~~~~~~
+
+The predicate and the base case are obvious:
+
+::
+
+    K == [<] [popop popd] [R0] [R1] genrec
 
 ::
 
@@ -90,19 +109,25 @@ Base-case
     n a'           popd
       a'
 
+Recur
+~~~~~~~~~~
+
 The recursive branch is pretty easy. Discard the error and recur.
 
 ::
 
-    w/ K == [<] [popop popd] [J] ifte
+    K == [<] [popop popd] [R0]   [R1] genrec
+    K == [<] [popop popd] [R0 [K] R1] ifte
 
-    n a' e ε J
+::
+
+    n a' e ε               R0 [K] R1
     n a' e ε popd [Q err] dip [K] i
     n a'   ε      [Q err] dip [K] i
     n a' Q err ε              [K] i
     n a''  e   ε               K
 
-This fragment alone is pretty useful.
+This fragment alone is pretty useful.  (``R1`` is ``i`` so this is a ``primrec`` "primitive recursive" function.)
 
 .. code:: ipython2
 
@@ -127,6 +152,8 @@ This fragment alone is pretty useful.
 
     5.000000000000005
 
+Initial Approximation and Epsilon
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 So now all we need is a way to generate an initial approximation and an
 epsilon value:
@@ -139,6 +166,9 @@ epsilon value:
 
     define('square-root == dup 3 / 0.000001 dup K')
 
+Examples
+~~~~~~~~~~
+
 .. code:: ipython2
 
     J('36 square-root')