T's and U's.

diff --git a/docs/reference/mkref/FuncRef.html b/docs/reference/mkref/FuncRef.html
index 7a4565d..879fc2e 100644 (file)
--- a/docs/reference/mkref/FuncRef.html
+++ b/docs/reference/mkref/FuncRef.html
@@ -2276,256 +2276,226 @@ a F a</code></pre>
 </blockquote>
 <hr />
 <h2 id="tailrec">tailrec</h2>
-<p>Basis Function Combinator</p>
-<p>[i] genrec</p>
-<p>Gentzen diagram.</p>
+<p>Combinator</p>
+<p>A specialization of the <a href="#genrec">genrec</a> combinator.</p>
 <h3 id="definition-92">Definition</h3>
-<p>if not basis.</p>
-<h3 id="derivation-3">Derivation</h3>
-<p>if not basis.</p>
-<h3 id="source">Source</h3>
-<p>if basis</p>
+<blockquote>
+<p>[<a href="#i">i</a>] <a href="#genrec">genrec</a></p>
+</blockquote>
 <h3 id="discussion-69">Discussion</h3>
-<p>Lorem ipsum.</p>
+<p>Some recursive functions do not need to store additional data or pending actions per-call. These are called <a href="https://en.wikipedia.org/wiki/Tail_recursive">&#x201C;tail recursive&#x201D; functions</a>. In Joy, they appear as <a href="#genrec">genrec</a> definitions that have <a href="#i">i</a> for the second half of their recursive branch.</p>
+<p>See the <a href="https://joypy.osdn.io/notebooks/Recursion_Combinators.html">Recursion Combinators notebook</a>.</p>
 <h3 id="crosslinks-109">Crosslinks</h3>
-<p>Lorem ipsum.</p>
+<p><a href="#genrec">genrec</a></p>
 <hr />
 <h2 id="take">take</h2>
