add reference/dynamic-symbols

3 files changed, 32 insertions, 2 deletions

diff --git a/docs/guide/07_defining-symbols.md b/docs/guide/07_defining-symbols.md
index 5fb6d3f..c25d34e 100644
--- a/docs/guide/07_defining-symbols.md
+++ b/docs/guide/07_defining-symbols.md
@@ -29,7 +29,7 @@ symbols starting and ending with asterisks (`*clock*`):
   example, `math/+` is found by first looking for a value for the symbol `math`,
   and then looking for the symbol `+` in that value. If the value for the
   symbol `math` is not a scope, an error is thrown.
-- Symbols starting and ending with asterisks are called `dynamic symbols` and
+- Symbols starting and ending with asterisks are called *dynamic symbols* and
   are looked up in a different way inside user-defined functions. This will be
   covered in detail later.
 - The two special formats can be mixed: when evaluating `*hello*/world`,
diff --git a/docs/reference/03-4_dynamic-symbols.md b/docs/reference/03-4_dynamic-symbols.md
new file mode 100644
index 0000000..d642984
--- /dev/null
+++ b/docs/reference/03-4_dynamic-symbols.md
@@ -0,0 +1,30 @@
+Symbol definitions in `alv` normally follow 'lexical scoping' rules. That means
+that symbols are looked up by following the scopes outwards according to the
+syntactical nesting of expressions in the source code.
+
+In the following snippet, for example, the symbol `hello` is resolved inside
+`print-hello` by checking first the innermost scope (the function body), and
+then the surrounding scope (the whole file), where the value `"original
+message"` is found:
+
+    (def hello "original message")
+    (defn print-hello () (print hello))
+    
+    (do
+      (def hello "overwritten message")
+      (print-hello))   #(-> prints "original message")
+
+On the other hand, there are also *dynamic symbols*. Dynamic symbols are
+symbols whose name starts and ends with an asterisk, like `*clock*` and
+`*sym*`. Where functions are called, dynamic symbols are not looked up in the
+scope that contains the *function definition*, but rather the scope containing
+the *function call site*:
+      
+    (def *hello* "original message")
+    (defn print-hello () (print *hello*))
+    
+    (do
+      (def *hello* "overwritten message")
+      (print-hello))   #(-> prints "overwritten message")
+
+This allows symbols to be *dynamically overwritten*.
diff --git a/docs/reference/index.md b/docs/reference/index.md
index f0335c3..bf8e5f3 100644
--- a/docs/reference/index.md
+++ b/docs/reference/index.md
@@ -16,7 +16,7 @@ own module or contributing to alive, check out the
    1. [symbol resolution](03-1_symbol-resolution.html)
    2. [conditionals](03-2_conditionals.html)
    3. [functions](03-3_functions.html)
-   4. dynamic symbols
+   4. [dynamic symbols](03-4_dynamic-symbols.html)
    5. [loops](03-5_loops.html)
    6. modules and loading
 4. runtime