--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/execution.md	Fri Aug 23 15:35:01 2019 +0200
@@ -0,0 +1,41 @@
+# ylisp
+
+## Execution model.
+
+The main execution model is stack-based interpretation of the parsed tree.
+
+Names are scoped and visible in the scope they are defined in, after being
+defined, and in child scopes.
+
+## Scoping.
+
+Every function call pushes an ID to the scope stack. The scope stack is used
+to identify variables/IDs in a scope. Variable and function definitions then
+always use the scope ID to resolve IDs.
+
+**Example**:
+
+```
+-- This is the top level program.
+
+-- SCOPE 0
+(defn f1
+ -- SCOPE 1
+ (a b)
+ (+ (* a a) b))
+
+(defn f2
+ -- SCOPE 2
+ (a b)
+ (defn inner-fn
+  -- SCOPE 3
+  (x)
+  (* x x))
+ -- scope 2 again
+ (+ (inner-fn a) (inner-fn b)))
+
+-- scope 0 again
+(let x 33)
+
+(print "The result is" (f1 5 x))
+```

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/syntax.md	Fri Aug 23 15:35:01 2019 +0200
@@ -0,0 +1,54 @@
+# ylisp
+
+## Syntax
+
+### Definitions
+
+#### `defn`: Define function
+
+```
+(defn name (arg arg ...) (body body) (body) ...)
+```
+
+Result of the function is the last expression. The name is visible in the same
+and all lower scopes, where a scope is an s-expr.
+
+#### `let`: Assign variable
+
+```
+(let var val)
+```
+
+The name is visible in the same and all lower scopes, where a scope is an
+s-expr.
+
+### Control structures
+
+```
+(for var (list-item list-item list-item) (expr ...) (expr ...) ...)
+```
+
+Run the given expressions once for every `list-item`. `var` is bound in the
+expressions to the respective item.
+
+### Arithmetic operations
+
+```
+(+ a b)
+(* a b)
+(- a b)
+(/ a b)
+```
+
+where `a` and `b` are numeric expressions.
+
+### I/O
+
+#### Output
+
+```
+(print a ...)
+(println a ...)
+```
+
+Print the arguments formatted to stdout, separated by no spaces.