book: guide chapter modelling data (data or capsule, builder, map key, conversions)

orion commented

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

Collaborator

Slice of #587 (Guide chapters), which is a slice of the epic #582. Second chapter; #607 (first project) is merged. 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 Guide chapter book/guide/modelling-data.md: describing data with types, choosing between data and capsule, building values with a builder, using a type as a map key, and converting between types. Read like book/guide/handling-errors.md (the merged vertical slice from #585) and book/guide/first-project.md: one example that grows across the sections.

Replaces in `docs/`

docs/language/types/data-or-capsule.md
docs/how-to/write-a-builder.md
docs/how-to/use-a-type-as-a-map-key.md
docs/how-to/convert-between-types.md

About 21 KB of old material, one chapter; no further narrowing needed.

Acceptance criteria

book/guide/modelling-data.md exists with kind page, status: stable, front matter in the shape of the other guide chapters (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
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); a project.trb is shown as a bare trb block; no fragments, no // prints comments
The chapter covers: data and capsule and when to use which, fields and defaults, a builder, a type as a map key (what it needs to derive), and conversions between types (From/Into, parsing, and what fails)
The signature features this area touches are shown, not just named: "No null and no exceptions" and "Every case is handled" in the example that grows
One example grows across the sections (CONCEPT.md, "Examples grow"), and it is a program, not a list of commands
book/guide/index.md lists the new chapter (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 four old pages are deleted in the same PR unless a skill is still built from them (torb docs skill docs skills generates the 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 (tour/, start/, reference/, std/) is changed except the links that must follow from the deletion; the other five chapters of #587 are not started

Notes for the implementer

Read book/CONCEPT.md, book/guide/handling-errors.md and book/guide/your-own-constructs.md and book/guide/first-project.md first; run the examples with torb before pasting their output.
Commits: one or two Conventional Commits, for example docs(book): guide chapter modelling data and, if needed, docs: retire the pages the chapter replaces.
Size: one PR, 30-40 minutes. Do not write other chapters.

Slice of #587 (Guide chapters), which is a slice of the epic #582. Second chapter; #607 (first project) is merged. 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 Guide chapter `book/guide/modelling-data.md`: describing data with types, choosing between `data` and `capsule`, building values with a builder, using a type as a map key, and converting between types. Read like `book/guide/handling-errors.md` (the merged vertical slice from #585) and `book/guide/first-project.md`: one example that grows across the sections. ## Replaces in `docs/` - `docs/language/types/data-or-capsule.md` - `docs/how-to/write-a-builder.md` - `docs/how-to/use-a-type-as-a-map-key.md` - `docs/how-to/convert-between-types.md` About 21 KB of old material, one chapter; no further narrowing needed. ## Acceptance criteria - [ ] `book/guide/modelling-data.md` exists with kind `page`, `status: stable`, front matter in the shape of the other guide chapters (`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 - [ ] 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); a `project.trb` is shown as a bare `trb` block; no fragments, no `// prints` comments - [ ] The chapter covers: `data` and `capsule` and when to use which, fields and defaults, a builder, a type as a map key (what it needs to derive), and conversions between types (`From`/`Into`, parsing, and what fails) - [ ] The signature features this area touches are shown, not just named: "No null and no exceptions" and "Every case is handled" in the example that grows - [ ] One example grows across the sections (CONCEPT.md, "Examples grow"), and it is a program, not a list of commands - [ ] `book/guide/index.md` lists the new chapter (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 four old pages are deleted in the same PR unless a skill is still built from them (`torb docs skill docs skills` generates the 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 (`tour/`, `start/`, `reference/`, `std/`) is changed except the links that must follow from the deletion; the other five chapters of #587 are not started ## Notes for the implementer - Read `book/CONCEPT.md`, `book/guide/handling-errors.md` and `book/guide/your-own-constructs.md` and `book/guide/first-project.md` first; run the examples with `torb` before pasting their output. - Commits: one or two Conventional Commits, for example `docs(book): guide chapter modelling data` and, if needed, `docs: retire the pages the chapter replaces`. - Size: one PR, 30-40 minutes. Do not write other chapters.

orion added the

loop

ready

labels

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

orion referenced this issue

2026-10-29 23:37:30 +00:00

book: Guide chapters (first project, modelling data, collections, files and formats, testing, native programs, design choices) #587

orion referenced this issue

2026-10-29 23:37:30 +00:00

book: Guide chapters (first project, modelling data, collections, files and formats, testing, native programs, design choices) #587

orion commented

2026-10-29 23:51:16 +00:00

Author

Collaborator

[loop:torbscript] claim implement by session:loop-torbscript-20261030 until 2026-10-30T05:51Z

orion referenced this issue from a pull request that will close it,

2026-10-30 00:02:23 +00:00

docs(book): guide chapter modelling data #645

orion commented

2026-10-30 00:02:27 +00:00

Author

Collaborator

[loop:torbscript] checkpoint: pushed loop/636-guide-modelling-data; PR #645 open (Closes #636), review requested from argus, waiting on forge CI. The four old pages stay in docs/ (skills still carry them).

orion commented

2026-10-30 00:54:21 +00:00

Author

Collaborator

[loop:torbscript] checkpoint: PR #645 open (c5c83a68). Green: commit messages, what the change touches, pdisc. Still pending after more than 1 h in the runner queue: gates and the platform jobs. docs check book and docs site --check were not judged locally (the local nightly does not run book mode), so gates is the first real verdict. The old pages stay in docs/.

[loop:torbscript] checkpoint: PR #645 open (c5c83a68). Green: commit messages, what the change touches, pdisc. Still pending after more than 1 h in the runner queue: gates and the platform jobs. `docs check book` and `docs site --check` were not judged locally (the local nightly does not run book mode), so gates is the first real verdict. The old pages stay in docs/.

orion commented

2026-10-30 00:54:33 +00:00

Author

Collaborator

[loop:torbscript] release implement: PR #645 (head c5c83a68) is open and in review. Green: commit messages, touches, pdisc. gates is still queued; it is the first real check of docs check book and docs site book --check, since the local nightly has no book mode. Old pages stay in docs/ for now; retiring them is a follow-up after CI is green. CI and Argus decide.

[loop:torbscript] release implement: PR #645 (head c5c83a68) is open and in review. Green: commit messages, touches, pdisc. `gates` is still queued; it is the first real check of `docs check book` and `docs site book --check`, since the local nightly has no book mode. Old pages stay in docs/ for now; retiring them is a follow-up after CI is green. CI and Argus decide.