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: Std pages, system and I/O #593

New issue
Open
opened 2026-10-29 14:25:45 +00:00 by orion · 3 comments
orion commented 2026-10-29 14:25:45 +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 one hand-written page in book/std/ per module: io, path, os, process, console, cli, stream, resource, storage, project, test, sandbox, expression. Each replaces docs/standard-library/<module>.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)
  • Each page opens with what the module is for and an example of the most common task, then covers the handful of tasks people use it for, each with an example and its output; it does not list every declaration
  • Each page names its module in the front matter (package: std/<module>), so the site links the generated API reference of torb doc std
  • Modules that touch the file system, processes or the network show output that is the same on every run (temporary directories, fixed inputs); no example depends on the machine it runs on

Children

  • #656 (io, path, console)
  • #657 (os)
  • #658 (process, test, resource)
  • #659 (cli)
  • #660 (stream, expression)
  • #661 (storage, project)
  • #662 (sandbox)
Slice of the epic #582. Starts after #585 (the concept, the vertical slice and the book gates) is merged. ## Scope Write one hand-written page in `book/std/` per module: `io`, `path`, `os`, `process`, `console`, `cli`, `stream`, `resource`, `storage`, `project`, `test`, `sandbox`, `expression`. Each replaces `docs/standard-library/<module>.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) - [ ] Each page opens with what the module is for and an example of the most common task, then covers the handful of tasks people use it for, each with an example and its output; it does not list every declaration - [ ] Each page names its module in the front matter (`package: std/<module>`), so the site links the generated API reference of `torb doc std` - [ ] Modules that touch the file system, processes or the network show output that is the same on every run (temporary directories, fixed inputs); no example depends on the machine it runs on ## Children - [ ] #656 (io, path, console) - [ ] #657 (os) - [ ] #658 (process, test, resource) - [ ] #659 (cli) - [ ] #660 (stream, expression) - [ ] #661 (storage, project) - [ ] #662 (sandbox)
orion commented 2026-10-29 23:05:18 +00:00
Author
Collaborator
Copy link

[loop:torbscript] intake: in scope (book std pages, slice of epic #582; dependency #585 is merged), no duplicate, no design-record collision, no seed impact. Next: refine (size check: 13 module pages in one PR is too large, split into one-page or small-group children).

[loop:torbscript] intake: in scope (book std pages, slice of epic #582; dependency #585 is merged), no duplicate, no design-record collision, no seed impact. Next: refine (size check: 13 module pages in one PR is too large, split into one-page or small-group children).
orion commented 2026-10-30 01:48:46 +00:00
Author
Collaborator
Copy link

[loop:torbscript] release refine: the old material of the thirteen modules is about 121 KB, too much for one PR; filed #656 (io, path, console), #657 (os), #658 (process, test, resource), #659 (cli), #660 (stream, expression), #661 (storage, project), #662 (sandbox), each with the criteria of this issue and its own Replaces in docs/ list. #593 now carries the checklist and no ready. All children carry loop and none is ready (made ready one after the other, CI is congested).

[loop:torbscript] next: waiting (children #656, #657, #658, #659, #660, #661, #662)

[loop:torbscript] wait until 2026-10-30T09:00Z: children are filed, not ready; they are made ready as PR slots free up.

[loop:torbscript] release refine: the old material of the thirteen modules is about 121 KB, too much for one PR; filed #656 (io, path, console), #657 (os), #658 (process, test, resource), #659 (cli), #660 (stream, expression), #661 (storage, project), #662 (sandbox), each with the criteria of this issue and its own `Replaces in docs/` list. #593 now carries the checklist and no `ready`. All children carry `loop` and none is `ready` (made ready one after the other, CI is congested). [loop:torbscript] next: waiting (children #656, #657, #658, #659, #660, #661, #662) [loop:torbscript] wait until 2026-10-30T09:00Z: children are filed, not ready; they are made ready as PR slots free up.
orion commented 2026-10-30 09:18:19 +00:00
Author
Collaborator
Copy link

[loop:torbscript] wait until 2026-10-30T12:00Z: children #656 to #662 are not ready yet; the worker slots are full (5 implementers running, 4 PRs open), they become ready as slots free up.
next: waiting (children #656 to #662) until 2026-10-30T12:00Z

[loop:torbscript] wait until 2026-10-30T12:00Z: children #656 to #662 are not ready yet; the worker slots are full (5 implementers running, 4 PRs open), they become ready as slots free up. next: waiting (children #656 to #662) until 2026-10-30T12:00Z
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#593
No description provided.