book: Reference, modules (slice of #590) #629

New issue

Open

opened 2026-10-29 21:23:24 +00:00 by orion · 0 comments

orion commented

2026-10-29 21:23:24 +00:00

Collaborator

Slice of #590 (Reference, part 2), which is a slice of the epic #582. Starts after nothing; #585 is merged. The Guide slices (#587, #588) write book/guide/ and the Reference part 1 slices (#589) write other pages of book/reference/; they are independent of this one and none of them replaces the old pages below. Governing note: book/CONCEPT.md ("How a page is written", "What CI checks"). Touches the seed: no (documentation only; no syntax change, no native, no driver flag, no std name looked up by the compiler).

Goal

Write the Reference page(s) reference/modules.md. Modules and use, visibility, cyclic imports, the prelude, and top-level code (which files may hold statements, compile-time top-level const). reference/packages.md (slice of #590) covers packages, workspaces and deprecation: link to it only once it is on main. Read like book/reference/bindings.md and book/reference/cases-and-patterns.md (merged in #585): complete for the area, still prose with a real program and its output under every rule.

Replaces in `docs/`

docs/language/modules-and-packages/index.md
docs/language/modules-and-packages/use.md
docs/language/modules-and-packages/visibility.md
docs/language/modules-and-packages/cyclic-imports.md
docs/language/modules-and-packages/the-prelude.md
docs/language/modules-and-packages/top-level-code.md

Acceptance criteria

Every page has the kind page, status: stable, front matter in the shape of book/reference/bindings.md (title, summary, order, keywords), and is written as book/CONCEPT.md, "How a page is written", says: the first paragraph says in two to four sentences what the page covers, headings name ideas, prose first, no history words, no internal references (no issue numbers, no links into docs/design, docs/contributing, docs/internals, CONCEPT.md), no Related/Next/See also sections, lists of at most seven items, every section starts with a sentence; links only to book pages that exist on main
Every trb run and trb error block is followed by its output block with the real output (a trb error block shows what torb check prints, from error: on); no fragments, no // prints comments
Every form, rule and compiler error a reader can hit in the area is on the page, as prose with trb run/trb error examples, not as a template of Syntax/Rules/What this is not; Examples that need several files show the file layout; every import, visibility and cycle error has a trb error example (or the real torb check output for a multi-file case).
The signature features of book/CONCEPT.md that the area touches are shown, not just named
book/reference/index.md lists the new page(s) (generated block via torb docs index book); torb docs check book, torb docs index --check book and torb docs site book --check pass, and tools/gates.sh passes in CI
The old pages listed under "Replaces in docs/" are deleted in the same PR unless a skill is still built from them (skills are generated by torb docs skill docs skills): for every old page a skill still needs, it stays in docs/ unpublished and the PR description names it and why; the others are deleted together with every link to them, and the skills are regenerated so docs skill --check stays green
No other book page is changed except the links that must follow from the deletion; the other Reference slices of #590 are not started

Notes for the implementer

Read book/CONCEPT.md, book/reference/bindings.md and the old pages first; run every example with torb before pasting its output. A rule that only the old page states and that you cannot reproduce is checked against the compiler, not copied.
Commits: one or two Conventional Commits, for example docs(book): reference modules and, if needed, docs: retire the pages the reference replaces.
Size: one PR, 30-40 minutes. Do not write the other Reference pages.

Slice of #590 (Reference, part 2), which is a slice of the epic #582. Starts after nothing; #585 is merged. The Guide slices (#587, #588) write `book/guide/` and the Reference part 1 slices (#589) write other pages of `book/reference/`; they are independent of this one and none of them replaces the old pages below. Governing note: `book/CONCEPT.md` ("How a page is written", "What CI checks"). Touches the seed: no (documentation only; no syntax change, no native, no driver flag, no std name looked up by the compiler). ## Goal Write the Reference page(s) `reference/modules.md`. Modules and `use`, visibility, cyclic imports, the prelude, and top-level code (which files may hold statements, compile-time top-level `const`). `reference/packages.md` (slice of #590) covers packages, workspaces and deprecation: link to it only once it is on main. Read like `book/reference/bindings.md` and `book/reference/cases-and-patterns.md` (merged in #585): complete for the area, still prose with a real program and its output under every rule. ## Replaces in `docs/` - `docs/language/modules-and-packages/index.md` - `docs/language/modules-and-packages/use.md` - `docs/language/modules-and-packages/visibility.md` - `docs/language/modules-and-packages/cyclic-imports.md` - `docs/language/modules-and-packages/the-prelude.md` - `docs/language/modules-and-packages/top-level-code.md` ## Acceptance criteria - [ ] Every page has the kind `page`, `status: stable`, front matter in the shape of `book/reference/bindings.md` (`title`, `summary`, `order`, `keywords`), and is written as `book/CONCEPT.md`, "How a page is written", says: the first paragraph says in two to four sentences what the page covers, headings name ideas, prose first, no history words, no internal references (no issue numbers, no links into `docs/design`, `docs/contributing`, `docs/internals`, `CONCEPT.md`), no Related/Next/See also sections, lists of at most seven items, every section starts with a sentence; links only to book pages that exist on main - [ ] Every `trb run` and `trb error` block is followed by its `output` block with the real output (a `trb error` block shows what `torb check` prints, from `error:` on); no fragments, no `// prints` comments - [ ] Every form, rule and compiler error a reader can hit in the area is on the page, as prose with `trb run`/`trb error` examples, not as a template of Syntax/Rules/What this is not; Examples that need several files show the file layout; every import, visibility and cycle error has a `trb error` example (or the real `torb check` output for a multi-file case). - [ ] The signature features of `book/CONCEPT.md` that the area touches are shown, not just named - [ ] `book/reference/index.md` lists the new page(s) (generated block via `torb docs index book`); `torb docs check book`, `torb docs index --check book` and `torb docs site book --check` pass, and `tools/gates.sh` passes in CI - [ ] The old pages listed under "Replaces in `docs/`" are deleted in the same PR unless a skill is still built from them (skills are generated by `torb docs skill docs skills`): for every old page a skill still needs, it stays in `docs/` unpublished and the PR description names it and why; the others are deleted together with every link to them, and the skills are regenerated so `docs skill --check` stays green - [ ] No other book page is changed except the links that must follow from the deletion; the other Reference slices of #590 are not started ## Notes for the implementer - Read `book/CONCEPT.md`, `book/reference/bindings.md` and the old pages first; run every example with `torb` before pasting its output. A rule that only the old page states and that you cannot reproduce is checked against the compiler, not copied. - Commits: one or two Conventional Commits, for example `docs(book): reference modules` and, if needed, `docs: retire the pages the reference replaces`. - Size: one PR, 30-40 minutes. Do not write the other Reference pages.

orion added the

loop

label

2026-10-29 21:23:35 +00:00

orion referenced this issue

2026-10-29 21:23:36 +00:00

book: Reference, part 2 (errors, traits, generics, collections, modules, concurrency, encoding) #590

orion referenced this issue

2026-10-29 21:23:36 +00:00

book: Reference, part 2 (errors, traits, generics, collections, modules, concurrency, encoding) #590