docs(book): a book for people, and the site built from it #585

Merged

argus merged 13 commits from docs/582-book into main

2026-10-29 20:37:07 +00:00

orion commented

2026-10-29 14:23:29 +00:00

Collaborator

The documentation people read at torb.dev was rendered from the same docs/ tree that feeds the Agent Skills. That tree is built for completeness and fixed sections an agent can find, and it shows: 330k words, examples that never say what they print, design history and issue numbers on user pages, ## Related chains at the bottom of 249 pages. Torben's verdict in #582 was blunt, and the audit there backs it up.

This PR splits the two. docs/ stays the source of the skills and the contributor material. A new tree, book/, is written for people and is the only thing the site publishes.

What is in it

The concept and the research (book/CONCEPT.md, book/RESEARCH.md): who the book is for, six sections, how a page is written, what CI checks, and where every old page goes. Neither file is published.
The vertical slice: the new front page (book/site/home.md), the overview (book/index.md), "What makes TorbScript different" (book/why.md), the full Tour (nine pages), two Guide pages (handling-errors, your-own-constructs), two Reference pages (bindings, cases-and-patterns) and two Std pages (json, fs), plus the section indexes.
Moved unchanged: the course (start/), its German translation and the website pages (site/) moved from docs/ into book/. The pages left in docs/ that linked to them now link to the site.
The site builds from the book: torb docs site book, Dockerfile.site and images.yml read book/. The header shows Tour, Guide, Reference, Std, then the playground and the registry. No page of docs/ is published any more.

The rest of the book comes in one PR per section; the slice issues are listed on #582. Old pages in docs/ are deleted only when the section that replaces them lands, because the skills are built from them.

How the gates work

torb docs check treats a tree as a book when its root index has the kind book. On top of the rules every tree has, a book gets these, all in compiler/src/documentation/book.trb and snippets.trb, with tests in compiler/tests/documentation.test.trb:

Every trb run block is built and run, and what it prints must equal the output block under it, line by line.
The output block of a trb error block must be exactly what torb check main.trb prints for it, from error: on, so the reader sees the real message with its source line.
A trb run or trb error block without an output block directly under it is an error, and so is a stray output block. Fragments and skips are not allowed in a book.
Banned patterns: history words ("no longer", "formerly", "used to", "not yet", "legacy", "milestone" and the like), issue numbers, links out of the book or into design/contributing/internals material, and the headings "Related", "See also", "Next", "Goal" and "What this is not".
A list has at most seven items, and a section starts with a sentence, not with a list.

tools/gates.sh runs docs check book, docs index --check book and docs site book --check in the docs lane, so every pull request checks the whole book.

Refs #582

The documentation people read at torb.dev was rendered from the same `docs/` tree that feeds the Agent Skills. That tree is built for completeness and fixed sections an agent can find, and it shows: 330k words, examples that never say what they print, design history and issue numbers on user pages, `## Related` chains at the bottom of 249 pages. Torben's verdict in #582 was blunt, and the audit there backs it up. This PR splits the two. `docs/` stays the source of the skills and the contributor material. A new tree, `book/`, is written for people and is the only thing the site publishes. ## What is in it - **The concept and the research** (`book/CONCEPT.md`, `book/RESEARCH.md`): who the book is for, six sections, how a page is written, what CI checks, and where every old page goes. Neither file is published. - **The vertical slice**: the new front page (`book/site/home.md`), the overview (`book/index.md`), "What makes TorbScript different" (`book/why.md`), the full Tour (nine pages), two Guide pages (`handling-errors`, `your-own-constructs`), two Reference pages (`bindings`, `cases-and-patterns`) and two Std pages (`json`, `fs`), plus the section indexes. - **Moved unchanged**: the course (`start/`), its German translation and the website pages (`site/`) moved from `docs/` into `book/`. The pages left in `docs/` that linked to them now link to the site. - **The site builds from the book**: `torb docs site book`, `Dockerfile.site` and `images.yml` read `book/`. The header shows Tour, Guide, Reference, Std, then the playground and the registry. No page of `docs/` is published any more. The rest of the book comes in one PR per section; the slice issues are listed on #582. Old pages in `docs/` are deleted only when the section that replaces them lands, because the skills are built from them. ## How the gates work `torb docs check` treats a tree as a book when its root index has the kind `book`. On top of the rules every tree has, a book gets these, all in `compiler/src/documentation/book.trb` and `snippets.trb`, with tests in `compiler/tests/documentation.test.trb`: - Every `trb run` block is built and run, and what it prints must equal the `output` block under it, line by line. - The `output` block of a `trb error` block must be exactly what `torb check main.trb` prints for it, from `error:` on, so the reader sees the real message with its source line. - A `trb run` or `trb error` block without an `output` block directly under it is an error, and so is a stray `output` block. Fragments and skips are not allowed in a book. - Banned patterns: history words ("no longer", "formerly", "used to", "not yet", "legacy", "milestone" and the like), issue numbers, links out of the book or into design/contributing/internals material, and the headings "Related", "See also", "Next", "Goal" and "What this is not". - A list has at most seven items, and a section starts with a sentence, not with a list. `tools/gates.sh` runs `docs check book`, `docs index --check book` and `docs site book --check` in the docs lane, so every pull request checks the whole book. Refs #582

orion added 9 commits

2026-10-29 14:23:29 +00:00