-<p>Basis Function Combinator</p>
-<p>Expects an integer and a quote on the stack and returns the quote with just the top n items in reverse order (because that's easier and you can use reverse if needed.) :</p>
-<pre><code>[a b c d] 2 take
+<p>Function</p>
+<p>Expects an integer <code>n</code> and a list on the stack and replace them with a list with just the top <code>n</code> items in reverse order.</p>
+<pre><code>   [a b c d] 2 take
 ----------------------
-    [b a]</code></pre>
-<p>Gentzen diagram.</p>
+        [b a]</code></pre>
 <h3 id="definition-93">Definition</h3>
-<p>if not basis.</p>
-<h3 id="derivation-4">Derivation</h3>
-<p>if not basis.</p>
-<h3 id="source-1">Source</h3>
-<p>if basis</p>
-<h3 id="discussion-70">Discussion</h3>
-<p>Lorem ipsum.</p>
-<h3 id="crosslinks-110">Crosslinks</h3>
-<p>Lorem ipsum.</p>
+<blockquote>
+<p><a href="#section-18">&lt;&lt;{}</a> [<a href="#shift">shift</a>] <a href="#times">times</a> <a href="#pop">pop</a></p>
+</blockquote>
 <hr />
 <h2 id="ternary">ternary</h2>
-<p>(Combinator)</p>
+<p>Combinator</p>
 <p>Run a quoted program using exactly three stack values and leave the first item of the result on the stack.</p>
-<pre><code>   ... z y x [P] unary
+<pre><code>   ... z y x [P] ternary
 -------------------------
-         ... A</code></pre>
+         ... a</code></pre>
 <h3 id="definition-94">Definition</h3>
-<pre><code>binary popd</code></pre>
-<h3 id="discussion-71">Discussion</h3>
+<blockquote>
+<p><a href="#binary">binary</a> <a href="#popd">popd</a></p>
+</blockquote>
+<h3 id="discussion-70">Discussion</h3>
 <p>Runs any other quoted function and returns its first result while consuming exactly three items from the stack.</p>
-<h3 id="crosslinks-111">Crosslinks</h3>
+<h3 id="crosslinks-110">Crosslinks</h3>
 <p><a href="#binary">binary</a> <a href="#nullary">nullary</a> <a href="#unary">unary</a></p>
 <hr />
 <h2 id="third">third</h2>
-<p>Basis Function Combinator</p>
-<pre><code>([a1 a2 a3 ...1] -- a3)</code></pre>
-<p>Gentzen diagram.</p>
+<p>Function</p>
+<pre><code>   [a b c ...] third
+-----------------------
+           c</code></pre>
 <h3 id="definition-95">Definition</h3>
-<p>if not basis.</p>
-<h3 id="derivation-5">Derivation</h3>
-<p>if not basis.</p>
-<h3 id="source-2">Source</h3>
-<p>if basis</p>
-<h3 id="discussion-72">Discussion</h3>
-<p>Lorem ipsum.</p>
-<h3 id="crosslinks-112">Crosslinks</h3>
-<p>Lorem ipsum.</p>
+<blockquote>
+<p><a href="#rest">rest</a> <a href="#second">second</a></p>
+</blockquote>
+<h3 id="crosslinks-111">Crosslinks</h3>
+<p><a href="#first">first</a> <a href="#second">second</a> <a href="#fourth">fourth</a> <a href="#rest">rest</a></p>
 <hr />
 <h2 id="times">times</h2>
-<p>Basis Function Combinator</p>
-<p>times == [-- dip] cons [swap] infra [0 &gt;] swap while pop :</p>
-<pre><code>... n [Q] . times
----------------------  w/ n &lt;= 0
-  ... .
-
+<p>Combinator</p>
+<p>Expect a quoted program and an integer <code>n</code> on the stack and do the program <code>n</code> times.</p>
+<pre><code>   ... n [Q] . times
+-----------------------  w/ n &lt;= 0
+         ... .
 
-... 1 [Q] . times
+   ... 1 [Q] . times
 -----------------------
-  ... . Q
-
+         ... . Q
 
-... n [Q] . times
+   ... n [Q] . times
 -------------------------------------  w/ n &gt; 1
-  ... . Q (n - 1) [Q] times</code></pre>
-<p>Gentzen diagram.</p>
+         ... . Q (n-1) [Q] times</code></pre>
 <h3 id="definition-96">Definition</h3>
-<p>if not basis.</p>
-<h3 id="derivation-6">Derivation</h3>
-<p>if not basis.</p>
-<h3 id="source-3">Source</h3>
-<p>if basis</p>
-<h3 id="discussion-73">Discussion</h3>
-<p>Lorem ipsum.</p>
-<h3 id="crosslinks-113">Crosslinks</h3>
-<p>Lorem ipsum.</p>
+<blockquote>
+<p>[-- dip] cons [swap] infra [0 &gt;] swap while pop :</p>
+</blockquote>
+<h3 id="discussion-71">Discussion</h3>
+<p>This works by building a little <a href="#while">while</a> program and running it:</p>
+<pre><code>                 1 3 [++] &#x2022; [-- dip] cons [swap] infra [0 &gt;] swap while pop                                                                                                                 
+        1 3 [++] [-- dip] &#x2022; cons [swap] infra [0 &gt;] swap while pop                                                                                                                          
+        1 3 [[++] -- dip] &#x2022; [swap] infra [0 &gt;] swap while pop                                                                                                                               
+ 1 3 [[++] -- dip] [swap] &#x2022; infra [0 &gt;] swap while pop                                                                                                                                      
+              dip -- [++] &#x2022; swap [3 1] swaack [0 &gt;] swap while pop                                                                                                                          
+              dip [++] -- &#x2022; [3 1] swaack [0 &gt;] swap while pop                                                                                                                               
+        dip [++] -- [3 1] &#x2022; swaack [0 &gt;] swap while pop                                                                                                                                     
+        1 3 [-- [++] dip] &#x2022; [0 &gt;] swap while pop                                                                                                                                            
+  1 3 [-- [++] dip] [0 &gt;] &#x2022; swap while pop                                                                                                                                                  
+  1 3 [0 &gt;] [-- [++] dip] &#x2022; while pop                                                                                                                                                       </code></pre>
+<p>This is a common pattern in Joy. You accept some parameters from the stack which typically include qouted programs and use them to build another program which does the actual work. This is kind of like macros in Lisp, or preprocessor directives in C.</p>
 <hr />
 <h2 id="truthy">truthy</h2>
 <p>See <a href="#bool">bool</a>.</p>
 <hr />
 <h2 id="tuck">tuck</h2>
-<p>Basis Function Combinator</p>
-<pre><code>(a2 a1 -- a1 a2 a1)</code></pre>
-<p>Gentzen diagram.</p>
+<p>Function</p>
+<p><a href="#dup">dup</a> the item on the top of the stack under the second item on the stack.</p>
+<pre><code>   a b tuck
+--------------
+    b a b</code></pre>
 <h3 id="definition-97">Definition</h3>
-<p>if not basis.</p>
-<h3 id="derivation-7">Derivation</h3>
-<p>if not basis.</p>
-<h3 id="source-4">Source</h3>
-<p>if basis</p>
-<h3 id="discussion-74">Discussion</h3>
-<p>Lorem ipsum.</p>
-<h3 id="crosslinks-114">Crosslinks</h3>
-<p>Lorem ipsum.</p>
+<blockquote>
+<p><a href="#dup">dup</a> [<a href="#swap">swap</a>] <a href="#dip">dip</a></p>
+</blockquote>
+<h3 id="crosslinks-112">Crosslinks</h3>
+<p><a href="#over">over</a></p>
 <hr />
 <h2 id="unary">unary</h2>
 <p>(Combinator)</p>
 <p>Run a quoted program using exactly one stack value and leave the first item of the result on the stack.</p>
 <pre><code>   ... x [P] unary
 ---------------------
-       ... A</code></pre>
+       ... a</code></pre>
 <h3 id="definition-98">Definition</h3>
-<pre><code>nullary popd</code></pre>
-<h3 id="discussion-75">Discussion</h3>
+<blockquote>
+<p><a href="#nullary">nullary</a> <a href="#popd">popd</a></p>
+</blockquote>
+<h3 id="discussion-72">Discussion</h3>
 <p>Runs any other quoted function and returns its first result while consuming exactly one item from the stack.</p>
-<h3 id="crosslinks-115">Crosslinks</h3>
+<h3 id="crosslinks-113">Crosslinks</h3>
 <p><a href="#binary">binary</a> <a href="#nullary">nullary</a> <a href="#ternary">ternary</a></p>
 <hr />
 <h2 id="uncons">uncons</h2>
-<p>(Basis Function)</p>
+<p>Basis Function</p>
 <p>Removes an item from a list and leaves it on the stack under the rest of the list. You cannot <code>uncons</code> an item from an empty list.</p>
-<pre><code>   [A ...] uncons
+<pre><code>   [a ...] uncons
 --------------------
-      A [...]</code></pre>
-<h3 id="source-5">Source</h3>
-<pre><code>func(uncons, Si, So) :- func(cons, So, Si).</code></pre>
-<h3 id="discussion-76">Discussion</h3>
-<p>This is the inverse of <code>cons</code>.</p>
-<h3 id="crosslinks-116">Crosslinks</h3>
+      a [...]</code></pre>
+<h3 id="discussion-73">Discussion</h3>
+<p>This is the inverse of <a href="#cons">cons</a>.</p>
+<h3 id="crosslinks-114">Crosslinks</h3>
 <p><a href="#cons">cons</a></p>
 <hr />
 <h2 id="unique">unique</h2>
-<p>Basis Function Combinator</p>
+<p>Function</p>
 <p>Given a list remove duplicate items.</p>
-<p>Gentzen diagram.</p>
-<h3 id="definition-99">Definition</h3>
-<p>if not basis.</p>
-<h3 id="derivation-8">Derivation</h3>
-<p>if not basis.</p>
-<h3 id="source-6">Source</h3>
-<p>if basis</p>
-<h3 id="discussion-77">Discussion</h3>
-<p>Lorem ipsum.</p>
-<h3 id="crosslinks-117">Crosslinks</h3>
-<p>Lorem ipsum.</p>
 <hr />
 <h2 id="unit">unit</h2>
-<p>Basis Function Combinator</p>
-<pre><code>(a1 -- [a1 ])</code></pre>
-<p>Gentzen diagram.</p>
-<h3 id="definition-100">Definition</h3>
-<p>if not basis.</p>
-<h3 id="derivation-9">Derivation</h3>
-<p>if not basis.</p>
-<h3 id="source-7">Source</h3>
-<p>if basis</p>
-<h3 id="discussion-78">Discussion</h3>
-<p>Lorem ipsum.</p>
-<h3 id="crosslinks-118">Crosslinks</h3>
-<p>Lorem ipsum.</p>
+<p>Function</p>
+<pre><code>   a unit
+------------
+    [a]</code></pre>
+<h3 id="definition-99">Definition</h3>
+<blockquote>
+<p>[] <a href="#cons">cons</a></p>
+</blockquote>
 <hr />
 <h2 id="unquoted">unquoted</h2>
-<p>Basis Function Combinator</p>
-<p>[i] dip</p>
-<p>Gentzen diagram.</p>
-<h3 id="definition-101">Definition</h3>
-<p>if not basis.</p>
-<h3 id="derivation-10">Derivation</h3>
-<p>if not basis.</p>
-<h3 id="source-8">Source</h3>
-<p>if basis</p>
-<h3 id="discussion-79">Discussion</h3>
-<p>Lorem ipsum.</p>
-<h3 id="crosslinks-119">Crosslinks</h3>
-<p>Lorem ipsum.</p>
+<p>Combinator</p>
+<p>Unquote (using <a href="#i">i</a>) the list that is second on the stack.</p>
+<h3 id="example-31">Example</h3>
+<pre><code>   1 2 [3 4] 5 unquoted
+--------------------------
+         1 2 3 4 5</code></pre>
+<h3 id="definition-100">Definition</h3>
+<blockquote>
+<p>[<a href="#i">i</a>] <a href="#dip">dip</a></p>
+</blockquote>
+<h3 id="crosslinks-115">Crosslinks</h3>
+<p><a href="#unit">unit</a></p>
 <hr />
 <h2 id="unswons">unswons</h2>
-<p>Basis Function Combinator</p>
-<pre><code>([a1 ...1] -- [...1] a1)</code></pre>
-<p>Gentzen diagram.</p>
-<h3 id="definition-102">Definition</h3>
-<p>if not basis.</p>
-<h3 id="derivation-11">Derivation</h3>
-<p>if not basis.</p>
-<h3 id="source-9">Source</h3>
-<p>if basis</p>
-<h3 id="discussion-80">Discussion</h3>
-<p>Lorem ipsum.</p>
-<h3 id="crosslinks-120">Crosslinks</h3>
-<p>Lorem ipsum.</p>
+<p>Function</p>
+<pre><code>   [a ...] unswons
+---------------------
+       [...] a</code></pre>
+<h3 id="definition-101">Definition</h3>
+<blockquote>
+<p><a href="#uncons">uncons</a> <a href="#swap">swap</a></p>
+</blockquote>
 <hr />
 <h2 id="void">void</h2>
 <p>Basis Function Combinator</p>
 <p>True if the form on TOS is void otherwise False.</p>
 <p>Gentzen diagram.</p>
-<h3 id="definition-103">Definition</h3>
+<h3 id="definition-102">Definition</h3>
 <p>if not basis.</p>
-<h3 id="derivation-12">Derivation</h3>
+<h3 id="derivation-3">Derivation</h3>
 <p>if not basis.</p>
-<h3 id="source-10">Source</h3>
+<h3 id="source">Source</h3>
 <p>if basis</p>
-<h3 id="discussion-81">Discussion</h3>
+<h3 id="discussion-74">Discussion</h3>
 <p>Lorem ipsum.</p>
-<h3 id="crosslinks-121">Crosslinks</h3>
+<h3 id="crosslinks-116">Crosslinks</h3>
 <p>Lorem ipsum.</p>
 <hr />
 <h2 id="warranty">warranty</h2>
 <p>Basis Function Combinator</p>
 <p>Print warranty information.</p>
 <p>Gentzen diagram.</p>
-<h3 id="definition-104">Definition</h3>
+<h3 id="definition-103">Definition</h3>
 <p>if not basis.</p>
-<h3 id="derivation-13">Derivation</h3>
+<h3 id="derivation-4">Derivation</h3>
 <p>if not basis.</p>
-<h3 id="source-11">Source</h3>
+<h3 id="source-1">Source</h3>
 <p>if basis</p>
-<h3 id="discussion-82">Discussion</h3>
+<h3 id="discussion-75">Discussion</h3>
 <p>Lorem ipsum.</p>
-<h3 id="crosslinks-122">Crosslinks</h3>
+<h3 id="crosslinks-117">Crosslinks</h3>
 <p>Lorem ipsum.</p>
 <hr />
 <h2 id="while">while</h2>
 <p>Basis Function Combinator</p>
 <p>swap nulco dupdipd concat loop</p>
 <p>Gentzen diagram.</p>
-<h3 id="definition-105">Definition</h3>
+<h3 id="definition-104">Definition</h3>
 <p>if not basis.</p>
-<h3 id="derivation-14">Derivation</h3>
+<h3 id="derivation-5">Derivation</h3>
 <p>if not basis.</p>
-<h3 id="source-12">Source</h3>
+<h3 id="source-2">Source</h3>
 <p>if basis</p>
-<h3 id="discussion-83">Discussion</h3>
+<h3 id="discussion-76">Discussion</h3>
 <p>Lorem ipsum.</p>
-<h3 id="crosslinks-123">Crosslinks</h3>
+<h3 id="crosslinks-118">Crosslinks</h3>
 <p>Lorem ipsum.</p>
 <hr />
 <h2 id="words">words</h2>
 <p>Basis Function Combinator</p>
 <p>Print all the words in alphabetical order.</p>
 <p>Gentzen diagram.</p>
-<h3 id="definition-106">Definition</h3>
+<h3 id="definition-105">Definition</h3>
 <p>if not basis.</p>
-<h3 id="derivation-15">Derivation</h3>
+<h3 id="derivation-6">Derivation</h3>
 <p>if not basis.</p>
-<h3 id="source-13">Source</h3>
+<h3 id="source-3">Source</h3>
 <p>if basis</p>
-<h3 id="discussion-84">Discussion</h3>
+<h3 id="discussion-77">Discussion</h3>
 <p>Lorem ipsum.</p>
-<h3 id="crosslinks-124">Crosslinks</h3>
+<h3 id="crosslinks-119">Crosslinks</h3>
 <p>Lorem ipsum.</p>
 <hr />
 <h2 id="x">x</h2>
@@ -2533,39 +2503,39 @@ a F a</code></pre>
 <pre><code>   [F] x
 -----------
    [F] F</code></pre>
-<h3 id="definition-107">Definition</h3>
+<h3 id="definition-106">Definition</h3>
 <pre><code>dup i</code></pre>
-<h3 id="discussion-85">Discussion</h3>
+<h3 id="discussion-78">Discussion</h3>
 <p>The <code>x</code> combinator &#x2026;</p>
 <hr />
 <h2 id="xor">xor</h2>
 <p>Basis Function Combinator</p>
 <p>Same as a ^ b.</p>
 <p>Gentzen diagram.</p>
-<h3 id="definition-108">Definition</h3>
+<h3 id="definition-107">Definition</h3>
 <p>if not basis.</p>
-<h3 id="derivation-16">Derivation</h3>
+<h3 id="derivation-7">Derivation</h3>
 <p>if not basis.</p>
-<h3 id="source-14">Source</h3>
+<h3 id="source-4">Source</h3>
 <p>if basis</p>
-<h3 id="discussion-86">Discussion</h3>
+<h3 id="discussion-79">Discussion</h3>
 <p>Lorem ipsum.</p>
-<h3 id="crosslinks-125">Crosslinks</h3>
+<h3 id="crosslinks-120">Crosslinks</h3>
 <p>Lorem ipsum.</p>
 <hr />
 <h2 id="zip">zip</h2>
 <p>Basis Function Combinator</p>
 <p>Replace the two lists on the top of the stack with a list of the pairs from each list. The smallest list sets the length of the result list.</p>
 <p>Gentzen diagram.</p>
-<h3 id="definition-109">Definition</h3>
+<h3 id="definition-108">Definition</h3>
 <p>if not basis.</p>
-<h3 id="derivation-17">Derivation</h3>
+<h3 id="derivation-8">Derivation</h3>
 <p>if not basis.</p>
-<h3 id="source-15">Source</h3>
+<h3 id="source-5">Source</h3>
 <p>if basis</p>
-<h3 id="discussion-87">Discussion</h3>
+<h3 id="discussion-80">Discussion</h3>
 <p>Lorem ipsum.</p>
-<h3 id="crosslinks-126">Crosslinks</h3>
+<h3 id="crosslinks-121">Crosslinks</h3>
 <p>Lorem ipsum.</p>
 </body>
 </html>

diff --git a/docs/reference/mkref/Functor-Reference.md b/docs/reference/mkref/Functor-Reference.md
index 270312f..effdeaa 100644 (file)
--- a/docs/reference/mkref/Functor-Reference.md
+++ b/docs/reference/mkref/Functor-Reference.md
@@ -3656,85 +3656,62 @@ Like [cons] but [swap] the item and list.
 
 ## tailrec
 
-Basis Function Combinator
-
-\[i\] genrec
+Combinator
 
-Gentzen diagram.
+A specialization of the [genrec] combinator.
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
+> \[[i]\] [genrec]
 
 ### Discussion
 
-Lorem ipsum.
+Some recursive functions do not need to store additional data or pending
+actions per-call.  These are called ["tail recursive" functions](https://en.wikipedia.org/wiki/Tail_recursive).  In Joy,
+they appear as [genrec] definitions that have [i] for the second half of
+their recursive branch.
+
+See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html).
 
 ### Crosslinks
 
-Lorem ipsum.
+[genrec]
+
 
 ------------------------------------------------------------------------
 
 ## take
 
-Basis Function Combinator
+Function
 
-Expects an integer and a quote on the stack and returns the quote with
-just the top n items in reverse order (because that\'s easier and you
-can use reverse if needed.) :
+Expects an integer `n` and a list on the stack and replace them with a list
+with just the top `n` items in reverse order.
 
-    [a b c d] 2 take
+       [a b c d] 2 take
     ----------------------
-        [b a]
-
-Gentzen diagram.
+            [b a]
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
+> [\<\<\{\}] \[[shift]\] [times] [pop]
 
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
-
-### Crosslinks
-
-Lorem ipsum.
 
 --------------------
 
 ## ternary
 
-(Combinator)
-
+Combinator
 
 Run a quoted program using exactly three stack values and leave the first
 item of the result on the stack.
 
-       ... z y x [P] unary
+       ... z y x [P] ternary
     -------------------------
-             ... A
+             ... a
 
 ### Definition
 
-    binary popd
+> [binary] [popd]
 
 ### Discussion
 
@@ -3752,75 +3729,70 @@ consuming exactly three items from the stack.
 
 ## third
 
-Basis Function Combinator
-
-    ([a1 a2 a3 ...1] -- a3)
+Function
 
-Gentzen diagram.
+       [a b c ...] third
+    -----------------------
+               c
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
+> [rest] [second]
 
 ### Crosslinks
 
-Lorem ipsum.
+[first]
+[second]
+[fourth]
+[rest]
+
 
 ------------------------------------------------------------------------
 
 ## times
 
-Basis Function Combinator
-
-times == \[\-- dip\] cons \[swap\] infra \[0 \>\] swap while pop :
+Combinator
 
-    ... n [Q] . times
-    ---------------------  w/ n <= 0
-      ... .
+Expect a quoted program and an integer `n` on the stack and do the
+program `n` times.
 
+       ... n [Q] . times
+    -----------------------  w/ n <= 0
+             ... .
 
-    ... 1 [Q] . times
+       ... 1 [Q] . times
     -----------------------
-      ... . Q
+             ... . Q
 
-
-    ... n [Q] . times
+       ... n [Q] . times
     -------------------------------------  w/ n > 1
-      ... . Q (n - 1) [Q] times
-
-Gentzen diagram.
+             ... . Q (n-1) [Q] times
 
 ### Definition
 
-if not basis.
+> \[\-- dip\] cons \[swap\] infra \[0 \>\] swap while pop :
 
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
 
 ### Discussion
 
-Lorem ipsum.
+This works by building a little [while] program and running it:
 
-### Crosslinks
+                     1 3 [++] • [-- dip] cons [swap] infra [0 >] swap while pop                                                                                                                 
+            1 3 [++] [-- dip] • cons [swap] infra [0 >] swap while pop                                                                                                                          
+            1 3 [[++] -- dip] • [swap] infra [0 >] swap while pop                                                                                                                               
+     1 3 [[++] -- dip] [swap] • infra [0 >] swap while pop                                                                                                                                      
+                  dip -- [++] • swap [3 1] swaack [0 >] swap while pop                                                                                                                          
+                  dip [++] -- • [3 1] swaack [0 >] swap while pop                                                                                                                               
+            dip [++] -- [3 1] • swaack [0 >] swap while pop                                                                                                                                     
+            1 3 [-- [++] dip] • [0 >] swap while pop                                                                                                                                            
+      1 3 [-- [++] dip] [0 >] • swap while pop                                                                                                                                                  
+      1 3 [0 >] [-- [++] dip] • while pop                                                                                                                                                       
+
+This is a common pattern in Joy.  You accept some parameters from the
+stack which typically include qouted programs and use them to build
+another program which does the actual work.  This is kind of like macros
+in Lisp, or preprocessor directives in C.
 
-Lorem ipsum.
 
 --------------
 
@@ -3833,31 +3805,23 @@ See [bool](#bool).
 
 ## tuck
 
-Basis Function Combinator
+Function
 
-    (a2 a1 -- a1 a2 a1)
+[dup] the item on the top of the stack under the second item on the
+stack.
 
-Gentzen diagram.
+       a b tuck
+    --------------
+        b a b
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
+> [dup] \[[swap]\] [dip]
 
 ### Crosslinks
 
-Lorem ipsum.
+[over]
+
 
 --------------------
 
@@ -3865,15 +3829,16 @@ Lorem ipsum.
 
 (Combinator)
 
-Run a quoted program using exactly one stack value and leave the first item of the result on the stack.
+Run a quoted program using exactly one stack value and leave the first
+item of the result on the stack.
 
        ... x [P] unary
     ---------------------
-           ... A
+           ... a
 
 ### Definition
 
-    nullary popd
+> [nullary] [popd]
 
 ### Discussion
 
@@ -3891,147 +3856,85 @@ consuming exactly one item from the stack.
 
 ## uncons
 
-(Basis Function)
+Basis Function
 
 Removes an item from a list and leaves it on the stack under the rest of
 the list.  You cannot `uncons` an item from an empty list.
 
-       [A ...] uncons
+       [a ...] uncons
     --------------------
-          A [...]
-
-### Source
-
-    func(uncons, Si, So) :- func(cons, So, Si).
+          a [...]
 
 ### Discussion
 
-This is the inverse of `cons`.
+This is the inverse of [cons].
 
 ### Crosslinks
 
-[cons](#cons)
+[cons]
 
 
 ------------------------------------------------------------------------
 
 ## unique
 
-Basis Function Combinator
+Function
 
 Given a list remove duplicate items.
 
-Gentzen diagram.
-
-### Definition
-
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
-
-### Crosslinks
-
-Lorem ipsum.
 
 ------------------------------------------------------------------------
 
 ## unit
 
-Basis Function Combinator
-
-    (a1 -- [a1 ])
+Function
 
-Gentzen diagram.
+       a unit
+    ------------
+        [a]
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
+> \[\] [cons]
 
-### Crosslinks
-
-Lorem ipsum.
 
 ------------------------------------------------------------------------
 
 ## unquoted
 
-Basis Function Combinator
-
-\[i\] dip
-
-Gentzen diagram.
-
-### Definition
-
-if not basis.
-
-### Derivation
+Combinator
 
-if not basis.
+Unquote (using [i]) the list that is second on the stack.
 
-### Source
+### Example
 
-if basis
+       1 2 [3 4] 5 unquoted
+    --------------------------
+             1 2 3 4 5
 
-### Discussion
+### Definition
 
-Lorem ipsum.
+> \[[i]\] [dip]
 
 ### Crosslinks
 
-Lorem ipsum.
+[unit]
+
 
 ------------------------------------------------------------------------
 
 ## unswons
 
-Basis Function Combinator
-
-    ([a1 ...1] -- [...1] a1)
+Function
 
-Gentzen diagram.
+       [a ...] unswons
+    ---------------------
+           [...] a
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
+> [uncons] [swap]
 
-### Crosslinks
-
-Lorem ipsum.
 
 ------------------------------------------------------------------------
 

diff --git a/docs/reference/tailrec.md b/docs/reference/tailrec.md
index ed5d81e..470a369 100644 (file)
--- a/docs/reference/tailrec.md
+++ b/docs/reference/tailrec.md
@@ -2,28 +2,24 @@
 
 ## tailrec
 
-Basis Function Combinator
+Combinator
 
-\[i\] genrec
-
-Gentzen diagram.
+A specialization of the [genrec] combinator.
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
+> \[[i]\] [genrec]
 
 ### Discussion
 
-Lorem ipsum.
+Some recursive functions do not need to store additional data or pending
+actions per-call.  These are called ["tail recursive" functions](https://en.wikipedia.org/wiki/Tail_recursive).  In Joy,
+they appear as [genrec] definitions that have [i] for the second half of
+their recursive branch.
+
+See the [Recursion Combinators notebook](https://joypy.osdn.io/notebooks/Recursion_Combinators.html).
 
 ### Crosslinks
 
-Lorem ipsum.
+[genrec]
+

diff --git a/docs/reference/take.md b/docs/reference/take.md
index d16a1fe..18b3818 100644 (file)
--- a/docs/reference/take.md
+++ b/docs/reference/take.md
@@ -2,34 +2,16 @@
 
 ## take
 
-Basis Function Combinator
+Function
 
-Expects an integer and a quote on the stack and returns the quote with
-just the top n items in reverse order (because that\'s easier and you
-can use reverse if needed.) :
+Expects an integer `n` and a list on the stack and replace them with a list
+with just the top `n` items in reverse order.
 
-    [a b c d] 2 take
+       [a b c d] 2 take
     ----------------------
-        [b a]
-
-Gentzen diagram.
+            [b a]
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
-
-### Crosslinks
+> [\<\<\{\}] \[[shift]\] [times] [pop]
 
-Lorem ipsum.

diff --git a/docs/reference/ternary.md b/docs/reference/ternary.md
index 856b162..1b80944 100644 (file)
--- a/docs/reference/ternary.md
+++ b/docs/reference/ternary.md
@@ -2,19 +2,18 @@
 
 ## ternary
 
-(Combinator)
-
+Combinator
 
 Run a quoted program using exactly three stack values and leave the first
 item of the result on the stack.
 
-       ... z y x [P] unary
+       ... z y x [P] ternary
     -------------------------
-             ... A
+             ... a
 
 ### Definition
 
-    binary popd
+> [binary] [popd]
 
 ### Discussion
 

diff --git a/docs/reference/third.md b/docs/reference/third.md
index dc74576..ae482b1 100644 (file)
--- a/docs/reference/third.md
+++ b/docs/reference/third.md
@@ -2,28 +2,20 @@
 
 ## third
 
-Basis Function Combinator
+Function
 
-    ([a1 a2 a3 ...1] -- a3)
-
-Gentzen diagram.
+       [a b c ...] third
+    -----------------------
+               c
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
+> [rest] [second]
 
 ### Crosslinks
 
-Lorem ipsum.
+[first]
+[second]
+[fourth]
+[rest]
+

diff --git a/docs/reference/times.md b/docs/reference/times.md
index d64acde..eae8e4f 100644 (file)
--- a/docs/reference/times.md
+++ b/docs/reference/times.md
@@ -2,42 +2,45 @@
 
 ## times
 
-Basis Function Combinator
+Combinator
 
-times == \[\-- dip\] cons \[swap\] infra \[0 \>\] swap while pop :
+Expect a quoted program and an integer `n` on the stack and do the
+program `n` times.
 
-    ... n [Q] . times
-    ---------------------  w/ n <= 0
-      ... .
+       ... n [Q] . times
+    -----------------------  w/ n <= 0
+             ... .
 
-
-    ... 1 [Q] . times
+       ... 1 [Q] . times
     -----------------------
-      ... . Q
-
+             ... . Q
 
-    ... n [Q] . times
+       ... n [Q] . times
     -------------------------------------  w/ n > 1
-      ... . Q (n - 1) [Q] times
-
-Gentzen diagram.
+             ... . Q (n-1) [Q] times
 
 ### Definition
 
-if not basis.
-
-### Derivation
+> \[\-- dip\] cons \[swap\] infra \[0 \>\] swap while pop :
 
-if not basis.
-
-### Source
-
-if basis
 
 ### Discussion
 
-Lorem ipsum.
+This works by building a little [while] program and running it:
+
+                     1 3 [++] • [-- dip] cons [swap] infra [0 >] swap while pop                                                                                                                 
+            1 3 [++] [-- dip] • cons [swap] infra [0 >] swap while pop                                                                                                                          
+            1 3 [[++] -- dip] • [swap] infra [0 >] swap while pop                                                                                                                               
+     1 3 [[++] -- dip] [swap] • infra [0 >] swap while pop                                                                                                                                      
+                  dip -- [++] • swap [3 1] swaack [0 >] swap while pop                                                                                                                          
+                  dip [++] -- • [3 1] swaack [0 >] swap while pop                                                                                                                               
+            dip [++] -- [3 1] • swaack [0 >] swap while pop                                                                                                                                     
+            1 3 [-- [++] dip] • [0 >] swap while pop                                                                                                                                            
+      1 3 [-- [++] dip] [0 >] • swap while pop                                                                                                                                                  
+      1 3 [0 >] [-- [++] dip] • while pop                                                                                                                                                       
 
-### Crosslinks
+This is a common pattern in Joy.  You accept some parameters from the
+stack which typically include qouted programs and use them to build
+another program which does the actual work.  This is kind of like macros
+in Lisp, or preprocessor directives in C.
 
-Lorem ipsum.

diff --git a/docs/reference/tuck.md b/docs/reference/tuck.md
index d0700de..2668fc0 100644 (file)
--- a/docs/reference/tuck.md
+++ b/docs/reference/tuck.md
@@ -2,28 +2,20 @@
 
 ## tuck
 
-Basis Function Combinator
+Function
 
-    (a2 a1 -- a1 a2 a1)
+[dup] the item on the top of the stack under the second item on the
+stack.
 
-Gentzen diagram.
+       a b tuck
+    --------------
+        b a b
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
+> [dup] \[[swap]\] [dip]
 
 ### Crosslinks
 
-Lorem ipsum.
+[over]
+

diff --git a/docs/reference/unary.md b/docs/reference/unary.md
index ccd3ea4..a03cd7e 100644 (file)
--- a/docs/reference/unary.md
+++ b/docs/reference/unary.md
@@ -4,15 +4,16 @@
 
 (Combinator)
 
-Run a quoted program using exactly one stack value and leave the first item of the result on the stack.
+Run a quoted program using exactly one stack value and leave the first
+item of the result on the stack.
 
        ... x [P] unary
     ---------------------
-           ... A
+           ... a
 
 ### Definition
 
-    nullary popd
+> [nullary] [popd]
 
 ### Discussion
 

diff --git a/docs/reference/uncons.md b/docs/reference/uncons.md
index 39f1d63..647c92d 100644 (file)
--- a/docs/reference/uncons.md
+++ b/docs/reference/uncons.md
@@ -2,24 +2,20 @@
 
 ## uncons
 
-(Basis Function)
+Basis Function
 
 Removes an item from a list and leaves it on the stack under the rest of
 the list.  You cannot `uncons` an item from an empty list.
 
-       [A ...] uncons
+       [a ...] uncons
     --------------------
-          A [...]
-
-### Source
-
-    func(uncons, Si, So) :- func(cons, So, Si).
+          a [...]
 
 ### Discussion
 
-This is the inverse of `cons`.
+This is the inverse of [cons].
 
 ### Crosslinks
 
-[cons](#cons)
+[cons]
 

diff --git a/docs/reference/unique.md b/docs/reference/unique.md
index 687876c..2cc39c9 100644 (file)
--- a/docs/reference/unique.md
+++ b/docs/reference/unique.md
@@ -2,28 +2,7 @@
 
 ## unique
 
-Basis Function Combinator
+Function
 
 Given a list remove duplicate items.
 
-Gentzen diagram.
-
-### Definition
-
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
-
-### Crosslinks
-
-Lorem ipsum.

diff --git a/docs/reference/unit.md b/docs/reference/unit.md
index ccd479e..0bfa28a 100644 (file)
--- a/docs/reference/unit.md
+++ b/docs/reference/unit.md
@@ -2,28 +2,13 @@
 
 ## unit
 
-Basis Function Combinator
+Function
 
-    (a1 -- [a1 ])
-
-Gentzen diagram.
+       a unit
+    ------------
+        [a]
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
-
-### Crosslinks
+> \[\] [cons]
 
-Lorem ipsum.

diff --git a/docs/reference/unquoted.md b/docs/reference/unquoted.md
index 6f44120..6f508b1 100644 (file)
--- a/docs/reference/unquoted.md
+++ b/docs/reference/unquoted.md
@@ -2,28 +2,21 @@
 
 ## unquoted
 
-Basis Function Combinator
+Combinator
 
-\[i\] dip
+Unquote (using [i]) the list that is second on the stack.
 
-Gentzen diagram.
+### Example
 
-### Definition
-
-if not basis.
-
-### Derivation
-
-if not basis.
+       1 2 [3 4] 5 unquoted
+    --------------------------
+             1 2 3 4 5
 
-### Source
-
-if basis
-
-### Discussion
+### Definition
 
-Lorem ipsum.
+> \[[i]\] [dip]
 
 ### Crosslinks
 
-Lorem ipsum.
+[unit]
+

diff --git a/docs/reference/unswons.md b/docs/reference/unswons.md
index 0fe4953..52bf383 100644 (file)
--- a/docs/reference/unswons.md
+++ b/docs/reference/unswons.md
@@ -2,28 +2,13 @@
 
 ## unswons
 
-Basis Function Combinator
+Function
 
-    ([a1 ...1] -- [...1] a1)
-
-Gentzen diagram.
+       [a ...] unswons
+    ---------------------
+           [...] a
 
 ### Definition
 
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
-
-### Crosslinks
+> [uncons] [swap]
 
-Lorem ipsum.

diff --git a/implementations/defs.txt b/implementations/defs.txt
index 33a5311..c152e90 100644 (file)
--- a/implementations/defs.txt
+++ b/implementations/defs.txt
@@ -90,7 +90,7 @@ swons swap cons
 swoncat swap concat
 sqr dup mul
 tailrec [i] genrec
-take [] roll> [shift] times pop
+take <<{} [shift] times pop
 ternary binary popd
 third rest second
 tuck dup swapd