read through everything again, made some small fixes to docs

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)

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

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"

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))
+    ("." let
+        (: map-alternate
+            (. fn [x] (: capitalize x))
             mapping)
-            body...)))
+        body...))
 
 #Usage
 (. caplet [foo "this is foo"