Most of the C's.

docs/reference/ccccons.md

@@ -2,28 +2,19 @@
 
 ## ccccons
 
-Basis Function Combinator
+Function
 
-ccons ccons
+       a b c d [...] ccccons
+    ---------------------------
+           [a b c d ...]
 
-Gentzen diagram.
+Do [cons] four times.
 
 ### Definition
 
-if not basis.
+> [ccons] [ccons]
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
 
 ### Crosslinks
 
-Lorem ipsum.
+[ccons] [cons] [times]
+

docs/reference/ccons.md

@@ -2,23 +2,20 @@
 
 ## ccons
 
-(Function)
+Function
 
-Given two items and a list, append the items to the list to make a new list.
+       a b [...] ccons
-
-       B A [...] ccons
     ---------------------
-          [B A ...]
+          [a b ...]
+
+Do [cons] two times.
 
 ### Definition
 
-    cons cons
+> [cons] [cons]
-
-### Discussion
-
-Does `cons` twice.
 
 ### Crosslinks
 
-[cons](#cons)
+[cons]
+[ccons]
 

docs/reference/choice.md

@@ -2,41 +2,29 @@
 
 ## choice
 
-Basis Function Combinator
+Basis Function
 
-Use a Boolean value to select one of two items. :
+Use a Boolean value to select one of two items.
 
-    A B false choice
+       a b false choice
     ----------------------
-    A
+              a
 
-
+       a b true choice
-    A B true choice
     ---------------------
-      B
+              b
-
-Currently Python semantics are used to evaluate the \"truthiness\" of
-the Boolean value (so empty string, zero, etc. are counted as false,
-etc.)
-
-Gentzen diagram.
 
 ### Definition
 
-if not basis.
+> \[[pop]\] \[[popd]\] [branch]
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
 
 ### Discussion
 
-Lorem ipsum.
+It's a matter of taste whether you implement this in terms of [branch] or
+the other way around.
 
 ### Crosslinks
 
-Lorem ipsum.
+[branch]
+[select]
+

docs/reference/clear.md

@@ -2,33 +2,16 @@
 
 ## clear
 
-Basis Function Combinator
+Basis Function
 
 Clear everything from the stack.
 
-:   clear == stack [pop stack] loop
-
-           ... clear
-        ---------------
-
-Gentzen diagram.
-
 ### Definition
 
-if not basis.
+> [stack] [bool] \[[pop] [stack] [bool]\] [loop]
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
 
 ### Crosslinks
 
-Lorem ipsum.
+[stack]
+[swaack]
+

docs/reference/cleave.md

@@ -2,28 +2,32 @@
 
 ## cleave
 
-Basis Function Combinator
+Combinator
 
-fork popdd
+Run two programs in parallel, consuming one additional item, and put their
+results on the stack.
 
-Gentzen diagram.
+       ... x [A] [B] cleave
-
+    ------------------------
-### Definition
+            ... a b
-
-if not basis.
 
 ### Derivation
 
-if not basis.
+> [fork] [popdd]
 
-### Source
+### Example
 
-if basis
+       1 2 3 [+] [-] cleave
+    --------------------------
+             1 2 5 -1
 
 ### Discussion
 
-Lorem ipsum.
+One of a handful of useful parallel combinators.
 
 ### Crosslinks
 
-Lorem ipsum.
+[clop]
+[fork]
+[map]
+

docs/reference/clop.md

@@ -2,28 +2,29 @@
 
 ## clop
 
-Basis Function Combinator
+Combinator
 
-cleave popdd
+Run two programs in parallel, consuming two additional items, and put their results on the stack.
 
-Gentzen diagram.
+       ... x y [A] [B] clop
+    --------------------------
+            ... a b
 
 ### Definition
 
-if not basis.
+> [cleave] [popdd]
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
 
 ### Discussion
 
-Lorem ipsum.
+Like [cleave] but consumes an additional item from the stack.
+
+       1 2 3 4 [+] [-] clop
+    --------------------------
+             1 2 7 -1
 
 ### Crosslinks
 
-Lorem ipsum.
+[cleave]
+[fork]
+[map]
+

docs/reference/cmp.md

@@ -2,41 +2,37 @@
 
 ## cmp
 
-Basis Function Combinator
+Combinator
 
-cmp takes two values and three quoted programs on the stack and runs one
+Take two values and three quoted programs on the stack and run one
-of the three depending on the results of comparing the two values: :
+of the three depending on the results of comparing the two values.
 
-    a b [G] [E] [L] cmp
+       a b [G] [E] [L] cmp
     ------------------------- a > b
-     G
+            G
 
-    a b [G] [E] [L] cmp
+       a b [G] [E] [L] cmp
     ------------------------- a = b
-         E
+                E
 
-    a b [G] [E] [L] cmp
+       a b [G] [E] [L] cmp
     ------------------------- a < b
-         L
+                    L
-
-Gentzen diagram.
-
-### Definition
-
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
 ### Discussion
 
-Lorem ipsum.
+This is useful sometimes, and you can [dup] or [dupd] with two quoted
+programs to handle the cases when you just want to deal with [<=] or [>=]
+and not all three possibilities, e.g.:
+
+    [G] [LE] dup cmp
+
+    [GE] [L] dupd cmp
+
+Or even:
+
+    [GL] [E] over cmp
 
 ### Crosslinks
 
-Lorem ipsum.
+TODO: link to tree notebooks where this was used.
+

docs/reference/codi.md

@@ -2,28 +2,26 @@
 
 ## codi
 
-Basis Function Combinator
+Combinator
 
-cons dip
+Take a quoted program from the stack, [cons] the next item onto it, then
-
+[dip] the whole thing under what was the third item on the stack.
-Gentzen diagram.
+ 
+       a b [F] . codi
+    --------------------
+             b . F a
 
 ### Definition
 
-if not basis.
+> [cons] [dip]
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
 
 ### Discussion
 
-Lorem ipsum.
+This is one of those weirdly specific functions that turns out to be
+useful in a few places.
 
 ### Crosslinks
 
-Lorem ipsum.
+[appN]
+[codireco]
+

docs/reference/mkref/Functor-Reference.md

@@ -671,267 +671,225 @@ terms of [choice] as above).  The more common "if..then..else" construct
 
 ## ccccons
 
