split guide into guide and reference

12 files changed, 13 insertions, 192 deletions

diff --git a/docs/guide/installation.md b/docs/guide/01_installation.md
index 5a192fa..5a192fa 100644
--- a/docs/guide/installation.md
+++ b/docs/guide/01_installation.md
diff --git a/docs/guide/hello-world.md b/docs/guide/02_hello-world.md
index 7f1517d..7f1517d 100644
--- a/docs/guide/hello-world.md
+++ b/docs/guide/02_hello-world.md
diff --git a/docs/guide/working-with-the-copilot.md b/docs/guide/03_working-with-the-copilot.md
index f40d82d..f40d82d 100644
--- a/docs/guide/working-with-the-copilot.md
+++ b/docs/guide/03_working-with-the-copilot.md
diff --git a/docs/guide/syntax.md b/docs/guide/04_syntax.md
index 93f1c61..93f1c61 100644
--- a/docs/guide/syntax.md
+++ b/docs/guide/04_syntax.md
diff --git a/docs/guide/basic-types.md b/docs/guide/05_basic-types.md
index c22929c..c22929c 100644
--- a/docs/guide/basic-types.md
+++ b/docs/guide/05_basic-types.md
diff --git a/docs/guide/importing-operators.md b/docs/guide/06_importing-operators.md
index 4321e7a..4321e7a 100644
--- a/docs/guide/importing-operators.md
+++ b/docs/guide/06_importing-operators.md
diff --git a/docs/guide/defining-symbols.md b/docs/guide/07_defining-symbols.md
index 5fb6d3f..5fb6d3f 100644
--- a/docs/guide/defining-symbols.md
+++ b/docs/guide/07_defining-symbols.md
diff --git a/docs/guide/making-sound.md b/docs/guide/08_making-sound.md
index 1987dac..1987dac 100644
--- a/docs/guide/making-sound.md
+++ b/docs/guide/08_making-sound.md
diff --git a/docs/guide/evaltime-and-runtime.md b/docs/guide/evaltime-and-runtime.md
deleted file mode 100644
index e718cf3..0000000
--- a/docs/guide/evaltime-and-runtime.md
+++ /dev/null
@@ -1,45 +0,0 @@
-So far, `alv` may seem a lot like any other programming language - you write
-some code, save the file, and it runs, printing some output. "What about the
-'continuously running' aspect from the introduction?", you may ask yourself. 
-
-So far, we have only seen *evaltime* execution in alv - but there is also
-*runtime* behavior. At *evaltime*, that is whenever there is change to the
-source code, `alv` behaves similar to a Lisp. This is the part we have seen
-so far. But once one such *eval cycle* has executed, *runtime* starts, and
-`alv` behaves like a dataflow system like [PureData][pd], [Max/MSP][max] or
-[vvvv][vvvv].
-
-What looked so far like static constants are actually *streams* of values.
-Whenever an input to an operator changes, the operator (may) update and respond
-with a change to its output as well. To see this in action, we need to start
-with a changing value. Number literals like `1` and `2`, which we used so far,
-are *evaltime constant*, which means simply that they will never update. Since
-all inputs to our [math/+][] operator are *evaltime constant*, the result is
-constant as well. To get some *runtime* activity, we have to introduce a
-side-effect input from somewhere outside the system.
-
-The [time/][] module contains a number of operators whose outputs update
-over time. Lets take a look at [time/tick][]:
-
-    (import* time)
-    (trace (tick 1))
-
-This will print a series of numbers, incrementing by 1 every second. The
-parameter to [time/tick][] controls how quickly it counts - try changing it to
-`0.5` or `2`. As you can see, we can change [time/tick][] *while it is
-running*, but it doesn't lose track of where it was!
-
-All of the other things we learned above apply to streams of values as well -
-we can use [def][] to store them in the scope, transform them using the ops
-from the [math/][] module and so on:
-
-    (import* time math)
-    (def tik (tick 0.25))
-    (trace (/ tik 4))
-
-Note that if you leave the [time/tick][]'s *tag* in place when you move it into
-the [def][] expression, it will keep on running steadily even then.
-
-[pd]:   http://puredata.info/
-[max]:  https://cycling74.com/products/max
-[vvvv]: https://vvvv.org/
diff --git a/docs/guide/functions.md b/docs/guide/functions.md
deleted file mode 100644
index 917b8d4..0000000
--- a/docs/guide/functions.md
+++ /dev/null
@@ -1,54 +0,0 @@
-Another builtin that creates a nested scope is [fn][], which is used to
-create a *user-defined function*, which can be used to simplify repetitive
-code, amongst other things:
-
-    (import* math)
-
-    (def add-and-trace
-      (fn
-        (a b)
-        (trace (+ a b))))
-
-    (add-and-trace 1 2)
-    (add-and-trace 3 4)
-
-Here a *function* `add-and-trace` is defined. When defining a function, first
-the names of the parameters have to be given. The function defined here takes
-two parameters, `a` and `b`. The last part of the function definition is called
-the *function body*.
-
-A function created using [fn][] can be called just like an operator. When a
-function is called, the parameters to the function are defined with the names
-given in the definition, and then the function body is executed. The previous
-example is equivalent to the following:
-
-    (import* math)
-
-    (def add-and-trace
-      (fn
-        (a b)
-        (trace (+ a b)))
-
-    (do
-      (let a 1
-           b 2)
-      (trace (+ a b)))
-
-    (do
-      (let a 3
-           b 4)
-      (trace (+ a b)))
-
-and the output of both is:
-
-    trace (+ a b): <num= 3>
-    trace (+ a b): <num= 7>
-
-In `alv`, functions are first-class values and can be passed around just like
-numbers, strings, etc. However it is very common to define a function with a
-name, so there is the `defn` shorthand, which combines the `def` and `fn`
-builtins into a single expression. Compare this equivalent definition of the
-`add-and-trace` function:
-
-    (defn add-and-trace (a b)
-      (trace (+ a b)))
diff --git a/docs/guide/getting-started-guide.md b/docs/guide/index.md
index 9ca2f63..6933717 100644
--- a/docs/guide/getting-started-guide.md
+++ b/docs/guide/index.md
@@ -7,19 +7,21 @@ tools, `alive` takes the role of a 'conductor', telling the other tools what to
 play when by sending commands to them using a variety of protocols, such as OSC
 and MIDI.
 
+This guide will get you up and running with `alv` and [Pilot][pilot], explaining
+most of the basics along the way. For more complete documentation on the `alv` 
+language and features like functions, loops, etc. take a look at the
+[language reference](../reference/index.html).
+
 ## contents
 
-1.  [installation](installation.html)
-2.  [hello world](hello-world.html)
-3.  [working with the copilot](working-with-the-copilot.html)
-4.  [syntax](syntax.html)
-5.  [basic types](basic-types.html)
-6.  [importing operators](importing-operators.html)
-7.  [defining symbols](symbols.html)
-8.  [scopes](scopes.html)
-9.  [functions](functions.html)
-10. [evaltime and runtime](evaltime-and-runtime.html)
-11. [making sound](making-sound.html)
+1. [installation](01_installation.html)
+2. [hello world](02_hello-world.html)
+3. [working with the copilot](03_working-with-the-copilot.html)
+4. [syntax](04_syntax.html)
+5. [basic types](05_basic-types.html)
+6. [importing operators](06_importing-operators.html)
+7. [defining symbols](07_symbols.html)
+8. [making sound](08_making-sound.html)
 
 [supercollider]: https://supercollider.github.io/
 [pilot]:         https://github.com/hundredrabbits/Pilot
diff --git a/docs/guide/scopes.md b/docs/guide/scopes.md
deleted file mode 100644
index 87568ef..0000000
--- a/docs/guide/scopes.md
+++ /dev/null
@@ -1,82 +0,0 @@
-Both [import][] and [import*][] are actually shorthands and what they
-accomplish can be done using the lower-level builtins [def][], [use][] and
-[require][]. Here is how you could replace [import][]:
-
-    #(with import:)
-    (import math)
-    (trace (math/+ 1 2))
-
-    #(with def and require:)
-    (def math (require "math"))
-    (trace (math/+ 1 2))
-
-[require][] returns a *scope*, which is defined as the symbol `math`.
-Then `math/+` is resolved by looking for `+` in this nested scope. Note that
-the symbol that the scope is defined as and the name of the module that is
-loaded do not have to be the same, you could call the alias whatever you want:
-
-    #(this not possible with import!)
-    (def fancy-math (require "math"))
-    (trace (fancy-math/+ 1 2))
-
-Most of the time the name of the module makes a handy prefix already, so
-[import][] can be used to save a bit of typing and make the code look a bit
-cleaner. [import*][], on the other hand, defines every symbol from the imported
-module individually. It could be implemented with [use][] like this:
-
-    (use (require "math"))
-    (trace (+ 1 2))
-
-[use][] copies all symbol definitions from the scope it is passed to the
-current scope.
-
-Note that [import][], [import*][], [def][], and [use][] all can take multiple
-arguments:
-
-    #(using the shorthands:)
-    (import* math logic)
-    (import midi osc)
-
-    #(using require, use and def:)
-    (use (require "math") (require "logic"))
-    (def midi (require "midi")
-         osc  (require "osc"))
-
-It is common to have an [import][] and [import*][] expression at the top of an
-`alv` program to load all of the modules that will be used later, but the
-modules don't necessarily have to be loaded at the very beginning, as long as
-all symbols are defined before they are being used.
-
-## nested scopes
-Once a symbol is defined, it cannot be changed or removed:
-
-    (def a 3)
-    (def a 4) #(error!)
-
-It is, however, possible to 'shadow' a symbol by re-defining it in a nested
-scope: So far, all symbols we have defined - using `def`, [import][] and
-[import*][] - have been defined in the *global scope*, the scope that is active
-in the whole `alv` program. The [do][] builtin can be used to create a new
-scope and evaluate some expressions in it:
-
-    (import string)
-
-    (def a 1
-         b 2)
-
-    (trace (.. "first: " a " " b))
-    (do
-      (def a 3)
-      (trace (.. "second: " a " " b))
-    (trace (.. "third: " a " " b))
-
-This example prints the following:
-
-    trace (.. "first: " a " " b): <Value str: first: 1 2>
-    trace (.. "second: " a " " b): <Value str: second: 3 2>
-    trace (.. "third: " a " " b): <Value str: third: 1 2>
-
-As you can see, within a nested scope it is possible to overwrite a definition
-from the parent scope. Symbols that are not explicitly redefined in a nested
-scope keep their values, and changes in the nested scope do not impact the
-parent scope.