From a4e28b79d28e2e346fa70e040443044ce21b50c9 Mon Sep 17 00:00:00 2001
From: crc <crc@noemail.net>
Date: Thu, 10 May 2018 15:39:28 +0000
Subject: [PATCH] merge in some minor updates to the examples

FossilOrigin-Name: bde547c22b155870b9a00e14bc73feb6c165df9c78ab1b51e31f42a8bd1304d9
---
 example/1D-Cellular-Automota.forth |  8 +-----
 example/99Bottles.forth            |  2 +-
 example/accumulator.forth          | 41 ++++++++++++++++++++++--------
 3 files changed, 32 insertions(+), 19 deletions(-)

diff --git a/example/1D-Cellular-Automota.forth b/example/1D-Cellular-Automota.forth
index b7fbdd9..6bce6a0 100644
--- a/example/1D-Cellular-Automota.forth
+++ b/example/1D-Cellular-Automota.forth
@@ -1,4 +1,4 @@
-# example|RosettaCode|1D-Cellular-Automota
+# 1D Cellular Automota
 
 Assume an array of cells with an initial distribution of live and dead cells, and imaginary cells off the end of the array having fixed values.
 
@@ -15,12 +15,6 @@ If, in the following table, a live cell is represented by 1 and a dead cell by 0
 110 -> 1  # Needs one neighbour to survive
 111 -> 0  # Starved to death.
 
-Declare module constant (prevents reloading when using `import`):
-
-~~~
-:example|RosettaCode|1D-Cellular-Automota ;
-~~~
-
 I had originally written an implementation of this in RETRO 11. For RETRO 12 I took advantage of new language features and some further considerations into the rules for this task.
 
 The first word, `string,` inlines a string to `here`. I'll use this to setup the initial input.
diff --git a/example/99Bottles.forth b/example/99Bottles.forth
index cf51840..baa7552 100644
--- a/example/99Bottles.forth
+++ b/example/99Bottles.forth
@@ -1,4 +1,4 @@
-# example|99Bottles
+# 99 Bottles
 
 Display the text for the *99 Bottles of Beer* song.
 
diff --git a/example/accumulator.forth b/example/accumulator.forth
index 8c00c82..0c85e28 100644
--- a/example/accumulator.forth
+++ b/example/accumulator.forth
@@ -1,23 +1,42 @@
-Traditional Forth has a CREATE/DOES> construct. RETRO allows for
-something similar using the `does` combinator.
+# Accumulator
 
-An example in traditional Forth:
+## Description
+
+This implements a function that takes an initial value and constructs a new function that returns the value before incrementing the stored value by 1.
+
+So, given an initial value of 1, the first time the function is called, 1 is returned. The second, 2, and so on.
+
+In traditional Forth, this would be done using a CREATE/DOES> construct. RETRO allows for something similar using the `does` combinator.
+
+An example in a traditional Forth:
 
     : acc ( n "name" -- )
       create , does> dup >r @ dup 1+ r> ! ;
 
-And in RETRO, using `does` and the `bi` combinator:
+In RETRO, we could begin by rewriting this using the RETRO words:
+
+    :acc (ns-)
+      d:create , [ dup push fetch n:inc pop store ] does ;
+
+The `dup push ... pop` pattern is the `sip` combinator, so we can simplify it:
+
+    :acc (ns-)
+      d:create , [ [ fetch n:inc ] sip store ] does ;
+
+This is better, but not quite done. RETRO has a `v:inc` for incrementing variables, which would eliminate the n:inc and store. And a `bi` combinator to run two quotes against a value. So we could simplify yet again, resulting in:
 
 ~~~
 :acc (ns-)
   d:create , [ [ fetch ] [ v:inc ] bi ] does ;
 ~~~
 
-Here's a little test case:
+This removes the primitive stack shuffling, and leaves something that expresses the intent more clearly.
 
-~~~
-#10 'foo acc
-foo
-foo
-foo
-~~~
+Finally, here's a little test case:
+
+```
+    #10 'foo acc
+    foo
+    foo
+    foo
+```