-Basis Function Combinator
+Function
 
-ccons ccons
+       a b c d [...] ccccons
+    ---------------------------
+           [a b c d ...]
 
-Gentzen diagram.
+Do [cons] four times.
 
 ### Definition
 
-if not basis.
+> [ccons] [ccons]
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
 
 ### Crosslinks
 
-Lorem ipsum.
+[ccons] [cons] [times]
+
 
 --------------------
 
 ## ccons
 
-(Function)
+Function
 
-Given two items and a list, append the items to the list to make a new list.
+       a b [...] ccons
-
-       B A [...] ccons
     ---------------------
-          [B A ...]
+          [a b ...]
+
+Do [cons] two times.
 
 ### Definition
 
-    cons cons
+> [cons] [cons]
-
-### Discussion
-
-Does `cons` twice.
 
 ### Crosslinks
 
-[cons](#cons)
+[cons]
+[ccons]
 
 
 ------------------------------------------------------------------------
 
 ## choice
 
-Basis Function Combinator
+Basis Function
 
-Use a Boolean value to select one of two items. :
+Use a Boolean value to select one of two items.
 
-    A B false choice
+       a b false choice
     ----------------------
-    A
+              a
 
-
+       a b true choice
-    A B true choice
     ---------------------
-      B
+              b
-
-Currently Python semantics are used to evaluate the \"truthiness\" of
-the Boolean value (so empty string, zero, etc. are counted as false,
-etc.)
-
-Gentzen diagram.
 
 ### Definition
 
-if not basis.
+> \[[pop]\] \[[popd]\] [branch]
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
 
 ### Discussion
 
-Lorem ipsum.
+It's a matter of taste whether you implement this in terms of [branch] or
+the other way around.
 
 ### Crosslinks
 
-Lorem ipsum.
+[branch]
+[select]
+
 
 ------------------------------------------------------------------------
 
 ## clear
 
-Basis Function Combinator
+Basis Function
 
 Clear everything from the stack.
 
-:   clear == stack [pop stack] loop
-
-           ... clear
-        ---------------
-
-Gentzen diagram.
-
 ### Definition
 
-if not basis.
+> [stack] [bool] \[[pop] [stack] [bool]\] [loop]
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
-### Discussion
-
-Lorem ipsum.
 
 ### Crosslinks
 
-Lorem ipsum.
+[stack]
+[swaack]
+
 
 ------------------------------------------------------------------------
 
 ## cleave
 
-Basis Function Combinator
+Combinator
 
-fork popdd
+Run two programs in parallel, consuming one additional item, and put their
+results on the stack.
 
-Gentzen diagram.
+       ... x [A] [B] cleave
-
+    ------------------------
-### Definition
+            ... a b
-
-if not basis.
 
 ### Derivation
 
-if not basis.
+> [fork] [popdd]
 
-### Source
+### Example
 
-if basis
+       1 2 3 [+] [-] cleave
+    --------------------------
+             1 2 5 -1
 
 ### Discussion
 
-Lorem ipsum.
+One of a handful of useful parallel combinators.
 
 ### Crosslinks
 
-Lorem ipsum.
+[clop]
+[fork]
+[map]
+
 
 ------------------------------------------------------------------------
 
 ## clop
 
-Basis Function Combinator
+Combinator
 
-cleave popdd
+Run two programs in parallel, consuming two additional items, and put their results on the stack.
 
-Gentzen diagram.
+       ... x y [A] [B] clop
+    --------------------------
+            ... a b
 
 ### Definition
 
-if not basis.
+> [cleave] [popdd]
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
 
 ### Discussion
 
-Lorem ipsum.
+Like [cleave] but consumes an additional item from the stack.
+
+       1 2 3 4 [+] [-] clop
+    --------------------------
+             1 2 7 -1
 
 ### Crosslinks
 
-Lorem ipsum.
+[cleave]
+[fork]
+[map]
+
 
 ------------------------------------------------------------------------
 
 ## cmp
 
-Basis Function Combinator
+Combinator
 
-cmp takes two values and three quoted programs on the stack and runs one
+Take two values and three quoted programs on the stack and run one
-of the three depending on the results of comparing the two values: :
+of the three depending on the results of comparing the two values.
 
-    a b [G] [E] [L] cmp
+       a b [G] [E] [L] cmp
     ------------------------- a > b
-     G
+            G
 
-    a b [G] [E] [L] cmp
+       a b [G] [E] [L] cmp
     ------------------------- a = b
-         E
+                E
 
-    a b [G] [E] [L] cmp
+       a b [G] [E] [L] cmp
     ------------------------- a < b
-         L
+                    L
-
-Gentzen diagram.
-
-### Definition
-
-if not basis.
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
-
 ### Discussion
 
-Lorem ipsum.
+This is useful sometimes, and you can [dup] or [dupd] with two quoted
+programs to handle the cases when you just want to deal with [<=] or [>=]
+and not all three possibilities, e.g.:
+
+    [G] [LE] dup cmp
+
+    [GE] [L] dupd cmp
+
+Or even:
+
+    [GL] [E] over cmp
 
 ### Crosslinks
 
-Lorem ipsum.
+TODO: link to tree notebooks where this was used.
+
 
 ------------------------------------------------------------------------
 
 ## codi
 
-Basis Function Combinator
+Combinator
 
-cons dip
+Take a quoted program from the stack, [cons] the next item onto it, then
-
+[dip] the whole thing under what was the third item on the stack.
-Gentzen diagram.
+ 
+       a b [F] . codi
+    --------------------
+             b . F a
 
 ### Definition
 
-if not basis.
+> [cons] [dip]
-
-### Derivation
-
-if not basis.
-
-### Source
-
-if basis
 
 ### Discussion
 
-Lorem ipsum.
+This is one of those weirdly specific functions that turns out to be
+useful in a few places.
 
 ### Crosslinks
 
-Lorem ipsum.
+[appN]
+[codireco]
+
 
 ------------------------------------------------------------------------
 

implementations/Python/joy/library.py

@@ -340,10 +340,9 @@ def choice(stack):
         ---------------------
              B
 
-    Currently Python semantics are used to evaluate the "truthiness" of the
-    Boolean value (so empty string, zero, etc. are counted as false, etc.)
     '''
     (if_, (then, (else_, stack))) = stack
+    assert isinstance(if_, bool), repr(if_)
     return then if if_ else else_, stack