More docs

Working towards that v0.1.1.

Makefile

@@ -1,7 +1,7 @@
 # My make-fu style is old and tired.  I just want to have a few helper commands.
 
 TESTDIR = ./test00
-VERSION = 0.1.0
+VERSION = 0.1.1
 
 .PHONY: clean sdist test docs
 

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

@@ -45,6 +45,8 @@ To start the REPL::
 
     $ python -m joy
 
+Continue with :doc:`the introduction <notebooks/Intro>`.
+
 .. _PyPI: https://pypi.org/project/Thun/
 
 
@@ -89,6 +91,7 @@ The following is specific information for this dialect of Joy.
 .. toctree::
    :maxdepth: 2
 
+   notebooks/Intro
    joy
    stack
    parser

docs/sphinx_docs/_build/html/index.html

@@ -16,7 +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="Joy Interpreter" href="joy.html" />
+    <link rel="next" title="Thun: Joy in Python" href="notebooks/Intro.html" />
    
   <link rel="stylesheet" href="_static/custom.css" type="text/css" />
   
@@ -63,6 +63,7 @@ itself.</p>
 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python -m joy
 </pre></div>
 </div>
+<p>Continue with <a class="reference internal" href="notebooks/Intro.html"><span class="doc">the introduction</span></a>.</p>
 </div>
 <div class="section" id="project-hosted-on-osdn">
 <h2>Project Hosted on <a class="reference external" href="https://osdn.net/projects/joypy/">OSDN</a><a class="headerlink" href="#project-hosted-on-osdn" title="Permalink to this headline">¶</a></h2>
@@ -89,6 +90,15 @@ interesting aspects.  It’s quite a treasure trove.</p>
 <p>The following is specific information for this dialect of Joy.</p>
 <div class="toctree-wrapper compound">
 <ul>
+<li class="toctree-l1"><a class="reference internal" href="notebooks/Intro.html">Thun: Joy in Python</a><ul>
+<li class="toctree-l2"><a class="reference internal" href="notebooks/Intro.html#read-eval-print-loop-repl">Read-Eval-Print Loop (REPL)</a></li>
+<li class="toctree-l2"><a class="reference internal" href="notebooks/Intro.html#the-stack">The Stack</a></li>
+<li class="toctree-l2"><a class="reference internal" href="notebooks/Intro.html#purely-functional-datastructures">Purely Functional Datastructures.</a></li>
+<li class="toctree-l2"><a class="reference internal" href="notebooks/Intro.html#the-joy-function">The <code class="docutils literal notranslate"><span class="pre">joy()</span></code> function</a></li>
+<li class="toctree-l2"><a class="reference internal" href="notebooks/Intro.html#parser">Parser</a></li>
+<li class="toctree-l2"><a class="reference internal" href="notebooks/Intro.html#library">Library</a></li>
+</ul>
+</li>
 <li class="toctree-l1"><a class="reference internal" href="joy.html">Joy Interpreter</a><ul>
 <li class="toctree-l2"><a class="reference internal" href="joy.html#module-joy.joy"><code class="docutils literal notranslate"><span class="pre">joy.joy</span></code></a></li>
 </ul>
@@ -163,7 +173,7 @@ interesting aspects.  It’s quite a treasure trove.</p>
 <h3>Related Topics</h3>
 <ul>
   <li><a href="#">Documentation overview</a><ul>
-      <li>Next: <a href="joy.html" title="next chapter">Joy Interpreter</a></li>
+      <li>Next: <a href="notebooks/Intro.html" title="next chapter">Thun: Joy in Python</a></li>
   </ul></li>
 </ul>
 </div>

docs/sphinx_docs/_templates/layout.html

