docs: small fixes in guide and reference

7 files changed, 48 insertions, 29 deletions

diff --git a/docs/guide/01_installation.md b/docs/guide/01_installation.md
index 5a192fa..26a5e9f 100644
--- a/docs/guide/01_installation.md
+++ b/docs/guide/01_installation.md
@@ -36,6 +36,10 @@ With the `alive` package, two binaries should have been installed on your system
 apply the exports from `luarocks path` upon login, e.g. in your `.bashrc`.
 
 ## windows
+
+> Windows builds are currently not being updated. Please email me if you need
+> help setting up `alv`.
+
 For Windows, a binary package is available from the latest
 [github release][:*release*:]. It includes not only the `alv` source code, but
 also a compiled version of Lua 5.3 as well as Luarocks and all of `alv`'s
diff --git a/docs/guide/04_syntax.md b/docs/guide/04_syntax.md
index 29361f7..e4c79bc 100644
--- a/docs/guide/04_syntax.md
+++ b/docs/guide/04_syntax.md
@@ -29,12 +29,21 @@ expression simply by adding a `#` character in front.
 
     #(this is a comment)
 
+    #also-a-comment
+
     #(this is a long,
       multi-line comment,
       (and it also has nested parentheses).
       It ends after this sentence.)
 
 You can put comments anywhere in your program where whitespace is allowed and
-it will simply be ignored by `alv`.
+it will simply be ignored by `alv`. You can also comment an entire line using a
+double `##`:
+
+    (print "test") ## just a little note here
+
+    ## the next line is valid,
+    ## parenthesis ) ))) in line comments are #(just ignored.
+
 
 [clojure-style]: https://github.com/bbatsov/clojure-style-guide
diff --git a/docs/guide/06_importing-operators.md b/docs/guide/06_importing-operators.md
index 2195d5c..4baf19b 100644
--- a/docs/guide/06_importing-operators.md
+++ b/docs/guide/06_importing-operators.md
@@ -1,10 +1,10 @@
-Apart from [trace][], there are only very little builtin operators in `alv` -
+Apart from [trace][], there are relatively little builtin operators in `alv` -
 you can see all of them in the *builtins* section of the [reference][:/:].
 All of the 'real' functionality of `alv` is grouped into *modules*, that have
 to be loaded individually. *Modules* help organize all of the operators so that
 it is less overwhelming to look for a concrete feature. It is also possible to
-create your own plugins as new modules, which will be covered in another guide
-soon.
+create your own plugins as new modules, which is covered in the internals
+section.
 
 Let's try using the [`+` operator][:math/+:] from the [math/][] module. To use
 operators from a module, we need to tell `alv` to load it first: We can load
diff --git a/docs/guide/07_defining-symbols.md b/docs/guide/07_defining-symbols.md
index 488270a..207680d 100644
--- a/docs/guide/07_defining-symbols.md
+++ b/docs/guide/07_defining-symbols.md
@@ -21,10 +21,10 @@ symbol `result`, and then refer to it by that symbol in the [trace][] operator:
 
 Symbols need to start with a letter or one of the following special characters:
 
-    - + * /
-    _ . , =
-    ! ? % $
-    > < ~
+    - _ + * ^
+    % / . , =
+    ~ ! ? % $
+    > <
 
 After the first character, numbers are also allowed. There are two types of
 symbols that are treated specially: symbols containing a slash (`math/+`), and
diff --git a/docs/reference/02_evaltime-and-runtime.md b/docs/reference/02_evaltime-and-runtime.md
index e718cf3..16b33f5 100644
--- a/docs/reference/02_evaltime-and-runtime.md
+++ b/docs/reference/02_evaltime-and-runtime.md
@@ -1,22 +1,18 @@
-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.
+Execution in `alv` is split into two phases - *evaltime* and *runtime*.
+
+At *evaltime*, that is whenever there is change to the source code, `alv`
+behaves similar to a Lisp. 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].
+
+Every alive expression returns a *stream* 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`, 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][]:
diff --git a/docs/reference/04-2_pure-operators.md b/docs/reference/04-2_pure-operators.md
index b3bdf42..2239f02 100644
--- a/docs/reference/04-2_pure-operators.md
+++ b/docs/reference/04-2_pure-operators.md
@@ -10,9 +10,9 @@ mixed between all kinds of results, subject to the following rules:
 - If any of the inputs is a !-stream, the output is also an !-stream and will
   only fire when the input stream does. All other inputs will be sampled at
   that moment. At most one !-stream is allowed as an input.
-- Otherwise, if there are one more ~-streams in the inputs, the output will
+- Otherwise, if there is at least one ~-stream in the inputs, the output will
   also be a ~-stream and will be updated whenever any of the inputs changes.
-- Otherwise the output is a constant.
+- Otherwise (if all inputs are constants) the output is a constant.
 
 The input and output *types* are defined by the concrete Op.
 
diff --git a/docs/style.css b/docs/style.css
index 90123a2..f9c1ba9 100644
--- a/docs/style.css
+++ b/docs/style.css
@@ -46,6 +46,16 @@ pre > code.language-output {
   background: #222222;
   color: #cccccc;
 }
+pre > code.language-output {
+  background: #222222;
+  color: #cccccc;
+}
+
+blockquote {
+  margin: 0;
+  padding: 1px 1rem;
+  background: #eeddaa;
+}
 
 h1, h2, h3,
 h4, h5, h6 {