Working on docs.

docs/sphinx_docs/_build/html/_modules/index.html

@@ -34,7 +34,6 @@
 <ul><li><a href="joy/joy.html">joy.joy</a></li>
 <li><a href="joy/library.html">joy.library</a></li>
 <li><a href="joy/parser.html">joy.parser</a></li>
-<li><a href="joy/pribrary.html">joy.pribrary</a></li>
 <li><a href="joy/utils/pretty_print.html">joy.utils.pretty_print</a></li>
 <li><a href="joy/utils/stack.html">joy.utils.stack</a></li>
 </ul>

docs/sphinx_docs/_build/html/_sources/index.rst.txt

@@ -87,6 +87,7 @@ There are also some Jupyter notebooks.
    pretty
    library
    lib
+   notebooks/index
 
 
 

docs/sphinx_docs/_build/html/index.html

@@ -114,6 +114,13 @@ There are also some Jupyter notebooks.</p>
 <li class="toctree-l2"><a class="reference internal" href="lib.html#void"><code class="docutils literal notranslate"><span class="pre">void</span></code></a></li>
 </ul>
 </li>
+<li class="toctree-l1"><a class="reference internal" href="notebooks/index.html">Essays about Programming in Joy</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="notebooks/Developing.html">Developing a Program in Joy</a></li>
+<li class="toctree-l2"><a class="reference internal" href="notebooks/Trees.html">Treating Trees</a></li>
+<li class="toctree-l2"><a class="reference internal" href="notebooks/Newton-Raphson.html">Newton’s method</a></li>
+<li class="toctree-l2"><a class="reference internal" href="notebooks/Quadratic.html">Quadratic formula</a></li>
+</ul>
+</li>
 </ul>
 </div>
 </div>

docs/sphinx_docs/_build/html/lib.html

@@ -16,6 +16,7 @@
     <script type="text/javascript" src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script>
     <link rel="index" title="Index" href="genindex.html" />
     <link rel="search" title="Search" href="search.html" />
+    <link rel="next" title="Essays about Programming in Joy" href="notebooks/index.html" />
     <link rel="prev" title="Function Reference" href="library.html" />
    
   <link rel="stylesheet" href="_static/custom.css" type="text/css" />
@@ -1353,6 +1354,7 @@ soley of containers, without strings or numbers or anything else.)</p>
 <ul>
   <li><a href="index.html">Documentation overview</a><ul>
       <li>Previous: <a href="library.html" title="previous chapter">Function Reference</a></li>
+      <li>Next: <a href="notebooks/index.html" title="next chapter">Essays about Programming in Joy</a></li>
   </ul></li>
 </ul>
 </div>

docs/sphinx_docs/index.rst

@@ -87,6 +87,7 @@ There are also some Jupyter notebooks.
    pretty
    library
    lib
+   notebooks/index
 
 
 

docs/sphinx_docs/notebooks/Developing.rst

@@ -1,8 +1,12 @@
+***************************
+Developing a Program in Joy
+***************************
+
+As an example of developing a program in Joy let's take the first problem from the Project Euler website.
 
 `Project Euler, first problem: "Multiples of 3 and 5" <https://projecteuler.net/problem=1>`__
 =============================================================================================
 
-::
 
     If we list all the natural numbers below 10 that are multiples of 3 or 5, we get 3, 5, 6 and 9. The sum of these multiples is 23.
 
@@ -12,6 +16,9 @@
 
     from notebook_preamble import J, V, define
 
+Sum a range filtered by a predicate
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 Let's create a predicate that returns ``True`` if a number is a multiple
 of 3 or 5 and ``False`` otherwise.
 
@@ -54,7 +61,10 @@ Logically this is fine, but pragmatically we are doing more work than we
 should be; we generate one thousand integers but actually use less than
 half of them. A better solution would be to generate just the multiples
 we want to sum, and to add them as we go rather than storing them and
-adding summing them at the end.
+and summing them at the end.
+
+Generate just the multiples
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 At first I had the idea to use two counters and increase them by three
 and five, respectively. This way we only generate the terms that we
@@ -206,6 +216,9 @@ the counter to the running sum. This function will do that:
 So one ``step`` through all seven terms brings the counter to 15 and the
 total to 60.
 
+How many multiples to sum?
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 .. code:: ipython2
 
     1000 / 15
@@ -276,6 +289,8 @@ get to 990 and then the first four numbers 3 2 1 3 to get to 999.
 
     233168
 
+Packing the terms into an integer
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 This form uses no extra storage and produces no unused summands. It's
 good but there's one more trick we can apply. The list of seven terms
@@ -517,7 +532,8 @@ And so we have at last:
     233168
 
 
-Let's refactor.
+Let's refactor
+^^^^^^^^^^^^^^^
 
 ::
 

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')

docs/sphinx_docs/notebooks/Quadratic.rst

@@ -1,6 +1,7 @@
 
+***********************************************************************
 `Quadratic formula <https://en.wikipedia.org/wiki/Quadratic_formula>`__
-=======================================================================
+***********************************************************************
 
 .. code:: ipython2
 

docs/sphinx_docs/notebooks/Trees.rst

@@ -1,6 +1,7 @@
 
+**************
 Treating Trees
-==============
+**************
 
 Although any expression in Joy can be considered to describe a
 `tree <https://en.wikipedia.org/wiki/Tree_structure>`__ with the quotes
@@ -20,8 +21,8 @@ That says that a BTree is either the empty quote ``[]`` or a quote with
 four items: a key, a value, and two BTrees representing the left and
 right branches of the tree.
 
