--- a/README.md	Tue Sep 03 14:06:42 2019 +0200
+++ b/README.md	Tue Sep 03 15:34:46 2019 +0200
@@ -1,3 +1,5 @@
 # ylisp
 
 lbo's runtime/VM/programming language playground.
+
+"ylisp" => *oh y did you build this "lisp"!?*

--- a/doc/execution.md	Tue Sep 03 14:06:42 2019 +0200
+++ b/doc/execution.md	Tue Sep 03 15:34:46 2019 +0200
@@ -1,4 +1,4 @@
-@page Execution
+@page Execution Execution
 
 ## Execution model.
 
@@ -71,18 +71,17 @@
 reference could be found (at which point the symbolic reference is translated
 into a numeric reference).
 
-A new scope is started by the start of a program, or one of a `defn`, `for`,
-`let` s-expr.
+A new scope is started for every list.
 
 * Scan program tree
     * Encounter symbolic reference (an ID)? -> Look up in stack of scope-lists by
     walking each list in the stack until one is found. If none is found, this is
     an error.
-    * Encounter one of `defn`, `for`, `let`: Push a new scope list onto the
-    stack. If `defn`, `let`: Push definition of the following function/value
-    into the list of the parent scope.
+    * Encounter new list: Push new scope onto stack.
     * Leave scope: Pop scope list from stack.
 
+(see `preprocess.c`)
+
 TODO: Garbage collection, slot recycling (free-slot-list), reference counting?
 
 ### Built-in functions and constructs
@@ -111,6 +110,19 @@
 referencing the function argument relative to the top of the stack (0 is the
 top-most stack value, 1 the one below, etc.).
 
+`yeval()` detects when an expression should be a function call. It is evaluated
+as such if the first element of a list is a reference to a function or a
+reference to a value containing a reference to a function:
+
+```
+(defn f (a) (+ a a))
+(let g f)
+(g 3)
+-- 6
+(f 3)
+-- 6
+```
+
 For function calls, `yeval_call_func()` evaluates each argument and pushes it
 onto the call stack (which is part of the `yeval_state_t` struct given to
 evaluation functions). When the function body is evaluated from there, the
@@ -142,3 +154,6 @@
 expression (and thus don't need to be returned to the caller).
 * `yeval()` is called with `in_place` already set.
 
+## REPL
+
+You can use the REPL binary `src/repl` to test out ylisp for yourself.

--- a/doc/syntax.md	Tue Sep 03 14:06:42 2019 +0200
+++ b/doc/syntax.md	Tue Sep 03 15:34:46 2019 +0200
@@ -1,7 +1,9 @@
-@page Syntax
+@page Syntax Syntax
 
 ## Syntax
 
+Comments start with `--` and end at the end of a line.
+
 ### Definitions
 
 The following IDs are represented as `YBUILTIN_TYPE` in `yexpr_t` values. Each
@@ -29,6 +31,8 @@
 The name is visible in the same and all lower scopes, where a scope is an
 s-expr. The value of the last `expr` will be assigned to the variable.
 
+Functions are also normal values that can be assigned.
+
 ### Control structures
 
 #### `for`
@@ -40,27 +44,30 @@
 Run the given expressions once for every `list-item`. `var` is bound in the
 expressions to the respective item.
 
+The result of a for expression is a list of the value of the last expression in
+each iteration.
+
+```
+(defn fac (n) (if (== n 0) 1 ((* n (fac (- n 1))))))
+
+(print (for i (1 2 3 4 5 6 7 8 9 10) (fac i)))
+-- prints (1 2 6 24 120 720 5040 40320 362880 3628800 )
+```
+
 #### `if`
 
 ```
 (if cond (then-exprs) [(else-exprs)])
 ```
 
-Where `cond` evaluates to a boolean value (numeric 1 or 0) and `then`, `else`
-are expressions. If multiple expressions should be executed, `seq` can be used
-to chain them.
+Where `cond` evaluates to a boolean value (`'true`/`'false` or `1`/`0`).
+`then-exprs` can be a single item (`(if (== 55 55) 1 2)`) or a list of
+expressions, of which the last will be returned (and all will be evaluated):
+(`(if (== 55 55) ((print 'hello 'world) (+ 22 3)))`)
 
 `cond` should evaluate to either `'true`/`'false` or an integer (0 is false,
 everything else is true).
 
-#### `seq`
-
-```
-(seq expr expr ...)
-```
-
-Execute `expr`s and return the result of the last `expr`.
-
 ### Arithmetic operations
 
 ```
@@ -78,7 +85,7 @@
 
 ```
 (print a ...)
-(println a ...)
+-- not yet implemented: (println a ...)
 ```
 
-Print the arguments formatted to stdout, separated by no spaces.
+Print the arguments formatted to stdout, separated by spaces.