@@ -0,0 +1,16 @@
+{% extends "!layout.html" %}
+{% block footer %}
+    <div class="footer" role="contentinfo">
+<a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">
+<img alt="Creative Commons License" style="border-width:0" src="https://i.creativecommons.org/l/by-nc-sa/4.0/88x31.png" />
+</a>
+<br />
+<span xmlns:dct="http://purl.org/dc/terms/" property="dct:title">Thun Documentation</span> by <a xmlns:cc="http://creativecommons.org/ns#" href="https://joypy.osdn.io/" property="cc:attributionName" rel="cc:attributionURL">Simon Forman</a> is licensed under a <a rel="license" href="http://creativecommons.org/licenses/by-nc-sa/4.0/">Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License</a>.<br />Based on a work at <a xmlns:dct="http://purl.org/dc/terms/" href="https://osdn.net/projects/joypy/" rel="dct:source">https://osdn.net/projects/joypy/</a>.
+    {%- if last_updated %}
+      {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
+    {%- endif %}
+    {%- if show_sphinx %}
+      {% trans sphinx_version=sphinx_version|e %}Created using <a href="http://sphinx-doc.org/">Sphinx</a> {{ sphinx_version }}.{% endtrans %}
+    {%- endif %}
+    </div>
+{% endblock %}

docs/sphinx_docs/index.rst

@@ -45,6 +45,8 @@ To start the REPL::
 
     $ python -m joy
 
+Continue with :doc:`the introduction <notebooks/Intro>`.
+
 .. _PyPI: https://pypi.org/project/Thun/
 
 
@@ -89,6 +91,7 @@ The following is specific information for this dialect of Joy.
 .. toctree::
    :maxdepth: 2
 
+   notebooks/Intro
    joy
    stack
    parser

docs/sphinx_docs/notebooks/AlsoNewton.rst

@@ -0,0 +1,124 @@
+***************
+``within``
+***************
+
+    The remainder of a square root finder is a function *within*, which takes a tolerance and a list of approximations and looks down the list for two successive approximations that differ by no more than the given tolerance.
+
+From `"Why Functional Programming Matters" by John
+Hughes <https://www.cs.kent.ac.uk/people/staff/dat/miranda/whyfp90.pdf>`__
+
+(And note that by "list" he means a lazily-evaluated list.)
+
+Using a :doc:`generator <Generator Programs>` driven by ``x`` and assuming such for square root approximations (or whatever) ``G``, and further assuming that the first term ``a`` has been generated already and epsilon ``ε`` is handy on the stack...
+
+::
+
+       a [b G] ε within
+    -------------------- a b - abs ε <=
+          b
+
+       a [b G] ε within
+    -------------------- a b - abs ε >
+           .
+       [b G] x ε ...
+       b [c G] ε ...
+           .
+    --------------------
+       b [c G] ε within
+
+
+
+Predicate
+^^^^^^^^^^^^^
+
+::
+
+    a [b G]             ε [first - abs] dip <=
+    a [b G] first - abs ε                   <=
+    a b           - abs ε                   <=
+    a-b             abs ε                   <=
+    abs(a-b)            ε                   <=
+    (abs(a-b)<=ε)
+
+
+::
+
+    P == [first - abs] dip <=
+
+
+Base-Case
+^^^^^^^^^^^^^
+
+::
+
+    a [b G] ε roll< popop first
+      [b G] ε a     popop first
+      [b G]               first
+       b
+
+::
+
+   B == roll< popop first
+
+Recur
+^^^^^^^^^^^^^
+
+::
+
+    a [b G] ε R0 [within] R1
+
+
+1. Discard ``a``.
+2. Use ``x`` combinator to generate next term from G.
+3. Run ``within`` with ``i`` (it is a ``primrec`` function.)
+
+::
+
+    a [b G]        ε R0           [within] R1
+    a [b G]        ε [popd x] dip [within] i
+    a [b G] popd x ε              [within] i
+      [b G]      x ε              [within] i
+    b [c G]        ε              [within] i
+    b [c G]        ε               within
+
+    b [c G] ε within
+
+::
+
+    R0 == [popd x] dip
+
+Setting up
+^^^^^^^^^^
+
+::
+
+    [a G] x ε
+    a [b G] ε
+
+::
+
+    within == x ε [[first - abs] dip <=] [roll< popop first] [[popd x] dip] primrec
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+

docs/sphinx_docs/notebooks/Categorical.rst

@@ -0,0 +1,17 @@
+
+***********************
+Categorical Programming
+***********************
+
+DRAFT
+
+`Categorical <https://en.wikipedia.org/wiki/Category_theory>`__  
+
+In Manfred von Thun's article `Joy compared with other functional languages <http://www.kevinalbrecht.com/code/joy-mirror/j08cnt.html>`__ he asks, "Could the language of categories be used for writing programs? Any lambda expression can be translated into a categorical expression, so the language of categories is expressively complete. But this does not make it a suitable language for writing programs. As it stands it is a very low-level language."
+
+In `Compiling to categories <http://conal.net/papers/compiling-to-categories/>`__ Conal Elliott give a taste of what this might mean.
+
+    It is well-known that the simply typed lambda-calculus is modeled by any cartesian closed category (CCC). This correspondence suggests giving typed functional programs a variety of interpretations, each corresponding to a different category. A convenient way to realize this idea is as a collection of meaning-preserving transformations added to an existing compiler, such as GHC for Haskell. This paper describes such an implementation and demonstrates its use for a variety of interpretations including hardware circuits, automatic differentiation, incremental computation, and interval analysis. Each such interpretation is a category easily defined in Haskell (outside of the compiler). The general technique appears to provide a compelling alternative to deeply embedded domain-specific languages.
+
+What he's doing is translating labda forms into a kind of "point-free" style that is very close to Joy code (although more verbose) and then showing how to instantiate that code over different categories to get several different kinds of program out of the same code.
+

docs/sphinx_docs/notebooks/Intro.rst

@@ -1,21 +1,20 @@
 
-Joypy
+*******************
-=====
+Thun: Joy in Python
-
+*******************
-Joy in Python
--------------
 
 This implementation is meant as a tool for exploring the programming
 model and method of Joy. Python seems like a great implementation
 language for Joy for several reasons.
 
-We can lean on the Python immutable types for our basic semantics and
+* We can lean on the Python immutable types for our basic semantics and types: ints, floats, strings, and tuples, which enforces functional purity.
-types: ints, floats, strings, and tuples, which enforces functional
+* We get garbage collection for free.
-purity. We get garbage collection for free. Compilation via Cython. Glue
+* Compilation via Cython.
-language with loads of libraries.
+* Python is a "glue language" with loads of libraries which we can wrap in Joy functions.
+
 
 `Read-Eval-Print Loop (REPL) <https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop>`__
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+====================================================================================================
 
 The main way to interact with the Joy interpreter is through a simple
 `REPL <https://en.wikipedia.org/wiki/Read%E2%80%93eval%E2%80%93print_loop>`__
@@ -37,11 +36,8 @@ that you start by running the package:
     joy? _
 
 The ``<-top`` marker points to the top of the (initially empty) stack.
-You can enter Joy notation at the prompt and a `trace of
+You can enter Joy notation at the prompt and a :doc:`trace of evaluation <../pretty>` will
-evaluation <#The-TracePrinter.>`__ will be printed followed by the stack
+be printed followed by the stack and prompt again::
-and prompt again:
-
-::
 
     joy? 23 sqr 18 +
            . 23 sqr 18 +
@@ -56,195 +52,59 @@ and prompt again:
 
     joy? 
 
-Stacks (aka list, quote, sequence, etc.)
+
-========================================
+The Stack
+=============
 
 In Joy, in addition to the types Boolean, integer, float, and string,
-there is a single sequence type represented by enclosing a sequence of
+there is a :doc:`single sequence type <../stack>` represented by enclosing a sequence of
 terms in brackets ``[...]``. This sequence type is used to represent
 both the stack and the expression. It is a `cons
 list <https://en.wikipedia.org/wiki/Cons#Lists>`__ made from Python
 tuples.
 
-.. code:: ipython2
 
-    import inspect
+Purely Functional Datastructures
-    import joy.utils.stack
+=================================
-    
+
-    
+Because Joy stacks are made out of Python tuples they are immutable, as are the other Python types we "borrow" for Joy, so all Joy datastructures are `purely functional <https://en.wikipedia.org/wiki/Purely_functional_data_structure>`__.
-    print inspect.getdoc(joy.utils.stack)
 
 
-.. parsed-literal::
+The ``joy()`` function
-
-    § Stack
-    
-    
-    When talking about Joy we use the terms "stack", "list", "sequence" and
-    "aggregate" to mean the same thing: a simple datatype that permits
-    certain operations such as iterating and pushing and popping values from
-    (at least) one end.
-    
-    We use the venerable two-tuple recursive form of sequences where the
-    empty tuple () is the empty stack and (head, rest) gives the recursive
-    form of a stack with one or more items on it.
-    
-      ()
-      (1, ())
-      (2, (1, ()))
-      (3, (2, (1, ())))
-      ...
-    
-    And so on.
-    
-    
-    We have two very simple functions to build up a stack from a Python
-    iterable and also to iterate through a stack and yield its items
-    one-by-one in order, and two functions to generate string representations
-    of stacks:
-    
-      list_to_stack()
-    
-      iter_stack()
-    
-      expression_to_string()  (prints left-to-right)
-    
-      stack_to_string()  (prints right-to-left)
-    
-    
-    A word about the stack data structure.
-    
-    Python has very nice "tuple packing and unpacking" in its syntax which
-    means we can directly "unpack" the expected arguments to a Joy function.
-    
-    For example:
-    
-      def dup(stack):
-        head, tail = stack
-        return head, (head, tail)
-    
-    We replace the argument "stack" by the expected structure of the stack,
-    in this case "(head, tail)", and Python takes care of de-structuring the
-    incoming argument and assigning values to the names.  Note that Python
-    syntax doesn't require parentheses around tuples used in expressions
-    where they would be redundant.
-
-
-The utility functions maintain order.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The 0th item in the list will be on the top of the stack and *vise
-versa*.
-
-.. code:: ipython2
-
-    joy.utils.stack.list_to_stack([1, 2, 3])
-
-
-
-
-.. parsed-literal::
-
-    (1, (2, (3, ())))
-
-
-
-.. code:: ipython2
-
-    list(joy.utils.stack.iter_stack((1, (2, (3, ())))))
-
-
-
-
-.. parsed-literal::
-
-    [1, 2, 3]
-
-
-
-This requires reversing the sequence (or iterating backwards) otherwise:
-
-.. code:: ipython2
-
-    stack = ()
-    
-    for n in [1, 2, 3]:
-        stack = n, stack
-    
-    print stack
-    print list(joy.utils.stack.iter_stack(stack))
-
-
-.. parsed-literal::
-
-    (3, (2, (1, ())))
-    [3, 2, 1]
-
-
-Purely Functional Datastructures.
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Because Joy lists are made out of Python tuples they are immutable, so
-all Joy datastructures are *`purely
-functional <https://en.wikipedia.org/wiki/Purely_functional_data_structure>`__*.
-
-The ``joy()`` function.
 =======================
 
 An Interpreter
---------------
+~~~~~~~~~~~~~~~~~
 
-The ``joy()`` function is extrememly simple. It accepts a stack, an
+The ``joy()`` interpreter function is extrememly simple. It accepts a stack, an
 expression, and a dictionary, and it iterates through the expression
-putting values onto the stack and delegating execution to functions it
+putting values onto the stack and delegating execution to functions which it
 looks up in the dictionary.
 
-Each function is passed the stack, expression, and dictionary and
-returns them. Whatever the function returns becomes the new stack,
-expression, and dictionary. (The dictionary is passed to enable e.g.
-writing words that let you enter new words into the dictionary at
-runtime, which nothing does yet and may be a bad idea, and the ``help``
-command.)
 
-.. code:: ipython2
+`Continuation-Passing Style <https://en.wikipedia.org/wiki/Continuation-passing_style>`__
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    import joy.joy
+One day I thought, What happens if you rewrite Joy to use
-    
+`CPS <https://en.wikipedia.org/wiki/Continuation-passing_style>`__? I
-    print inspect.getsource(joy.joy.joy)
+made all the functions accept and return the expression as well as the
-
+stack and found that all the combinators could be rewritten to work by
-
+modifying the expression rather than making recursive calls to the
-.. parsed-literal::
+``joy()`` function.
-
-    def joy(stack, expression, dictionary, viewer=None):
-      '''
-      Evaluate the Joy expression on the stack.
-      '''
-      while expression:
-    
-        if viewer: viewer(stack, expression)
-    
-        term, expression = expression
-        if isinstance(term, Symbol):
-          term = dictionary[term]
-          stack, expression, dictionary = term(stack, expression, dictionary)
-        else:
-          stack = term, stack
-    
-      if viewer: viewer(stack, expression)
-      return stack, expression, dictionary
-    
 
 
 View function
 ~~~~~~~~~~~~~
 
-The ``joy()`` function accepts a "viewer" function which it calls on
+The ``joy()`` function accepts an optional ``viewer`` argument that
+is a function which it calls on
 each iteration passing the current stack and expression just before
 evaluation. This can be used for tracing, breakpoints, retrying after
 exceptions, or interrupting an evaluation and saving to disk or sending
 over the network to resume later. The stack and expression together
 contain all the state of the computation at each step.
 
+
 The ``TracePrinter``.
 ~~~~~~~~~~~~~~~~~~~~~
 
@@ -254,108 +114,55 @@ evaluation, one line per step. Each step is aligned to the current
 interpreter position, signified by a period separating the stack on the
 left from the pending expression ("continuation") on the right.
 
-`Continuation-Passing Style <https://en.wikipedia.org/wiki/Continuation-passing_style>`__
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-One day I thought, What happens if you rewrite Joy to use
-`CSP <https://en.wikipedia.org/wiki/Continuation-passing_style>`__? I
-made all the functions accept and return the expression as well as the
-stack and found that all the combinators could be rewritten to work by
-modifying the expression rather than making recursive calls to the
-``joy()`` function.
 
 Parser
 ======
 
-.. code:: ipython2
+The parser is extremely simple.  The undocumented ``re.Scanner`` class
-
+does the tokenizing and then the parser builds the tuple
-    import joy.parser
-    
-    print inspect.getdoc(joy.parser)
-
-
-.. parsed-literal::
-
-    § Converting text to a joy expression.
-    
-    This module exports a single function:
-    
-      text_to_expression(text)
-    
-    As well as a single Symbol class and a single Exception type:
-    
-      ParseError
-    
-    When supplied with a string this function returns a Python datastructure
-    that represents the Joy datastructure described by the text expression.
-    Any unbalanced square brackets will raise a ParseError.
-
-
-The parser is extremely simple, the undocumented ``re.Scanner`` class
-does most of the tokenizing work and then you just build the tuple
 structure out of the tokens. There's no Abstract Syntax Tree or anything
 like that.
 
-.. code:: ipython2
 
-    print inspect.getsource(joy.parser._parse)
+Symbols
+~~~~~~~~~~~~~
+
+TODO: Symbols are just a string subclass; used by the parser to represent function names and by the interpreter to look up functions in the dictionary.  N.B.: Symbols are not looked up at parse-time.  You *could* define recursive functions, er, recusively, without ``genrec`` or other recursion combinators  ``foo == ... foo ...`` but don't do that.
 
 
-.. parsed-literal::
+Token Regular Expressions
+~~~~~~~~~~~~~~~~~~~~~~~~~
 
-    def _parse(tokens):
+::
-      '''
+
-      Return a stack/list expression of the tokens.
+    123   1.2   'single quotes'  "double quotes"   function
-      '''
+
-      frame = []
+TBD (look in the :module: joy.parser  module.)
-      stack = []
-      for tok in tokens:
-        if tok == '[':
-          stack.append(frame)
-          frame = []
-          stack[-1].append(frame)
-        elif tok == ']':
-          try:
-            frame = stack.pop()
-          except IndexError:
-            raise ParseError('One or more extra closing brackets.')
-          frame[-1] = list_to_stack(frame[-1])
-        else:
-          frame.append(tok)
-      if stack:
-        raise ParseError('One or more unclosed brackets.')
-      return list_to_stack(frame)
-    
 
 
-That's pretty much all there is to it.
+Examples
+~~~~~~~~~~~
 
 .. code:: ipython2
 
     joy.parser.text_to_expression('1 2 3 4 5')  # A simple sequence.
 
 
-
-
 .. parsed-literal::
 
     (1, (2, (3, (4, (5, ())))))
 
 
-
 .. code:: ipython2
 
     joy.parser.text_to_expression('[1 2 3] 4 5')  # Three items, the first is a list with three items
 
 
-
-
 .. parsed-literal::
 
     ((1, (2, (3, ()))), (4, (5, ())))
 
 
-
 .. code:: ipython2
 
     joy.parser.text_to_expression('1 23 ["four" [-5.0] cons] 8888')  # A mixed bag. cons is
@@ -364,7 +171,6 @@ That's pretty much all there is to it.
 
 
 
-
 .. parsed-literal::
 
     (1, (23, (('four', ((-5.0, ()), (cons, ()))), (8888, ()))))
@@ -406,18 +212,6 @@ the Joy system. There are simple functions such as addition ``add`` (or
 ``+``, the library module supports aliases), and combinators which
 provide control-flow and higher-order operations.
 
-.. code:: ipython2
-
-    import joy.library
-    
-    print ' '.join(sorted(joy.library.initialize()))
-
-
-.. parsed-literal::
-
-    != % & * *fraction *fraction0 + ++ - -- / < << <= <> = > >= >> ? ^ add anamorphism and app1 app2 app3 average b binary branch choice clear cleave concat cons dinfrirst dip dipd dipdd disenstacken div down_to_zero dudipd dup dupd dupdip enstacken eq first flatten floordiv gcd ge genrec getitem gt help i id ifte infra le least_fraction loop lshift lt map min mod modulus mul ne neg not nullary or over pam parse pm pop popd popdd popop pow pred primrec product quoted range range_to_zero rem remainder remove rest reverse roll< roll> rolldown rollup rshift run second select sharing shunt size sqr sqrt stack step sub succ sum swaack swap swoncat swons ternary third times truediv truthy tuck unary uncons unit unquoted unstack void warranty while words x xor zip •
-
-
 Many of the functions are defined in Python, like ``dip``:
 
 .. code:: ipython2
@@ -433,7 +227,6 @@ Many of the functions are defined in Python, like ``dip``:
       return stack, pushback(quote, expression), dictionary
     
 
-
 Some functions are defined in equations in terms of other functions.
 When the interpreter executes a definition function that function just
 pushes its body expression onto the pending expression (the
@@ -496,7 +289,7 @@ datastructures (which only contain symbols, not the actual functions.
 Pickle some and see for yourself.)
 
 "There should be only one."
-^^^^^^^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Which brings me to talking about one of my hopes and dreams for this
 notation: "There should be only one." What I mean is that there should
@@ -516,7 +309,7 @@ attack <https://en.wikipedia.org/wiki/Thundering_herd_problem>`__ on
 human mentality.
 
 Literary Code Library
-^^^^^^^^^^^^^^^^^^^^^
+~~~~~~~~~~~~~~~~~~~~~
 
 If you read over the other notebooks you'll see that developing code in
 Joy is a lot like doing simple mathematics, and the descriptions of the

docs/sphinx_docs/notebooks/NoUpdates.rst

@@ -0,0 +1,22 @@
+
+**************
+No Updates
+**************
+
+DRAFT
+
+1. Joy doesn't need to change.
+
+  A. The interpreter doesn't need to change, ``viewer`` function can customize mainloop.  Or use a sub-interpreter (Joy in Joy.)  The base interpreter remains static.
+  B. Once a function has been named and defined *never change that name*.  It's just not allowed.  If you need to change a function ``foo`` you have to call it ``foo_II`` or something.  Once a function (name mapped to behavior) is released to the public *that's it*, it's done.
+  C. The language evolves by adding new definitions and refactoring, always choosing new names for new functions.
+
+2. Following `Semantic Versioning`_ there will never be a version 2.0.
+
+  A. `Major version must be incremented if any backwards incompatible changes are introduced to the public API. <https://semver.org/#spec-item-8>`__
+  B. We never implement any backwards incompatible changes, so...
+  C. We could see e.g. Thun version 1.273.3!
+
+
+.. _Semantic Versioning: https://semver.org
+