-A Function to Traverse this Structure
--------------------------------------
+A Function to Traverse a BTree
+=====================================
 
 Let's take a crack at writing a function that can recursively iterate or
 traverse these trees.
@@ -102,9 +103,7 @@ Hmm, will ``step`` do?
     key left-keys right BTree-iter
     key left-keys right-keys
 
-Wow. So:
-
-::
+So::
 
     R1 == [rest rest] dip step
 
@@ -133,17 +132,13 @@ Parameterizing the ``F`` per-node processing function.
 
     [F] BTree-iter == [not] [pop] [[F] dupdip rest rest] [step] genrec
 
-Working backward:
-
-::
+Working backward::
 
     [not] [pop] [[F] dupdip rest rest]            [step] genrec
     [not] [pop] [F]       [dupdip rest rest] cons [step] genrec
     [F] [not] [pop] roll< [dupdip rest rest] cons [step] genrec
 
-Ergo:
-
-::
+Ergo::
 
     BTree-iter == [not] [pop] roll< [dupdip rest rest] cons [step] genrec
 
@@ -162,7 +157,7 @@ Ergo:
 
 .. parsed-literal::
 
-    
+    (nothing)
 
 
 .. code:: ipython2
@@ -646,6 +641,9 @@ Putting it all together:
     ['a' 23 [] ['b' 88 [] ['c' 44 [] []]]]
 
 
+A Set-Like Datastructure
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
 We can use this to make a set-like datastructure by just setting values
 to e.g. 0 and ignoring them. It's set-like in that duplicate items added
 to it will only occur once within it, and we can query it in
@@ -693,8 +691,8 @@ from a list.
     [7 6 8 4 5 9 2 3]
 
 
-``cmp`` combinator
-==================
+Interlude: The ``cmp`` combinator
+=================================
 
 Instead of all this mucking about with nested ``ifte`` let's just go
 whole hog and define ``cmp`` which takes two values and three quoted
@@ -877,8 +875,8 @@ to understand:
     ['a' 23 [] ['b' 88 [] ['c' 44 [] []]]]
 
 
-Factoring and naming
-====================
+Interlude: Factoring and Naming
+================================
 
 It may seem silly, but a big part of programming in Forth (and therefore
 in Joy) is the idea of small, highly-factored definitions. If you choose
@@ -1210,9 +1208,6 @@ So:
 TODO: BTree-delete
 ==================
 
-Then, once we have add, get, and delete we can see about abstracting
-them.
-
 ::
 
        tree key [E] BTree-delete
@@ -1256,6 +1251,10 @@ And:
 Tree with node and list of trees.
 =================================
 
+Once we have add, get, and delete we can see about abstracting
+them.
+
+
 Let's consider a tree structure, similar to one described `"Why
 functional programming matters" by John
 Hughes <https://www.cs.kent.ac.uk/people/staff/dat/miranda/whyfp90.pdf>`__,
@@ -1268,7 +1267,7 @@ star <https://en.wikipedia.org/wiki/Kleene_star>`__.)
     tree = [] | [node [tree*]]
 
 ``treestep``
-~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
 
 In the spirit of ``step`` we are going to define a combinator
 ``treestep`` which expects a tree and three additional items: a
@@ -1298,7 +1297,7 @@ combine the result with ``C``.
            node N [tree*] [K] map C
 
 Derive the recursive form.
-~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Since this is a recursive function, we can begin to derive it by finding
 the ``ifte`` stage that ``genrec`` will produce. The predicate and
@@ -1353,7 +1352,7 @@ Plug it in and convert to ``genrec``:
     K == [not] [pop z] [i [N] dip]   [map C] genrec
 
 Extract the givens to parameterize the program.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -1379,7 +1378,7 @@ Extract the givens to parameterize the program.
 The givens are all to the left so we have our definition.
 
 Define ``treestep``
-~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -1439,7 +1438,7 @@ Define ``treestep``
 
 
 A slight modification.
-----------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Let's simplify the tree datastructure definition slightly by just
 letting the children be the ``rest`` of the tree:
@@ -1494,7 +1493,7 @@ The ``J`` function changes slightly.
 I think these trees seem a little easier to read.
 
 Redefining our BTree in terms of this form.
--------------------------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
@@ -1560,7 +1559,10 @@ So:
     [3 2 9 5 4 8 6 7]
 
 
-There we go. #### In-order traversal with ``treestep``.
+There we go.
+
+In-order traversal with ``treestep``.
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 From here:
 
@@ -1590,10 +1592,10 @@ So:
 
 
 Miscellaneous Crap
-------------------
+==================
 
 Toy with it.
-~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Let's reexamine:
 
@@ -1658,7 +1660,7 @@ items" in each node. This point to a more general factorization that
 would render a combinator that could work for other geometries of trees.
 
 A General Form for Trees
-------------------------
+========================
 
 A general form for tree data with N children per node:
 
@@ -1779,7 +1781,7 @@ Hmm...
 We could just let ``[R1]`` be a parameter too, for maximum flexibility.
 
 Automatically deriving the recursion combinator for a data type?
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+================================================================
 
 If I understand it correctly, the "Bananas..." paper talks about a way
 to build the processor function automatically from the description of

docs/sphinx_docs/notebooks/index.rst

@@ -1,11 +1,13 @@
 
-There are also some Jupyter notebooks.
-======================================
+Essays about Programming in Joy
+===============================
 
 .. toctree::
    :glob:
    :maxdepth: 2
 
-   *
-
+   Developing
+   Trees
+   Newton-Raphson
+   Quadratic