From 2d779f8182aa1a8c53647583fc82347c689d2f8e Mon Sep 17 00:00:00 2001
From: Brian Picciano <mediocregopher@gmail.com>
Date: Wed, 15 Jul 2015 20:32:53 -0600
Subject: [PATCH] read through everything again, made some small fixes to docs

---
 README.md         | 18 ++++++++++++++----
 docs/functions.md |  4 ++--
 docs/packages.md  |  4 ++--
 docs/syntax.md    | 35 ++++++++++++++++-------------------
 4 files changed, 34 insertions(+), 27 deletions(-)

diff --git a/README.md b/README.md
index 68d1eec..42107e9 100644
--- a/README.md
+++ b/README.md
@@ -15,17 +15,27 @@ work-in-progress, and this repo is where I'm jotting down my notes:
   easily discoverable and always importable so helper functions can be made
   available.
 
-* When choosing between adding a syntax rule or a datatype and not adding a
-  feature, err on not adding the feature.
+* When choosing between adding a syntax rule/datatype and not adding a feature,
+  err on not adding the feature.
 
 * It is not a goal to make ginger code be usable from go code.
 
 * Naming should use words instead of symbols, except when those symbols are
   existing go operators.
 
-* Overloading function should be used as little as possible.
+* Overloading functions should be used as little as possible. Possibly not at
+  all
 
 # Documentation
 
-See the [docs][/docs] folder for more details. Keep in mind that most of ginger
+See the [docs](/docs) folder for more details. Keep in mind that most of ginger
 is still experimental and definitely not ready for the spotlight.
+
+Here is a list of the docs more or less in the order they should be read for a
+complete overview of the language:
+
+* [syntax](/docs/syntax.md)
+* [functions](/docs/functions.md)
+* [compilation](/docs/compilation.md)
+* [packages](/docs/packages.md)
+* [go-interop](/docs/go-interop.md)
diff --git a/docs/functions.md b/docs/functions.md
index 574222b..bfdd9b8 100644
--- a/docs/functions.md
+++ b/docs/functions.md
@@ -36,7 +36,7 @@ example:
 ```
 
 This function will return the argument `x` if it is greater than or equal to 0,
-or `(* -1 x)` if it's not.
+or `(: * -1 x)` if it's not.
 
 ### Multiple returns
 
@@ -50,7 +50,7 @@ temporary variables in a scope, can deconstruct these multiple-returns:
     [4 6])
 
 (. let [[foo bar] (: sum-10)
-    (: fmt.Println "%d + %d = 10" foo bar))
+    (: fmt.Printf "%d + %d = 10\n" foo bar))
 ```
 
 Functions defined within a go library which return multiple values can also be
diff --git a/docs/packages.md b/docs/packages.md
index 245462f..8f2bdb8 100644
--- a/docs/packages.md
+++ b/docs/packages.md
@@ -37,9 +37,9 @@ variable/function defined in one part can be used in another part.
 
 A public variable/function can be used within a package without any extra
 embelishment (in the above example, `(: AwesomeFunction)` could simply be called
-from within the package.
+from within the package).
 
-Outside of a package can be used as follows:
+Outside of a package variables/functions can be used as follows:
 
 ```
 (. package "show-and-tell"
diff --git a/docs/syntax.md b/docs/syntax.md
index 5cf4783..423da2f 100644
--- a/docs/syntax.md
+++ b/docs/syntax.md
@@ -7,8 +7,8 @@ evaluated.
 
 I have some immediate goals I'm trying to achieve with this syntax:
 
-* Everything is strings (except numbers, functions, and data structures). There
-  is no symbol type, atom type, keyword type, etc... they're all just strings.
+* Everything is strings (except numbers, functions, and composites). There is no
+  symbol type, atom type, keyword type, etc... they're all just strings.
 
 * There is no `defmacro`. Macro creation and usage is simply an inherent feature
   of the language syntax.
@@ -115,29 +115,26 @@ value. This evaluates to a map with 2 key/val pairs:
 
 `.` is the half-evaluator. It only works on lists, and runs the function given
 in the first argument with the unevaluated arguments (even if they have `:`).
-You can generate new code to run on the fly (macros) using the normal `fn`. This
-evaluates to a `let`-like function, except it forces you to use the capitalized
-variable names in the body (utterly useless):
+You can generate new code to run (compile-time macros) using the normal `fn`.
+The returned value is evaluated in place of the original. This evaluates to a
+`let`-like function, except it forces you to use the capitalized variable names
+in the body (utterly useless):
 
 ```
 #
-# eval evaluates a given value (either a string or list). It has been
-# implicitely called on all examples so far.
+# map-alternate is a made up function which maps over every other element in a
+# list, starting with the first.
+# E.g. (: map-alternate (. fn [x] (: + x 1)) (1 2 3 4 5)) -> (2 2 4 4 6)
 #
-# elem-map maps over every element in a list, embedded or otherwise
-#
-# capitalize looks for the first letter in a string and capitalizes it
+# capitalize is a made up function which looks for the first letter in a string
+# and capitalizes it
 #
 (. defn caplet [mapping body...]
-    (. eval
-        (. let
-            (: elem-map
-                (. fn [x]
-                    (. if (: mapping (: slice x 1))
-                        (: capitalize x)
-                        x))
-                mapping)
-            body...)))
+    ("." let
+        (: map-alternate
+            (. fn [x] (: capitalize x))
+            mapping)
+        body...))
 
 #Usage
 (. caplet [foo "this is foo"