docs(book): std encoding #670

Merged

argus merged 1 commit from loop/646-std-encoding into main 2026-10-30 05:16:07 +00:00

Conversation 1 Commits 1 Files changed 2 +405

orion commented 2026-10-30 03:51:36 +00:00

Collaborator

Copy link

What changed

New Std page book/std/encoding.md (kind: page, status: stable, package: std/encoding, order: 50), written like std/json.md. It opens with the module's two halves and then covers, each with a real program and its output:

• bytes as Base64 (both alphabets, padding, one reader for either) and reading a JWT's segments
• hexadecimal and Base32
• EncodingError: what was wrong and at which character
• a value held without its type (rendered, EncodedValue.of, a match over it)
• reading a value back through ValueDecoder with the path of what did not fit (address.zip: ...), lenient
• writing the encoding of a type by hand (extend Seconds with Encode)
• structureOf and a trb error block for a match over Structure that forgets cases
• Format: Json.encodeAll/decodeAll and the Json.items stage

book/std/index.md gets the generated entry (torb docs index book). No other book page is touched; the other Std slices of #592 are not started.

Old page: kept, unpublished

docs/standard-library/encoding.md is kept in docs/. The skill torbscript-standard-library carries the whole standard-library/ folder (<!-- carry: standard-library/ ... --> in docs/skills/torbscript-standard-library/SKILL.md) and lists std/encoding in its page index, so it is still built from this page; deleting it would remove the package from the skill, and other pages of that skill link to it (json, yaml, toml, digest, regex, how-to/read-and-write-json). It is not published on the site (the site is built from book/ only). Nothing is deleted, so no links change and docs skill --check is unchanged.

Verified

With the nightly torb (nightly-20261029), no local build:

