torbscript/language
Watch
1
0
Fork
You've already forked language
 0
Code Issues 139 Pull requests 2 Projects Releases 18 Packages 3 Wiki Activity Actions

book: Reference, part 1 (syntax, built-in types, strings, functions, types, control flow) #589

New issue
Open
opened 2026-10-29 14:25:44 +00:00 by orion · 4 comments
orion commented 2026-10-29 14:25:44 +00:00
Collaborator
Copy link

Slice of the epic #582. Starts after #585 (the concept, the vertical slice and the book gates) is merged.

Scope

Write these pages of book/reference/, each complete for its area:

New page Replaces in docs/
reference/syntax.md language/syntax/*
reference/built-in-types.md, reference/strings.md language/values-and-types/* except bindings.md
reference/functions.md language/functions/*
reference/types.md language/types/* except the pages bindings.md and cases-and-patterns.md already cover
reference/control-flow.md language/execution/* except copies.md, language/extensibility/control-structures.md

Acceptance criteria

  • Every page has the kind page and is written as book/CONCEPT.md, "How a page is written", says: the first paragraph says what the page covers, headings name ideas, prose first, no history, no internal references, no Related/Next sections
  • Every trb run and trb error block has its output block with the real output; torb docs check book, torb docs index --check book and torb docs site book --check pass in CI
  • The signature features of book/CONCEPT.md that the area touches are shown, not just named
  • The old pages of docs/ this slice replaces are deleted in the same PR, unless a skill is still built from them (then they stay, unpublished, and the PR says which)
  • 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

Pages

Filed as child issues, each its own PR; only the first carries ready, the others are made ready one after the other. The pages are independent (links only to pages already on main), so the order is a suggestion. The first slice that touches a page set also decides the order: front matter of the Reference index.

  • reference/syntax.md - #609 (ready)
  • reference/strings.md - #610
  • reference/numbers.md - #611
  • reference/built-in-types.md - #612
  • reference/functions.md - #613
  • reference/command-calls.md and reference/closures.md - #614
  • reference/types.md - #615
  • reference/changing-values.md - #616
  • reference/conversions.md - #617
  • reference/control-flow.md - #618

Changes against the table above: the strings page is split off the built-in types, numbers get their own page, types is cut into types, changing-values and conversions, and command-calls and closures are new pages (command calls were part of syntax). syntax/cheat-sheet.md has no new page and stays until it is retired.

Slice of the epic #582. Starts after #585 (the concept, the vertical slice and the book gates) is merged. ## Scope Write these pages of `book/reference/`, each complete for its area: | New page | Replaces in `docs/` | |---|---| | `reference/syntax.md` | `language/syntax/*` | | `reference/built-in-types.md`, `reference/strings.md` | `language/values-and-types/*` except `bindings.md` | | `reference/functions.md` | `language/functions/*` | | `reference/types.md` | `language/types/*` except the pages `bindings.md` and `cases-and-patterns.md` already cover | | `reference/control-flow.md` | `language/execution/*` except `copies.md`, `language/extensibility/control-structures.md` | ## Acceptance criteria - [ ] Every page has the kind `page` and is written as `book/CONCEPT.md`, "How a page is written", says: the first paragraph says what the page covers, headings name ideas, prose first, no history, no internal references, no Related/Next sections - [ ] Every `trb run` and `trb error` block has its `output` block with the real output; `torb docs check book`, `torb docs index --check book` and `torb docs site book --check` pass in CI - [ ] The signature features of `book/CONCEPT.md` that the area touches are shown, not just named - [ ] The old pages of `docs/` this slice replaces are deleted in the same PR, unless a skill is still built from them (then they stay, unpublished, and the PR says which) - [ ] 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 ## Pages Filed as child issues, each its own PR; only the first carries `ready`, the others are made ready one after the other. The pages are independent (links only to pages already on main), so the order is a suggestion. The first slice that touches a page set also decides the `order:` front matter of the Reference index. - [ ] `reference/syntax.md` - #609 (ready) - [ ] `reference/strings.md` - #610 - [ ] `reference/numbers.md` - #611 - [ ] `reference/built-in-types.md` - #612 - [ ] `reference/functions.md` - #613 - [ ] `reference/command-calls.md` and `reference/closures.md` - #614 - [ ] `reference/types.md` - #615 - [ ] `reference/changing-values.md` - #616 - [ ] `reference/conversions.md` - #617 - [ ] `reference/control-flow.md` - #618 Changes against the table above: the strings page is split off the built-in types, numbers get their own page, `types` is cut into `types`, `changing-values` and `conversions`, and `command-calls` and `closures` are new pages (command calls were part of syntax). `syntax/cheat-sheet.md` has no new page and stays until it is retired.
orion commented 2026-10-29 21:00:33 +00:00
Author
Collaborator
Copy link

[loop:torbscript] intake: in scope (book Reference part 1, slice of epic #582), no duplicate. Next: refine (size check: five-plus pages in one PR is likely too large).

[loop:torbscript] intake: in scope (book Reference part 1, slice of epic #582), no duplicate. Next: refine (size check: five-plus pages in one PR is likely too large).
orion commented 2026-10-29 21:00:34 +00:00
Author
Collaborator
Copy link

[loop:torbscript] claim refine by session:loop-torbscript-20261029-0858 until 2026-10-30T00:00Z

[loop:torbscript] claim refine by session:loop-torbscript-20261029-0858 until 2026-10-30T00:00Z
orion commented 2026-10-29 21:02:53 +00:00
Author
Collaborator
Copy link

[loop:torbscript] release refine: filed #609 (syntax, ready), #610 (strings), #611 (numbers), #612 (built-in types), #613 (functions), #614 (command calls and closures), #615 (types), #616 (changing values), #617 (conversions and the generated Show), #618 (control flow and evaluation). Five-plus pages in one PR was too large (about 320 KB of old pages), so each child is one page or a small group of 2-9 old pages, 30-40 minutes, with the criteria of this issue and its own Replaces in docs/ list; #589 now carries the checklist and no ready. Only #609 is ready; the others carry loop and are made ready one after the other (the pages do not depend on each other, links only to pages already on main). No conflict with #587/#588: they write book/guide/; the one shared old page, docs/language/types/data-or-capsule.md, is replaced by #587 and is excluded from #615.

[loop:torbscript] next: waiting (children #609, #610, #611, #612, #613, #614, #615, #616, #617, #618)

[loop:torbscript] release refine: filed #609 (syntax, ready), #610 (strings), #611 (numbers), #612 (built-in types), #613 (functions), #614 (command calls and closures), #615 (types), #616 (changing values), #617 (conversions and the generated Show), #618 (control flow and evaluation). Five-plus pages in one PR was too large (about 320 KB of old pages), so each child is one page or a small group of 2-9 old pages, 30-40 minutes, with the criteria of this issue and its own `Replaces in docs/` list; #589 now carries the checklist and no `ready`. Only #609 is `ready`; the others carry `loop` and are made ready one after the other (the pages do not depend on each other, links only to pages already on main). No conflict with #587/#588: they write `book/guide/`; the one shared old page, `docs/language/types/data-or-capsule.md`, is replaced by #587 and is excluded from #615. [loop:torbscript] next: waiting (children #609, #610, #611, #612, #613, #614, #615, #616, #617, #618)
orion commented 2026-10-30 14:24:35 +00:00
Author
Collaborator
Copy link

[loop:torbscript] refine: epic checklist stands, children #609 to #618 carry the work (one page or small group each, made ready one after the other).
next: waiting (children #609 to #618)

[loop:torbscript] refine: epic checklist stands, children #609 to #618 carry the work (one page or small group each, made ready one after the other). next: waiting (children #609 to #618)
Sign in to join this conversation.
No Branch/Tag specified
Branches Tags
main
loop/705-default-shadow
loop/691-tensor-core
loop/705-fix-candidate
orion/456-tierb-probe
loop/164-measure2
loop/207-measure
loop/164-prototype
probe/207-count
loop/205-measure
loop/140-hide-staged
nightly-20261103
nightly-20261031
nightly-20261029
nightly-20261027
nightly-20261026
nightly-20261025
nightly-20261024
nightly-20261023
nightly-20261021
nightly-20261020
nightly-20261015
nightly-20261014
nightly-20261013
nightly-20261011
nightly-20261010
nightly-20261009
nightly-20261008
seeds
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
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Blocks
#599 book: retire the human pages of docs/
torbscript/language
Depends on
#585 docs(book): a book for people, and the site built from it
torbscript/language
Reference
torbscript/language#589
No description provided.