i and ii

docs/reference/i.md

@@ -2,21 +2,17 @@
 
 ## i
 
-(Basis Combinator)
+Basis Combinator
 
 Append a quoted expression onto the pending expression.
 
 
-       [Q] i
-    -----------
-        Q
-
-### Source
-
-    combo(i, [list(P)|S], S, Ei, Eo) :- append(P, Ei, Eo).
+       [Q] . i
+    -------------
+           . Q
 
 ### Discussion
 
-This is probably the fundamental combinator.  You wind up using it in all
-kinds of places (for example, the `x` combinator can be defined as `dup i`.)
+This is a fundamental combinator.  It is used in all kinds of places.  For
+example, the [x] combinator can be defined as `dup i`.
 

docs/reference/ii.md

@@ -2,30 +2,46 @@
 
 ## ii
 
-Basis Function Combinator
+Combinator
+
+Take a quoted program from the stack and run it twice, first under the
+top item, then again with the top item.
 
     ... a [Q] ii
     ------------------
      ... Q a Q
 
-Gentzen diagram.
-
 ### Definition
 
-if not basis.
+> \[[dip]\] [dupdip] [i]
 
-### Derivation
+### Example
 
-if not basis.
+It's a little tricky to understand how this works so here's an example trace:
 
-### Source
-
-if basis
+          1 2 3 4 [++] • [dip] dupdip i
+    1 2 3 4 [++] [dip] • dupdip i
+          1 2 3 4 [++] • dip [++] i
+                 1 2 3 • ++ 4 [++] i
+                 1 2 4 • 4 [++] i
+               1 2 4 4 • [++] i
+          1 2 4 4 [++] • i
+               1 2 4 4 • ++
+               1 2 4 5 •
 
 ### Discussion
 
-Lorem ipsum.
+In some cases (like the example above) this is the same effect as using [app2] but most of the time it's not:
+
+       1 2 3 4 [+] ii
+    --------------------
+            1 9
+
+       1 2 3 4 [+] app2
+    ----------------------
+           1 2 5 6
 
 ### Crosslinks
 
-Lorem ipsum.
+[app2]
+[b]

docs/reference/mkref/Functor-Reference.md

@@ -1862,23 +1862,19 @@ This is another function that has to wait on the numeric tower.
 
 ## i
 
-(Basis Combinator)
+Basis Combinator
 
 Append a quoted expression onto the pending expression.
 
 
-       [Q] i
-    -----------
-        Q
-
-### Source
-
-    combo(i, [list(P)|S], S, Ei, Eo) :- append(P, Ei, Eo).
+       [Q] . i
+    -------------
+           . Q
 
 ### Discussion
 
-This is probably the fundamental combinator.  You wind up using it in all
-kinds of places (for example, the `x` combinator can be defined as `dup i`.)
+This is a fundamental combinator.  It is used in all kinds of places.  For
+example, the [x] combinator can be defined as `dup i`.
 
 
 ------------------------------------------------------------------------
@@ -1959,33 +1955,49 @@ Lorem ipsum.
 
 ## ii
 
-Basis Function Combinator
+Combinator
+
+Take a quoted program from the stack and run it twice, first under the
+top item, then again with the top item.
 
     ... a [Q] ii
     ------------------
      ... Q a Q
 
-Gentzen diagram.
-
 ### Definition
 
-if not basis.
+> \[[dip]\] [dupdip] [i]
 
-### Derivation
+### Example
 
-if not basis.
+It's a little tricky to understand how this works so here's an example trace:
 
-### Source
-
-if basis
+          1 2 3 4 [++] • [dip] dupdip i
+    1 2 3 4 [++] [dip] • dupdip i
+          1 2 3 4 [++] • dip [++] i
+                 1 2 3 • ++ 4 [++] i
+                 1 2 4 • 4 [++] i
+               1 2 4 4 • [++] i
+          1 2 4 4 [++] • i
+               1 2 4 4 • ++
+               1 2 4 5 •
 
 ### Discussion
 
-Lorem ipsum.
+In some cases (like the example above) this is the same effect as using [app2] but most of the time it's not:
+
+       1 2 3 4 [+] ii
+    --------------------
+            1 9
+
+       1 2 3 4 [+] app2
+    ----------------------
+           1 2 5 6
 
 ### Crosslinks
 
-Lorem ipsum.
+[app2]
+[b]
 
 --------------------