Clean up documentation

docs/modules/ROOT/pages/zexp.adoc

@@ -1,11 +1,15 @@
 = zexps
 
 zexps, similar to g-expressions in Guix, are a way to generate
-S-expressions that are taggged with store paths. But that's where
-the similarity ends.
+S-expressions that are tagged with store paths. The syntax in Zilch is inspired
+by it, but has been developed separately.
 
+A zexp is used similarly to a ``quasiquote``d value in Scheme, but has an extra type
+of unquoting, called `zexp-unquote`, which unquotes a value such as a `++<store-path>++`
+or another `zexp`.
 
-To create a zexp, you can use either the full syntax, or the reader macro:
+Each `zexp` keeps track of the derivation outputs and store files it depends on,
+similarly to how string context works in Nix:
 
 [,scheme]
 ----
@@ -14,15 +18,14 @@ To create a zexp, you can use either the full syntax, or the reader macro:
 (zexp (foo bar (zexp-unquote baz)))
 ----
 
-`(zexp-unquote VAL)` returns the value that the zexp (or any compatible record)
-contains, while gathering the `zexp-unquote`d values used.
-
-Like quasiquotation, zexps can use `unquote`, including ``zexp-unquote``d values
-inside the ``unquote``d code. ``unquote``d code is evaluated when the `zexp` is evaluated.
+When a `zexp-unquote` (or its reader syntax, `#$`) is encountered, the value
+contained in the `zexp` (or compatible object) is used as-is, with no
+evaluation. It is possible to mix and match `zexp-unquote` with `unquote`,
+allowing building e.g. dynamic strings from zexps. `zexp-unquote` is always
+evaluated before `unquote` is.
 
 [,scheme]
 ----
-(define world #~,(begin (write "hello") "world"))
-(define hello #~("hello" ,(string-append "very " "cute") #$world))
-; When hello is used as zexp, it will also write "hello" to the output port.
+(define world ...)
+(define hello #~("hello" ,(string-append "very " "cute" #$world)))
 ----