AtlatestRepositorysigil-doc
1
# Root profiles — parameterizing the root container3
`#lang sigil/doc` used to hardcode **"exactly one `@chapter`"** as the only legal4
document root. SD-P1 makes the root-command set *and its multiplicity* a parameter of5
the reader, so a delegating language can deliver its own roots without forking the6
grammar.8
**SD-P8 then used that parameter on `sigil/doc` itself** (ruling D8, 2026-08-22): the base9
language is generic and genres are languages. `#lang sigil/doc` admits exactly one10
`@article`; `@chapter` moved to the sibling genre language `#lang sigil/doc/book`. See11
[Two shipped languages](#two-shipped-languages) below.13
The two root-policy diagnostics are DERIVED from the profile, so a language's messages14
follow its root set with no second copy to keep in step. SD-P8 is the first change to15
exercise that: moving the base root set reworded both of its messages without touching16
the formatter.18
## What a profile is20
```sigil21
(import (sigil doc reader))23
(define folio-profile (make-document-profile "folio/doc" '(note project) 'one-or-more))24
```26
| field | meaning |27
| --- | --- |28
| `name` | prefixes the two **root-policy** diagnostics, so a delegating profile reports `folio/doc:` where the policy genuinely differs |29
| `roots` | non-empty list of distinct command-name symbols legal at top level |30
| `multiplicity` | `'one` or `'one-or-more` |32
The built-in `sigil-doc-profile` is `("sigil/doc" (article) one)`, and the genre profile33
`sigil-doc-book-profile` in `(sigil doc book reader)` is `("sigil/doc/book" (chapter) one)`.35
Everything is validated **at construction**, not at parse time: an empty root set, a36
non-symbol root, a duplicate root, an unknown multiplicity, or an empty name all raise37
immediately. A profile admitting no root would otherwise reject every document with a38
message naming no command — an always-red gate wearing a manuscript error's clothes.40
A profile is immutable and owns its aggregates. `document-profile-roots` hands back a41
copy, and mutating the list you passed to the constructor cannot widen a profile42
afterwards.44
`'zero-or-more` is deliberately absent. It would legalise a rootless document and so45
retire the diagnostic that catches an empty or truncated file. The vocabulary is closed46
because widening one later is cheap and narrowing one is not.48
## Parsing with a profile50
```sigil51
(define parts (parse-document-parts-with-profile profile source source-name header-end))52
(define author-forms (car parts)) ; top-level @(...) forms, in manuscript order53
(define roots (cadr parts)) ; lowered root syntax, in manuscript order54
```56
`roots` is a **list under both multiplicities**, so a delegating reader never has to57
discriminate on the shape. `parse-document-forms-with-profile` and58
`parse-document-source-with-profile` are the single-root conveniences; they raise if the59
profile actually delivered several roots.61
The three-argument `parse-document-source` / `parse-document-forms` spellings are62
unchanged and use `sigil-doc-profile`.64
## Reading a whole manuscript66
`read-language-source-with-profile` is the convenience path for a profile that keeps the67
`sigil/doc` author vocabulary and varies only the root container:69
- `'one` → the sequence `#lang sigil/doc` has always produced: prelude imports, the70
manuscript's author forms, `(define document <root>)`, `document`.71
- `'one-or-more` → `(define document-roots (list …))` and `document-roots`, in72
manuscript order.74
**A profile usually exists to change the author environment**, and such a language should75
call `parse-document-parts-with-profile` and assemble its own forms — its own prelude76
imports around the same roots. That is the intended shape for `#lang folio/doc`: delegate77
the complete grammar and every location here, change only the vocabulary and the roots.79
## What a profile does NOT vary81
- **Grammar-level diagnostics.** `fail-at` messages (`unexpected EOF; missing '}'`,82
`mismatched named block terminator`, …) keep the `sigil/doc:` prefix. The grammar is83
precisely what a profile must not fork, and D1/D2 pin those exact strings.84
- **The passive surface.** `(sigil doc inspect)` enforces no root policy at all and never85
did; it reports what a manuscript declares. See `docs/passive-parse-api.md`.86
- **Anything about `@` scanning, bodies, escapes, or locations.**88
## Two shipped languages90
sigil-doc ships the base plus the genres it owns. Today that is two languages, and they91
differ **only** in their root profile.93
| `#lang` | module | root set | multiplicity | what it is for |94
| --- | --- | --- | --- | --- |95
| `sigil/doc` | `(sigil doc reader)` | `(article)` | `one` | the generic standalone document — README, design doc, spec, memo, blog post |96
| `sigil/doc/book` | `(sigil doc book reader)` | `(chapter)` | `one` | the book/print genre; one manuscript is one chapter |98
The whole of the genre language is a profile and a two-line reader:100
```sigil101
(define-library (sigil doc book reader)102
(import (sigil core) (sigil doc reader))103
(export read-language-source sigil-doc-book-profile)104
(begin105
(define sigil-doc-book-profile106
(make-document-profile "sigil/doc/book" '(chapter) 'one))107
(define (read-language-source source context)108
(read-language-source-with-profile sigil-doc-book-profile source context))))109
```111
`#lang a/b/c` resolves to the module `(a b c reader)`, which is why a multi-segment112
language id needs nothing special from the reader.114
**Why `@chapter` is not a base root.** A chapter is a *part* of an assembly, and the115
assembly lives in this package too — `make-print-publication` in `(sigil doc publication)`,116
driven by a module such as `book/practical-sigil/book.sgl`. The language that hands you117
`@chapter` should be the one that owns book assembly. While `@chapter` was the base's only118
root, the base's most common root was a fragment of a workflow the base does not contain,119
and every standalone document had to call itself a chapter.121
**Why the root comes from `#lang` and not from an import.** Everything *below* the root is122
already import-extensible: an author command is an ordinary binding and a manuscript can123
`@(import …)` more of them. The root is different in kind — it is the document's *type*,124
the first fact a tool wants, and root policy is enforced at parse time from nothing but125
the source text. Making roots importable would either drag module resolution into the126
reader (so what a document *is* depends on installed package state, and an indexer whose127
normal case is scanning files it will reject could no longer classify one) or abolish root128
policy altogether, retiring the diagnostic that catches an empty or truncated file. So:129
**imports extend what a document can say; the `#lang` line declares what a document is.**131
**Where a new genre goes.** With its product owner, not here. `#lang folio/doc` is the132
proof that a package outside sigil-doc can own a genre: it constructs its own profile,133
delegates the complete grammar to `(sigil doc reader)`, and ships its own reader module.134
sigil-doc ships `book` because Practical Sigil and print publication live here.136
## Reachable model kinds138
The semantic model has two document kinds, `article` and `chapter`, and both are now139
producible from source by a shipped language. `book` was a third; SD-P8 removed it,140
because it was constructed nowhere in this package or in folio and a book is an141
*assembly* (`make-print-publication`) rather than a document kind. `make-document` now142
refuses it by name: `kind must be article or chapter`.144
Note the boundary, which D8 fixed deliberately: root **commands** are the profile's145
vocabulary and document **kinds** are the model's. A profile may name any command symbol;146
what that command constructs is the model's business. A genre needing genuinely new147
semantics follows folio's pattern — its own records, lowered to core kinds for148
publication — rather than a new core kind.150
## `@text{}` and `@expr{}` are ordinary commands152
The parser represents prose as a five-slot `(text () value start end)` node and author153
expressions as `(expr () syntax start end)`, while a command has six slots. `@text{…}` and154
`@expr{…}` are legal author commands whose head symbol collides with those pseudo-kinds.156
Every classification in the lowering path — including this phase's root allowlist, which157
is itself a head-symbol test — now discriminates on **slot count**, which is exact. An158
author's `@text{}` is dispatched as the command it is; the parser's own prose nodes are159
never confused with it.161
The measured before/after is `test/sd-p1-classification-probe.sgl` with its two162
transcripts in `test/transcripts/sd-p1/`.