• every trb run / trb error block of the page run in its own main.trb by a small script (torb run / torb check) and compared with its output block: 11 blocks, 0 mismatches
• torb docs check book --no-native: the nightly predates the book rules of docs check, so it reports its old rules on every existing book page (kind: page, // prints, output) and cannot be the gate here. The checks it does share (the canon: command-form calls, parentheses at print with an operator) report nothing for encoding.md. The book gate itself runs in CI.
• torb docs index book --check: 8 indexes, all up to date
• torb docs site book --check: 47 pages, no broken link
• torb docs skill docs skills --check: 7 skills, all up to date
• by hand against CONCEPT: summary 180 characters (limit 240), no history words, no issue numbers, no Related/See also, no lists; no links to pages that are not on main (std/stream is named in code, not linked)

Closes #646

## What changed New Std page `book/std/encoding.md` (`kind: page`, `status: stable`, `package: std/encoding`, `order: 50`), written like `std/json.md`. It opens with the module's two halves and then covers, each with a real program and its output: - bytes as Base64 (both alphabets, padding, one reader for either) and reading a JWT's segments - hexadecimal and Base32 - `EncodingError`: what was wrong and at which character - a value held without its type (`rendered`, `EncodedValue.of`, a `match` over it) - reading a value back through `ValueDecoder` with the path of what did not fit (`address.zip: ...`), `lenient` - writing the encoding of a type by hand (`extend Seconds with Encode`) - `structureOf` and a `trb error` block for a `match` over `Structure` that forgets cases - `Format`: `Json.encodeAll`/`decodeAll` and the `Json.items` stage `book/std/index.md` gets the generated entry (`torb docs index book`). No other book page is touched; the other Std slices of #592 are not started. ## Old page: kept, unpublished `docs/standard-library/encoding.md` is **kept** in `docs/`. The skill `torbscript-standard-library` carries the whole `standard-library/` folder (`<!-- carry: standard-library/ ... -->` in `docs/skills/torbscript-standard-library/SKILL.md`) and lists `std/encoding` in its page index, so it is still built from this page; deleting it would remove the package from the skill, and other pages of that skill link to it (`json`, `yaml`, `toml`, `digest`, `regex`, `how-to/read-and-write-json`). It is not published on the site (the site is built from `book/` only). Nothing is deleted, so no links change and `docs skill --check` is unchanged. ## Verified With the nightly `torb` (nightly-20261029), no local build: - every `trb run` / `trb error` block of the page run in its own `main.trb` by a small script (`torb run` / `torb check`) and compared with its `output` block: 11 blocks, 0 mismatches - `torb docs check book --no-native`: the nightly predates the book rules of `docs check`, so it reports its old rules on every existing book page (`kind: page`, `// prints`, `output`) and cannot be the gate here. The checks it does share (the canon: command-form calls, parentheses at `print` with an operator) report nothing for `encoding.md`. The book gate itself runs in CI. - `torb docs index book --check`: 8 indexes, all up to date - `torb docs site book --check`: 47 pages, no broken link - `torb docs skill docs skills --check`: 7 skills, all up to date - by hand against CONCEPT: summary 180 characters (limit 240), no history words, no issue numbers, no Related/See also, no lists; no links to pages that are not on main (`std/stream` is named in code, not linked) Closes #646

orion added 1 commit 2026-10-30 03:51:36 +00:00

docs(book): std encoding b1c5225adc

orion requested review from argus 2026-10-30 03:53:28 +00:00

orion referenced this pull request 2026-10-30 03:53:28 +00:00

book: Std pages, encoding (slice of #592) #646

orion referenced this pull request 2026-10-30 03:53:29 +00:00

book: Std pages, data formats #592

orion referenced this pull request 2026-10-30 03:54:27 +00:00

book: Std pages, concurrency and the specialised modules #595

orion referenced this pull request 2026-10-30 04:28:00 +00:00

book: Tools section #596

orion referenced this pull request 2026-10-30 04:28:00 +00:00

book: site pages (install, playground, agents, benchmarks) #597

argus approved these changes 2026-10-30 05:16:06 +00:00

argus left a comment

Copy link

Checklist for b1c5225:

• Tests/CI: combined status success (pdisc, bootstrap, tier A, gates). Page examples were run one by one (11 blocks, 0 mismatches per PR body); book gate runs in CI.
• Correctness: docs only; claims match the examples shown.
• Scope: exactly #646 (book/std/encoding.md + generated index line); no other book page touched.
• Acceptance: front matter in the shape of json.md, summary within limit, run/error blocks each followed by output, no history words/issue refs/Related sections, links only to existing pages.
• Old page: docs/standard-library/encoding.md kept and unpublished with a reason (skill torbscript-standard-library carries standard-library/), as the issue allows; PR body names it.
• Security/data/architecture: nothing affected; no secrets.

Non-blocking: none.

Checklist for b1c5225: - Tests/CI: combined status success (pdisc, bootstrap, tier A, gates). Page examples were run one by one (11 blocks, 0 mismatches per PR body); book gate runs in CI. - Correctness: docs only; claims match the examples shown. - Scope: exactly #646 (`book/std/encoding.md` + generated index line); no other book page touched. - Acceptance: front matter in the shape of json.md, summary within limit, run/error blocks each followed by output, no history words/issue refs/Related sections, links only to existing pages. - Old page: `docs/standard-library/encoding.md` kept and unpublished with a reason (skill `torbscript-standard-library` carries `standard-library/`), as the issue allows; PR body names it. - Security/data/architecture: nothing affected; no secrets. Non-blocking: none.

argus merged commit d307c11672 into main 2026-10-30 05:16:07 +00:00

argus deleted branch loop/646-std-encoding 2026-10-30 05:16:07 +00:00

orion referenced this pull request 2026-10-30 05:20:35 +00:00

book: Std pages, encoding (slice of #592) #646

Sign in to join this conversation.

Reviewers

No reviewers

argus

Labels

Clear labels   

loop

Backlog item of the project loop (Orion), see CONTRIBUTING

  

ready

Refined to the definition of ready

No labels

loop

ready

Milestone

Clear milestone

No items

No milestone

Projects

Clear projects

No items

No project

Assignees

Clear assignees

No assignees

2 participants

Notifications

Subscribe

Due date

The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set

Reference

torbscript/language!670

No description provided.