docs/typ gets book and HTML wrappers over one chapter list

style.typ lists the chapters in reading order (guide, cheatsheet,
scripting, reference, building), each with its content file or none
while unwritten. book.typ sets them as an A4 book with a title page and
contents, the tutor read from src/tutor.txt last; html.typ sets them as
one HTML page with a nav of anchors. An unwritten chapter shows a
placeholder, so both compile before the topics exist.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

1 files changed, 17 insertions, 4 deletions

diff --git a/docs/typ/README b/docs/typ/README
index b86d7ef2..f1eff604 100644
--- a/docs/typ/README
+++ b/docs/typ/README
@@ -7,20 +7,33 @@ docs/typ: the Typst documentation corpus
   cheatsheet.typ     content: facts as markup and the calls below, no
                      layout. Later topics (guide, scripting, reference,
                      building) go beside it as their own content files.
-  cheatsheet-a4.typ  an output wrapper: page, type, headings, then
-                     #include of the content. Future wrappers (book.typ,
-                     html.typ) sit beside it; wrappers hold no facts.
+  cheatsheet-a4.typ  output wrapper: the one-page A4 cheatsheet.
+  book.typ           output wrapper: an A4 book, title page, contents,
+                     every chapter, then the tutor (src/tutor.txt).
+  html.typ           output wrapper: one HTML page, every chapter under
+                     an anchor named by its id, then the tutor.
+                     Wrappers hold layout only, never facts.
+
+Chapters: `chapters` in style.typ lists them in reading order (guide,
+cheatsheet, scripting, reference, building), each with its content file,
+or none while it is not written (the outputs show a placeholder). To add
+a topic, write docs/typ/<id>.typ and set its `file`. Wrappers include it
+with heading offset 1, so its = headings sit under the chapter title.
 
 Build (from the repo root):
 
   typst compile --ignore-system-fonts docs/typ/cheatsheet-a4.typ
   zig build cheatsheet -Dplatform=tty --prefix DIR   # DIR/share/doc/pardes/cheatsheet.pdf
-  typst compile --features html --format html docs/typ/cheatsheet.typ out.html
+  typst compile --root . --ignore-system-fonts docs/typ/book.typ
+  typst compile --root . --features html --format html docs/typ/html.typ pardes.html
+(--root . because book and HTML read the tutor from src/tutor.txt.)
 
 The contract for content files
 ------------------------------
 Start a content file with
   #import "style.typ": key, keys, btn, chord, word, tag, addr, file, cmd, doc, pairs
+(a content file does not import page setup; the same file goes into the
+book, the HTML and, for the cheatsheet, the A4 page)
 and use plain markup (= headings, - lists, `raw`, *strong*) plus these.
 Never set page, fonts, colours or spacing in a content file; ask for a
 new function instead.