AtlatestRepositorysigil-doc

sigil-doc / tree / docssection-profiles.md

Read it rendered

1# Content profiles: what a `@section` may contain
2
3`docs/root-profiles.md` describes how a delegating language names its **root**
4container. This document is the same idea one level down the tree: how a
5delegating language says what a `@section` may **contain**, and what counts as a
6document node at all.
7
8Both are needed by the same consumer. `(folio doc reader)` has `@note` and
9`@project` as roots, and folio's notes are written as a `## Tasks` heading with
10tasks underneath it — so it needs a `@section` whose children may be folio work
11items.
13## The problem this solves, measured
15Before SD-P7 there were **three** closed enumerations between a `@task` and a
16`@section`, and the first one a manuscript hits is not the one you would guess:
18| gate | where | predicate |
19| --- | --- | --- |
20| 1 | `author-normalize`, on every lowered command's result | `document-node?` |
21| 2 | `author-flatten`, on every child of a flattening container | `document-node?` |
22| 3 | `make-section` → `require-list` | `block-node?` |
24A manuscript writing `@section[…]{ @task{…} }` **never reaches `make-section`**.
25It fails in `author-normalize` with
27```
28sigil/doc author: @task must produce a document node or proper list of nodes
29```
31which names `@task` rather than `@section`, so the message does not even point
32at the container that has the policy. A repair confined to `make-section` is
33therefore enough for a converter that builds records programmatically, and not
34enough for a **reader**.
36That is why a content profile carries two predicates rather than one.
38## The value
40```scheme
41(make-content-profile name node-predicate section-child-predicate admitted refused
42 describer: <optional, see below>)
43```
45exported from `(sigil doc model)` and re-exported from `(sigil doc)`.
47- **`node-predicate`** — what counts as a document node in this language.
48 Consumed by `(sigil doc private author-runtime)`.
49- **`section-child-predicate`** — what may be a child of a section. Consumed by
50 `make-section-with-profile`.
51- **`admitted`** — a non-empty list of values the profile declares must be
52 legal section children.
53- **`refused`** — a non-empty list of values the profile declares must **never**
54 be legal section children.
56`sigil-doc-content-profile` is the default: `document-node?` and `block-node?`,
57which are the two constants the model and the author runtime used before this
58existed. `#lang sigil/doc` is unchanged.
60## Why a profile carries witnesses
62A predicate is opaque. There is no way to ask a closure what it admits, so
63there is no way to check a containment rule that lives inside one — a comment
64saying "this must never admit a milestone" is enforced by nobody.
66So a profile **declares** the values it must admit and the values it must never
67admit, and `make-content-profile` checks the predicate against both. Widening a
68profile's predicate to admit something it declared refused makes the **profile**
69fail to construct, at the line that writes it.
71`make-content-profile` refuses a profile when:
73- its `section-child-predicate` **refuses a core block node**. The core block
74 vocabulary is a floor: a profile may widen the section child set, never narrow
75 it. A profile that narrowed it would be a fork of the grammar wearing a
76 profile's clothes, and a `sigil/doc` document would mean different things
77 depending on whose profile happened to be installed. **The check samples one
78 witness per kind**, so it stops a profile dropping a whole construct and does
79 not stop one narrowing within a kind (an `aside` admitted, a `warning`
80 refused). That limit is real and is stated rather than implied.
81- it **declares a core block node refused**. The floor applies in both
82 directions; without this, a predicate discriminating by identity could honour
83 such a declaration and still pass the sampled check above.
84- any declared witness **fails the profile's own `node-predicate`**. This is
85 what stops a profile declaring a bare symbol refused — refused by every sane
86 predicate, so the refusal check would pass for free — while its predicate
87 admitted whatever it liked.
88- **either predicate admits a value that is no profile's node** — a symbol, a
89 number, a string, a boolean, the empty list, a procedure. This is the floor on
90 REFUSAL, and it is what makes the guard above worth anything: `(lambda (x) #t)`
91 satisfies "every declared witness is a node of this language" for free, so
92 without it a profile declares a junk *predicate* instead of a junk witness and
93 arrives at exactly the same place. Found by adversarial review, which is worth
94 saying: the first version of this list had the hole it describes.
95- its `section-child-predicate` **refuses a declared admitted witness**, which
96 is how a profile says it genuinely extends the child set rather than merely
97 claiming to.
98- its `section-child-predicate` **admits a declared refused witness**.
99- it declares the **same value both admitted and refused**. That already fails
100 one of the two checks above, but it is a defect in the declaration and gets a
101 message that says so instead of one blaming the predicate.
102- either witness list is **empty**, which would make every check above pass over
103 nothing.
104- either predicate **raises** rather than answering, which would turn every
105 section construction into a crash far from the profile that caused it.
107### The limit, stated
109This makes a **declared** exclusion enforceable. It cannot invent an exclusion
110nobody declared: a profile that never names structural containers can still
111admit them. What it cannot do is name them refused and admit them anyway, and
112it cannot lose the declaration without that appearing in a diff.
114## Installing a profile in a delegating language
116`(sigil doc private parser)` emits generated syntax that calls runtime
117procedures **by bare name**. Those names resolve in the manuscript's own scope,
118which the reader's prelude decides — so a delegating language installs its
119profile by binding those names to wrappers. No change to sigil-doc, and no fork
120of the paragraph-run rules.
122The parser emits three names from the **author runtime**:
124| name | emitted for | inside an `author-at`? |
125| --- | --- | --- |
126| `author-at` | every command and every root | it is the wrapper |
127| `author-normalize` | every command's result, and the hoisted `#%sigil/doc-expression:N` lambdas built for `@(…)` forms found inside a root body | yes — the hoisted lambda is only ever *called* from inside a root body |
128| `author-paragraph-run` | bare-prose runs | yes — a run is lowered as a child of the enclosing command and spliced into its `author-at` expression |
130**Wrapping `author-at` alone is therefore sufficient**, and an earlier version of
131this document said otherwise. It claimed the other two were emitted outside any
132`author-at` and had to be wrapped for that reason. That was wrong: read
133`author-expression` and `command-expression` in `private/parser.sgl` — a
134command's lowered children are spliced *into* the expression that `author-at`
135wraps. Wrapping all three is harmless defence in depth, and the worked example
136below does it, but a delegating-language author should know which one is
137load-bearing.
139**The site that genuinely has no wrapper is a different one.** A `@(…)` form at
140the manuscript's TOP LEVEL is hoisted by `parse-document-parts-with-profile` as
141raw syntax, with no `author-at`, no `author-normalize` and no profile installed.
142Nothing there can build a node anyway — `author-location` raises outside an
143`author-at` — but if that ever changes, this is the hole.
145**These three are not the only names the parser calls in manuscript scope.** It
146also emits `make-srcloc` (from every `loc-datum`), and `make-text` and
147`make-paragraph` when it lowers prose. A delegating prelude must therefore keep
148those reachable too, which importing `(sigil doc)` does. `test/gate-sd-p7.sh`
149arm 3 re-derives the author-runtime names from `parser.sgl` and fails if that set
150has moved.
152`author-flatten` is deliberately **not** in that list and must not be wrapped:
153it is called lexically from inside `(sigil doc author)`'s own commands, so a
154prelude binding could never reach it. It consults the ambient profile itself.
155That is the reason the profile is ambient rather than an extra argument —
156threading it as an argument would mean changing the syntax the parser emits,
157which would move the lowered output SD-P1 and SD-P3 pin byte for byte.
159```scheme
160(define-library (folio doc author)
161 (import (sigil core)
162 (prefix (sigil doc private author-runtime) sd:)
163 (folio doc model))
164 (export author-at author-normalize author-paragraph-run ...)
165 (begin
166 (define (author-at loc thunk)
167 (sd:with-content-profile folio-content-profile
168 (lambda () (sd:author-at loc thunk))))
169 (define (author-normalize value loc command)
170 (sd:with-content-profile folio-content-profile
171 (lambda () (sd:author-normalize value loc command))))
172 (define (author-paragraph-run values loc)
173 (sd:with-content-profile folio-content-profile
174 (lambda () (sd:author-paragraph-run values loc))))
175 ...))
176```
178and the reader's prelude imports that module **instead of**
179`(sigil doc private author-runtime)`, keeping `(sigil doc author)` whole so
180`@section`, `@p`, `@code` and the rest are reused unchanged:
182```scheme
183(make-syntax '(import (sigil doc) (sigil doc author) (folio doc author)) loc)
184```
186### Installation is one-directional, deliberately
188`with-content-profile` swaps the ambient cell in both `dynamic-wind` thunks, so
189**LEAVING** an extent restores the outer profile on every exit — a normal
190return, a raise, or a continuation re-entered later.
192**ENTERING is not symmetric, and this is the sentence to read carefully.**
193Nothing installs a profile on the way *in*. `#lang sigil/doc`'s prelude imports
194the author runtime unwrapped and relies on the module-level default, so a
195`sigil/doc` manuscript loaded by author code running inside a delegating
196language's extent **evaluates with that delegating language's profile ambient**,
197not with `sigil-doc-content-profile`.
199That is accepted rather than overlooked. Installing in the default prelude would
200add a form to the emitted sequence that `test/test-root-profile.sgl` pins, and
201the anti-narrowing floor makes any inherited ambient profile a **superset** of
202the core block vocabulary — so an inner manuscript can never be refused
203something `sigil/doc` would have allowed, and its own vocabulary cannot build
204the foreign nodes the wider profile would admit. The behaviour is pinned by an
205arm in `test/test-section-profile.sgl` so it stays deliberate.
207Reopen it if any of three things become true: manuscripts gain a
208feature that embeds another language's nodes directly, a profile is ever allowed
209to NARROW rather than only widen, or the runtime becomes multi-threaded — the
210ambient cell is module-level and two concurrent parses would observe each other
211through it.
213A worked example lives in `test/sd-p7/folio/`: a complete delegating language in
214three small modules, exercised end to end by
215`test/fixtures/sd-p7-folio-note.sgd` through the real `#lang` path.
217## Constructing sections directly
219A converter that builds records without a manuscript does not go near the author
220runtime and needs only the constructor:
222```scheme
223(make-section-with-profile folio-content-profile id title children loc)
224```
226The four-argument `make-section` is unchanged and still checks `block-node?`
227directly — it does not consult the default profile, so its behaviour does not
228depend on any profile having been built correctly.
230## What is *not* parameterized
232`make-document`, `make-admonition`, `make-exercise`, `make-list-item` and
233`make-table-cell` still check `block-node?`. Only the section-child predicate
234was ruled on, and a container that quietly accepted a wider set than anyone
235asked for is exactly where a laundering route would hide.
237## Naming and locating a refusal: the describer
239`make-content-profile` takes an optional `describer:` keyword. It is called
240**only** when a child has already been refused, receives **only** that child,
241and returns the text of the diagnostic.
243```scheme
244(make-content-profile "folio/doc" folio-node? folio-section-child?
245 admitted refused
246 describer: folio-describe-refusal)
247```
249A profile without one gets `child belongs to the wrong semantic category`,
250unlocated, byte-identical to what `make-section` has always raised. That is what
251keeps `sigil/doc` untouched, and it has its own gate arm asserting both halves:
252the exact wording, and the *absence* of a location.
254### Why the describer, and not the model, does the locating
256You would expect the model to point at the offending child itself. It cannot,
257for foreign nodes, and foreign nodes are the whole point:
259**`node-location` is a closed enumeration over the core kinds and raises on
260anything else** — the same shape as the `block-node?` enumeration that made this
261parameter necessary, one layer down. So the core model can locate a paragraph
262and cannot locate a milestone, and a milestone is exactly what a laundering
263attempt smuggles into a section.
265The delegating language can locate its own nodes, so the describer is the only
266place where the offending child's position is both knowable and expressible. It
267therefore returns the *complete* wording, location included, and the model
268contributes no location of its own.
270Opening `node-location` would mean the core model learning to locate vocabulary
271it does not own — the same error as making it name folio's classes — so SD-P7
272deliberately did not.
274### What a describer may not do
276It cannot decide acceptance. By the time it runs the refusal is already
277determined; it never sees the predicate, the accepted children, or the verdict,
278and there is no path by which its return value reaches the decision. A describer
279that raises, or returns a non-string, gets the model's own fixed wording rather
280than being allowed to produce nothing.
282Keep it that way. A user-supplied *string* inside the trust boundary is a very
283different thing from a user-supplied *callback*.