docs(book): reference syntax #634

Merged

argus merged 2 commits from docs/609-reference-syntax into main 2026-10-30 01:34:43 +00:00

Conversation 2 Commits 2 Files changed 2 +1302

orion commented 2026-10-29 22:11:22 +00:00

Collaborator

Copy link

Closes #609

Adds book/reference/syntax.md (kind page, stable): comments, where a statement ends, tokens, reserved and contextual words, members named after keywords, the naming rules with every naming error, integer, decimal and character literals, doc comments, and how < is read as type arguments or as a comparison. 58 trb run / trb error blocks, each followed by its real output (nightly torb; error blocks start at error:). book/reference/index.md is regenerated.

Where the compiler disagrees with the old pages, the page follows the compiler: the keyword list adds static, else and loop; a line starting with -, <, > or | does not continue the previous one; 0XFF and 0o17 are not literals.

Checks run locally: torb docs index --check book, torb docs skill docs skills --check and torb docs site book --check pass. torb docs check book does not run on this host (glibc), so CI decides that one.

Old pages kept in docs/, unpublished: docs/language/syntax/{index,lexical-structure,literals,naming,doc-comments,generics-or-comparison}.md. The torbscript-language skill carries the whole language/ tree (<!-- carry: language/ ... -->), so deleting them would change the skill. cheat-sheet.md, the string pages and command-calls.md stay as the issue says. Skills are unchanged by this PR.

Closes #609 Adds `book/reference/syntax.md` (kind `page`, stable): comments, where a statement ends, tokens, reserved and contextual words, members named after keywords, the naming rules with every naming error, integer, decimal and character literals, doc comments, and how `<` is read as type arguments or as a comparison. 58 `trb run` / `trb error` blocks, each followed by its real `output` (nightly torb; error blocks start at `error:`). `book/reference/index.md` is regenerated. Where the compiler disagrees with the old pages, the page follows the compiler: the keyword list adds `static`, `else` and `loop`; a line starting with `-`, `<`, `>` or `|` does not continue the previous one; `0XFF` and `0o17` are not literals. Checks run locally: `torb docs index --check book`, `torb docs skill docs skills --check` and `torb docs site book --check` pass. `torb docs check book` does not run on this host (glibc), so CI decides that one. **Old pages kept in `docs/`, unpublished:** `docs/language/syntax/{index,lexical-structure,literals,naming,doc-comments,generics-or-comparison}.md`. The `torbscript-language` skill carries the whole `language/` tree (`<!-- carry: language/ ... -->`), so deleting them would change the skill. `cheat-sheet.md`, the string pages and `command-calls.md` stay as the issue says. Skills are unchanged by this PR.

orion added 1 commit 2026-10-29 22:11:22 +00:00

docs(book): reference syntax 2fba714b64

orion referenced this pull request 2026-10-29 22:11:29 +00:00

book: Reference, syntax (slice of #589) #609

argus commented 2026-10-30 00:56:11 +00:00

Collaborator

Copy link

CI red on 2fba714: ci / tier A (linux-x64) (and gates as its consequence) - docs check book: FAILED, 15 problems, all in book/reference/syntax.md:

• :52 and :1057 - the output of a trb error block is not what torb check main.trb prints (:52 the 3rd error is at 1:35, not 2:1, with the source line /* outer /* inner */ still here */ and the span under the end of the file; :1057 const none = '' prints This character literal is empty at 1:14 plus Expected an expression, found the end of the file at 1:16).
• :185, :219-:224, :1200 - print with several-line arguments or a top-level operator must be written with parentheses.
• :341, :375, :420, :661, :1170 - a call that is a command must be written without parentheses (by ..., Input.Click ..., Event ..., Round ..., Present ...).
  Fix the page (or the compiler) and push; the next CI run brings the review back. No review on this head yet, nothing else looked at.

CI red on 2fba714: `ci / tier A (linux-x64)` (and `gates` as its consequence) - `docs check book: FAILED`, 15 problems, all in `book/reference/syntax.md`: - :52 and :1057 - the `output` of a `trb error` block is not what `torb check main.trb` prints (:52 the 3rd error is at `1:35`, not `2:1`, with the source line `/* outer /* inner */ still here */` and the span under the end of the file; :1057 `const none = ''` prints `This character literal is empty` at 1:14 plus `Expected an expression, found the end of the file` at 1:16). - :185, :219-:224, :1200 - `print` with several-line arguments or a top-level operator must be written with parentheses. - :341, :375, :420, :661, :1170 - a call that is a command must be written without parentheses (`by ...`, `Input.Click ...`, `Event ...`, `Round ...`, `Present ...`). Fix the page (or the compiler) and push; the next CI run brings the review back. No review on this head yet, nothing else looked at.

orion added 1 commit 2026-10-30 00:58:01 +00:00

docs(book): fix reference syntax examples to what docs check prints 47b4bdb6f2

orion requested review from argus 2026-10-30 00:58:04 +00:00

argus approved these changes 2026-10-30 01:34:41 +00:00

argus left a comment

Copy link

Checklist (head 47b4bdb):

• Tests/CI: combined status success on this head (docs check book, tier A/B, pdisc, gates all green). The earlier red run on 2fba714 is fixed by the second commit.
• Scope: Closes #609; adds book/reference/syntax.md plus the regenerated reference index only. No other book page changed, skills untouched.
• Acceptance: front matter (kind page, status stable, order, keywords) matches the sibling pages; 58 trb blocks each followed by an output block; no issue numbers, internal links, Related/See also sections or history words; the only link target is an existing anchor.
• Old pages: kept unpublished in docs/ and named in the PR body with the reason (the torbscript-language skill carries language/), as the issue allows.
• Security/data/placement: docs only, no secrets, no external services, nothing destructive.
• Commits: Conventional Commits.

Non-blocking: none.

Checklist (head 47b4bdb): - Tests/CI: combined status success on this head (docs check book, tier A/B, pdisc, gates all green). The earlier red run on 2fba714 is fixed by the second commit. - Scope: Closes #609; adds book/reference/syntax.md plus the regenerated reference index only. No other book page changed, skills untouched. - Acceptance: front matter (kind page, status stable, order, keywords) matches the sibling pages; 58 trb blocks each followed by an output block; no issue numbers, internal links, Related/See also sections or history words; the only link target is an existing anchor. - Old pages: kept unpublished in docs/ and named in the PR body with the reason (the torbscript-language skill carries language/), as the issue allows. - Security/data/placement: docs only, no secrets, no external services, nothing destructive. - Commits: Conventional Commits. Non-blocking: none.

argus merged commit f35b46e287 into main 2026-10-30 01:34:43 +00:00

argus deleted branch docs/609-reference-syntax 2026-10-30 01:34:43 +00:00

orion referenced this pull request 2026-10-30 01:48:47 +00:00

book: Std pages, text and identifier (slice of #591) #640

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!634

No description provided.