split guide into guide and reference

1 files changed, 0 insertions, 82 deletions

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.