From dbc3779c552f616437574e04c8673c6f5d8382a6 Mon Sep 17 00:00:00 2001
From: Taylan Kammer <taylan.kammer@gmail.com>
Date: Sun, 11 Jan 2026 13:02:29 +0100
Subject: Docs.

---
 .gitignore         |  3 ++-
 docs/c1/1-parse.md | 16 +++++++++++-----
 docs/c1/index.md   |  2 ++
 docs/index.md      |  6 +++---
 html/gen.sh        | 27 ++++++++++++++++++++++++---
 5 files changed, 42 insertions(+), 12 deletions(-)
 create mode 100644 docs/c1/index.md

diff --git a/.gitignore b/.gitignore
index ac25911..66c4be2 100644
--- a/.gitignore
+++ b/.gitignore
@@ -1,6 +1,7 @@
 /html/highlightjs
 /html/index.html
-/html/notes/*.html
+/html/notes
+/html/docs
 .zig-cache
 zig-out
 a.out
diff --git a/docs/c1/1-parse.md b/docs/c1/1-parse.md
index e04240b..b01d759 100644
--- a/docs/c1/1-parse.md
+++ b/docs/c1/1-parse.md
@@ -1,5 +1,7 @@
 # Parser for Code & Data
 
+*For an exact specification of the grammar, see [grammar](grammar.html).*
+
 Zisp S-Expressions represent an extremely minimal set of data types; only that
 which is necessary to strategically construct more complex code and data:
 
@@ -52,9 +54,13 @@ Further notes about the syntax sugar table and examples above:
   hash sign, or a pipe-quoted string (see next).  A bare string can follow the
   hash sign by separating the two with a backslash: `#\string`
 
-* Strings can be quoted with pipes, like symbols in Scheme:
+* Strings can be quoted with pipes, like symbols in Scheme.  This is the "real"
+  string literal syntax, whereas using double quotes is syntax sugar for a
+  quoted string literal.
+
+      |foo bar baz|  -> |foo bar baz|
 
-      |foo bar baz|
+      "foo bar baz"  -> (#QUOTE & |foo bar baz|)
 
 * Though not represented in the table due to notational difficulty, the form
   `#rune(...)` doesn't require a list in the second position; any datum that
@@ -73,7 +79,9 @@ Further notes about the syntax sugar table and examples above:
 
       #abcdefgh  ;Could be (#abcdef & gh) or (#abcde & fgh) or ...
 
-* Syntax sugar can combine arbitrarily; some examples follow:
+* Syntax sugar can combine arbitrarily.  Some examples follow.  Any of these may
+  or may not actually have a meaning in code; many could simply end up producing
+  a syntax error at the macro-expand stage.
 
       #{...}            -> (#HASH #BRACE ...)
 
@@ -105,8 +113,6 @@ Further notes about the syntax sugar table and examples above:
   Zisp's internal use and standard library; users can use lowercase runes with
   custom meaning without worrying about clashes.
 
-For an exact specification of the grammar, see [grammar](grammar.html).
-
 <!--
 ;; Local Variables:
 ;; fill-column: 80
diff --git a/docs/c1/index.md b/docs/c1/index.md
new file mode 100644
index 0000000..f306e11
--- /dev/null
+++ b/docs/c1/index.md
@@ -0,0 +1,2 @@
+# Chapter 1: Genesis
+
diff --git a/docs/index.md b/docs/index.md
index ca8d814..471d518 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -27,10 +27,10 @@ code base.
 
 2. [Chapter 2: Types](c2/)
 
-   Following is an enumeration of the standard data types, and the
-   methods Zisp offers for generating new types.
+   This chapter deals with the standard data types, and the methods
+   Zisp offers for defining new types.
 
    1. ...
    2. ...
 
-3. [Chapter 3: ...]
+3. [Chapter 3: ...](c3/)
diff --git a/html/gen.sh b/html/gen.sh
index 445704f..03ae570 100755
--- a/html/gen.sh
+++ b/html/gen.sh
@@ -28,11 +28,32 @@ md2ht() {
 
 md2ht index.md index.html
 
-for note in ../notes/*.md
+for file in ../notes/*.md
 do
-    name=${note#../notes/}
+    name=${file#../notes/}
     name=${name%.md}
-    md2ht "$note" "notes/$name.html"
+    md2ht "$file" "notes/$name.html"
+done
+
+shopt -s globstar
+
+for file in ../docs/**/*.md
+do
+    name=${file#../docs/}
+    name=${name%.md}
+    dir=${file#../}
+    dir=${dir%/*}
+    mkdir -p "$dir"
+    md2ht "$file" "docs/$name.html"
+done
+
+for file in ../docs/**/*.txt
+do
+    dir=${file#../}
+    dir=${dir%/*}
+    mkdir -p "$dir"
+    dest=docs/${file#../docs/}
+    cp "$file" "$dest"
 done
 
 rsync -a ./ tk:/var/www/html/zisp
-- 
cgit v1.2.3