From aeb5497f613ad2311ff396b6b1d1b7f7e310d57b Mon Sep 17 00:00:00 2001
From: Brian Picciano <mediocregopher@gmail.com>
Date: Thu, 2 Oct 2014 11:24:52 -0400
Subject: [PATCH] suggestions from @marcopolo

---
 README.md | 90 ++++++++++++++++++++++++++++++-------------------------
 1 file changed, 50 insertions(+), 40 deletions(-)

diff --git a/README.md b/README.md
index 130aeda..c84f781 100644
--- a/README.md
+++ b/README.md
@@ -21,13 +21,7 @@ This is a number which evalutates to 5:
 5
 ```
 
-This is a string, as it contains no whitespace:
-
-```
-ImJustAString
-```
-
-This is also a string, it can contain anything:
+This is a string, it can contain anything:
 
 ```
 "! I'm the king of the world !"
@@ -36,70 +30,86 @@ This is also a string, it can contain anything:
 This is a list. It evaluates to a linked-list of four strings:
 
 ```
-(a b c d)
+("a" "b" "c" "d")
 ```
 
 This is a vector of those same elements. It's like a list, but has some slightly
 different properties. We'll mostly be using lists:
 
 ```
-[a b c d]
+["a" "b" "c" "d"]
 ```
 
 This is a string
 
 ```
-+
+"+"
 ```
 
-`:` is the evaluator. This evaluates to a function which adds its arguments:
+`:` is the evaluator. A string beginning with `:` is evaluated to whatever it
+references. This evaluates to a function which adds its arguments:
 
 ```
-:+
+":+"
 ```
 
 This evaluates to list whose elements are a function and two numbers:
 
 ```
-(:+ 1 2)
+(":+" 1 2)
 ```
 
-This evaluates to the number 5:
+A list prefixed with a `:` calls the first element as a function with the rest
+of the elements as arguments. This evaluates to the number 5:
 
 ```
-:(:+ 1 2)
+:(":+" 1 2)
+```
+
+A bare string (lacking in `"`) is a shortcut for that string prefixed by a `:`.
+This is equivalent to the above:
+
+```
+:(+ 1 2)
 ```
 
 The `fn` function can be used to define a new function. This evaluates to an
 anonymous function which adds one to its argument and returns it:
 
 ```
-:(:fn [x]
-    :(:+ :x 1))
+:(fn [x]
+    :(+ x 1))
 ```
 
-The `def` function can be used to bind some value to a new variable:
+The `def` function can be used to bind some value to a new variable. Note the
+`.` instead of `:`. We'll cover that in a bit. This defines a variable `foo`
+which evaluates to the string `"bar"`:
 
 ```
-:(:def foo bar)
-# Now :foo will evaluate to the string bar
+.(def foo "bar")
+```
 
-:(:def incr
-    :(:fn [x]
-        :(:+ :x 1)))
-# Now :incr will evaulate to a function which adds 1 to its argument
+This defines a variable `incr` which evaluates to a function which adds one to
+its argument:
 
-#defn is a shortcut for the above
-:(:defn incr [x]
-    :(:+ :x 1))
+```
+.(def incr
+    :(fn [x]
+        :(+ x 1)))
+```
+
+This uses `defn` as a shortcut for the above:
+```
+.(defn incr [x]
+    :(+ x 1))
 ```
 
 There are also maps. A map's keys can be any value(?). A map's values can be any
 value. This evaluates to a map with 2 key/val pairs:
 
 ```
-{ foo :foo
-  bar :(:incr 4) }
+{ "foo" foo
+  "bar" :(incr 4) }
 ```
 
 `.` is the half-evaluator. It only works on lists, and runs the function given
@@ -109,18 +119,18 @@ front). You can generate new code to run on the fly (macros) using the normal
 capitalized variable names in the body (utterly useless):
 
 ```
-:(:defn caplet [mapping body...]
+.(defn caplet [mapping body...]
     # elem-map maps over every element in a list, embedded or otherwise
-    ::(:elem-map
-        :(:fn [x]
-            :(:if (mapping :(:slice :x 1))
-                (capitalize :x)
-                :x))
-        :body))
+    ::(elem-map
+        :(fn [x]
+            :(if (mapping :(slice x 1))
+                (capitalize x)
+                x))
+        body))
 
 #Usage
-.(:caplet [foo "this is foo"
-           dog "this is dog"]
-    :(:println :Foo)
-    :(:println :Dog))
+.(caplet [foo "this is foo"
+          dog "this is dog"]
+    :(println Foo)
+    :(println Dog))
 ```