AtlatestRepositorysigil-doc

sigil-doc / tree / docsroot-profiles.md

Read it rendered

1# Root profiles — parameterizing the root container
2
3`#lang sigil/doc` used to hardcode **"exactly one `@chapter`"** as the only legal
4document root. SD-P1 makes the root-command set *and its multiplicity* a parameter of
5the reader, so a delegating language can deliver its own roots without forking the
6grammar.
7
8**SD-P8 then used that parameter on `sigil/doc` itself** (ruling D8, 2026-08-22): the base
9language is generic and genres are languages. `#lang sigil/doc` admits exactly one
10`@article`; `@chapter` moved to the sibling genre language `#lang sigil/doc/book`. See
11[Two shipped languages](#two-shipped-languages) below.
13The two root-policy diagnostics are DERIVED from the profile, so a language's messages
14follow its root set with no second copy to keep in step. SD-P8 is the first change to
15exercise that: moving the base root set reworded both of its messages without touching
16the formatter.
18## What a profile is
20```sigil
21(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` |
32The built-in `sigil-doc-profile` is `("sigil/doc" (article) one)`, and the genre profile
33`sigil-doc-book-profile` in `(sigil doc book reader)` is `("sigil/doc/book" (chapter) one)`.
35Everything is validated **at construction**, not at parse time: an empty root set, a
36non-symbol root, a duplicate root, an unknown multiplicity, or an empty name all raise
37immediately. A profile admitting no root would otherwise reject every document with a
38message naming no command — an always-red gate wearing a manuscript error's clothes.
40A profile is immutable and owns its aggregates. `document-profile-roots` hands back a
41copy, and mutating the list you passed to the constructor cannot widen a profile
42afterwards.
44`'zero-or-more` is deliberately absent. It would legalise a rootless document and so
45retire the diagnostic that catches an empty or truncated file. The vocabulary is closed
46because widening one later is cheap and narrowing one is not.
48## Parsing with a profile
50```sigil
51(define parts (parse-document-parts-with-profile profile source source-name header-end))
52(define author-forms (car parts)) ; top-level @(...) forms, in manuscript order
53(define roots (cadr parts)) ; lowered root syntax, in manuscript order
54```
56`roots` is a **list under both multiplicities**, so a delegating reader never has to
57discriminate on the shape. `parse-document-forms-with-profile` and
58`parse-document-source-with-profile` are the single-root conveniences; they raise if the
59profile actually delivered several roots.
61The three-argument `parse-document-source` / `parse-document-forms` spellings are
62unchanged and use `sigil-doc-profile`.
64## Reading a whole manuscript
66`read-language-source-with-profile` is the convenience path for a profile that keeps the
67`sigil/doc` author vocabulary and varies only the root container:
69- `'one` → the sequence `#lang sigil/doc` has always produced: prelude imports, the
70 manuscript's author forms, `(define document <root>)`, `document`.
71- `'one-or-more` → `(define document-roots (list …))` and `document-roots`, in
72 manuscript order.
74**A profile usually exists to change the author environment**, and such a language should
75call `parse-document-parts-with-profile` and assemble its own forms — its own prelude
76imports around the same roots. That is the intended shape for `#lang folio/doc`: delegate
77the complete grammar and every location here, change only the vocabulary and the roots.
79## What a profile does NOT vary
81- **Grammar-level diagnostics.** `fail-at` messages (`unexpected EOF; missing '}'`,
82 `mismatched named block terminator`, …) keep the `sigil/doc:` prefix. The grammar is
83 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 never
85 did; it reports what a manuscript declares. See `docs/passive-parse-api.md`.
86- **Anything about `@` scanning, bodies, escapes, or locations.**
88## Two shipped languages
90sigil-doc ships the base plus the genres it owns. Today that is two languages, and they
91differ **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 |
98The whole of the genre language is a profile and a two-line reader:
100```sigil
101(define-library (sigil doc book reader)
102 (import (sigil core) (sigil doc reader))
103 (export read-language-source sigil-doc-book-profile)
104 (begin
105 (define sigil-doc-book-profile
106 (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-segment
112language id needs nothing special from the reader.
114**Why `@chapter` is not a base root.** A chapter is a *part* of an assembly, and the
115assembly lives in this package too — `make-print-publication` in `(sigil doc publication)`,
116driven by a module such as `book/practical-sigil/book.sgl`. The language that hands you
117`@chapter` should be the one that owns book assembly. While `@chapter` was the base's only
118root, the base's most common root was a fragment of a workflow the base does not contain,
119and 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 is
122already import-extensible: an author command is an ordinary binding and a manuscript can
123`@(import …)` more of them. The root is different in kind — it is the document's *type*,
124the first fact a tool wants, and root policy is enforced at parse time from nothing but
125the source text. Making roots importable would either drag module resolution into the
126reader (so what a document *is* depends on installed package state, and an indexer whose
127normal case is scanning files it will reject could no longer classify one) or abolish root
128policy 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 the
132proof that a package outside sigil-doc can own a genre: it constructs its own profile,
133delegates the complete grammar to `(sigil doc reader)`, and ships its own reader module.
134sigil-doc ships `book` because Practical Sigil and print publication live here.
136## Reachable model kinds
138The semantic model has two document kinds, `article` and `chapter`, and both are now
139producible from source by a shipped language. `book` was a third; SD-P8 removed it,
140because it was constructed nowhere in this package or in folio and a book is an
141*assembly* (`make-print-publication`) rather than a document kind. `make-document` now
142refuses it by name: `kind must be article or chapter`.
144Note the boundary, which D8 fixed deliberately: root **commands** are the profile's
145vocabulary and document **kinds** are the model's. A profile may name any command symbol;
146what that command constructs is the model's business. A genre needing genuinely new
147semantics follows folio's pattern — its own records, lowered to core kinds for
148publication — rather than a new core kind.
150## `@text{}` and `@expr{}` are ordinary commands
152The parser represents prose as a five-slot `(text () value start end)` node and author
153expressions as `(expr () syntax start end)`, while a command has six slots. `@text{…}` and
154`@expr{…}` are legal author commands whose head symbol collides with those pseudo-kinds.
156Every classification in the lowering path — including this phase's root allowlist, which
157is itself a head-symbol test — now discriminates on **slot count**, which is exact. An
158author's `@text{}` is dispatched as the command it is; the parser's own prose nodes are
159never confused with it.
161The measured before/after is `test/sd-p1-classification-probe.sgl` with its two
162transcripts in `test/transcripts/sd-p1/`.