AtlatestRepositorysigil-doc
1
# Content profiles: what a `@section` may contain3
`docs/root-profiles.md` describes how a delegating language names its **root**4
container. This document is the same idea one level down the tree: how a5
delegating language says what a `@section` may **contain**, and what counts as a6
document node at all.8
Both are needed by the same consumer. `(folio doc reader)` has `@note` and9
`@project` as roots, and folio's notes are written as a `## Tasks` heading with10
tasks underneath it — so it needs a `@section` whose children may be folio work11
items.13
## The problem this solves, measured15
Before SD-P7 there were **three** closed enumerations between a `@task` and a16
`@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?` |24
A manuscript writing `@section[…]{ @task{…} }` **never reaches `make-section`**.25
It fails in `author-normalize` with27
```28
sigil/doc author: @task must produce a document node or proper list of nodes29
```31
which names `@task` rather than `@section`, so the message does not even point32
at the container that has the policy. A repair confined to `make-section` is33
therefore enough for a converter that builds records programmatically, and not34
enough for a **reader**.36
That is why a content profile carries two predicates rather than one.38
## The value40
```scheme41
(make-content-profile name node-predicate section-child-predicate admitted refused42
describer: <optional, see below>)43
```45
exported 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 by50
`make-section-with-profile`.51
- **`admitted`** — a non-empty list of values the profile declares must be52
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?`,57
which are the two constants the model and the author runtime used before this58
existed. `#lang sigil/doc` is unchanged.60
## Why a profile carries witnesses62
A predicate is opaque. There is no way to ask a closure what it admits, so63
there is no way to check a containment rule that lives inside one — a comment64
saying "this must never admit a milestone" is enforced by nobody.66
So a profile **declares** the values it must admit and the values it must never67
admit, and `make-content-profile` checks the predicate against both. Widening a68
profile's predicate to admit something it declared refused makes the **profile**69
fail 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 block74
vocabulary is a floor: a profile may widen the section child set, never narrow75
it. A profile that narrowed it would be a fork of the grammar wearing a76
profile's clothes, and a `sigil/doc` document would mean different things77
depending on whose profile happened to be installed. **The check samples one78
witness per kind**, so it stops a profile dropping a whole construct and does79
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 both82
directions; without this, a predicate discriminating by identity could honour83
such a declaration and still pass the sampled check above.84
- any declared witness **fails the profile's own `node-predicate`**. This is85
what stops a profile declaring a bare symbol refused — refused by every sane86
predicate, so the refusal check would pass for free — while its predicate87
admitted whatever it liked.88
- **either predicate admits a value that is no profile's node** — a symbol, a89
number, a string, a boolean, the empty list, a procedure. This is the floor on90
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, so92
without it a profile declares a junk *predicate* instead of a junk witness and93
arrives at exactly the same place. Found by adversarial review, which is worth94
saying: the first version of this list had the hole it describes.95
- its `section-child-predicate` **refuses a declared admitted witness**, which96
is how a profile says it genuinely extends the child set rather than merely97
claiming to.98
- its `section-child-predicate` **admits a declared refused witness**.99
- it declares the **same value both admitted and refused**. That already fails100
one of the two checks above, but it is a defect in the declaration and gets a101
message that says so instead of one blaming the predicate.102
- either witness list is **empty**, which would make every check above pass over103
nothing.104
- either predicate **raises** rather than answering, which would turn every105
section construction into a crash far from the profile that caused it.107
### The limit, stated109
This makes a **declared** exclusion enforceable. It cannot invent an exclusion110
nobody declared: a profile that never names structural containers can still111
admit them. What it cannot do is name them refused and admit them anyway, and112
it cannot lose the declaration without that appearing in a diff.114
## Installing a profile in a delegating language116
`(sigil doc private parser)` emits generated syntax that calls runtime117
procedures **by bare name**. Those names resolve in the manuscript's own scope,118
which the reader's prelude decides — so a delegating language installs its119
profile by binding those names to wrappers. No change to sigil-doc, and no fork120
of the paragraph-run rules.122
The 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 of131
this document said otherwise. It claimed the other two were emitted outside any132
`author-at` and had to be wrapped for that reason. That was wrong: read133
`author-expression` and `command-expression` in `private/parser.sgl` — a134
command's lowered children are spliced *into* the expression that `author-at`135
wraps. Wrapping all three is harmless defence in depth, and the worked example136
below does it, but a delegating-language author should know which one is137
load-bearing.139
**The site that genuinely has no wrapper is a different one.** A `@(…)` form at140
the manuscript's TOP LEVEL is hoisted by `parse-document-parts-with-profile` as141
raw syntax, with no `author-at`, no `author-normalize` and no profile installed.142
Nothing there can build a node anyway — `author-location` raises outside an143
`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.** It146
also emits `make-srcloc` (from every `loc-datum`), and `make-text` and147
`make-paragraph` when it lowers prose. A delegating prelude must therefore keep148
those reachable too, which importing `(sigil doc)` does. `test/gate-sd-p7.sh`149
arm 3 re-derives the author-runtime names from `parser.sgl` and fails if that set150
has moved.152
`author-flatten` is deliberately **not** in that list and must not be wrapped:153
it is called lexically from inside `(sigil doc author)`'s own commands, so a154
prelude binding could never reach it. It consults the ambient profile itself.155
That is the reason the profile is ambient rather than an extra argument —156
threading it as an argument would mean changing the syntax the parser emits,157
which would move the lowered output SD-P1 and SD-P3 pin byte for byte.159
```scheme160
(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
(begin166
(define (author-at loc thunk)167
(sd:with-content-profile folio-content-profile168
(lambda () (sd:author-at loc thunk))))169
(define (author-normalize value loc command)170
(sd:with-content-profile folio-content-profile171
(lambda () (sd:author-normalize value loc command))))172
(define (author-paragraph-run values loc)173
(sd:with-content-profile folio-content-profile174
(lambda () (sd:author-paragraph-run values loc))))175
...))176
```178
and the reader's prelude imports that module **instead of**179
`(sigil doc private author-runtime)`, keeping `(sigil doc author)` whole so180
`@section`, `@p`, `@code` and the rest are reused unchanged:182
```scheme183
(make-syntax '(import (sigil doc) (sigil doc author) (folio doc author)) loc)184
```186
### Installation is one-directional, deliberately188
`with-content-profile` swaps the ambient cell in both `dynamic-wind` thunks, so189
**LEAVING** an extent restores the outer profile on every exit — a normal190
return, a raise, or a continuation re-entered later.192
**ENTERING is not symmetric, and this is the sentence to read carefully.**193
Nothing installs a profile on the way *in*. `#lang sigil/doc`'s prelude imports194
the author runtime unwrapped and relies on the module-level default, so a195
`sigil/doc` manuscript loaded by author code running inside a delegating196
language's extent **evaluates with that delegating language's profile ambient**,197
not with `sigil-doc-content-profile`.199
That is accepted rather than overlooked. Installing in the default prelude would200
add a form to the emitted sequence that `test/test-root-profile.sgl` pins, and201
the anti-narrowing floor makes any inherited ambient profile a **superset** of202
the core block vocabulary — so an inner manuscript can never be refused203
something `sigil/doc` would have allowed, and its own vocabulary cannot build204
the foreign nodes the wider profile would admit. The behaviour is pinned by an205
arm in `test/test-section-profile.sgl` so it stays deliberate.207
Reopen it if any of three things become true: manuscripts gain a208
feature that embeds another language's nodes directly, a profile is ever allowed209
to NARROW rather than only widen, or the runtime becomes multi-threaded — the210
ambient cell is module-level and two concurrent parses would observe each other211
through it.213
A worked example lives in `test/sd-p7/folio/`: a complete delegating language in214
three small modules, exercised end to end by215
`test/fixtures/sd-p7-folio-note.sgd` through the real `#lang` path.217
## Constructing sections directly219
A converter that builds records without a manuscript does not go near the author220
runtime and needs only the constructor:222
```scheme223
(make-section-with-profile folio-content-profile id title children loc)224
```226
The four-argument `make-section` is unchanged and still checks `block-node?`227
directly — it does not consult the default profile, so its behaviour does not228
depend on any profile having been built correctly.230
## What is *not* parameterized232
`make-document`, `make-admonition`, `make-exercise`, `make-list-item` and233
`make-table-cell` still check `block-node?`. Only the section-child predicate234
was ruled on, and a container that quietly accepted a wider set than anyone235
asked for is exactly where a laundering route would hide.237
## Naming and locating a refusal: the describer239
`make-content-profile` takes an optional `describer:` keyword. It is called240
**only** when a child has already been refused, receives **only** that child,241
and returns the text of the diagnostic.243
```scheme244
(make-content-profile "folio/doc" folio-node? folio-section-child?245
admitted refused246
describer: folio-describe-refusal)247
```249
A profile without one gets `child belongs to the wrong semantic category`,250
unlocated, byte-identical to what `make-section` has always raised. That is what251
keeps `sigil/doc` untouched, and it has its own gate arm asserting both halves:252
the exact wording, and the *absence* of a location.254
### Why the describer, and not the model, does the locating256
You would expect the model to point at the offending child itself. It cannot,257
for foreign nodes, and foreign nodes are the whole point:259
**`node-location` is a closed enumeration over the core kinds and raises on260
anything else** — the same shape as the `block-node?` enumeration that made this261
parameter necessary, one layer down. So the core model can locate a paragraph262
and cannot locate a milestone, and a milestone is exactly what a laundering263
attempt smuggles into a section.265
The delegating language can locate its own nodes, so the describer is the only266
place where the offending child's position is both knowable and expressible. It267
therefore returns the *complete* wording, location included, and the model268
contributes no location of its own.270
Opening `node-location` would mean the core model learning to locate vocabulary271
it does not own — the same error as making it name folio's classes — so SD-P7272
deliberately did not.274
### What a describer may not do276
It cannot decide acceptance. By the time it runs the refusal is already277
determined; it never sees the predicate, the accepted children, or the verdict,278
and there is no path by which its return value reaches the decision. A describer279
that raises, or returns a non-string, gets the model's own fixed wording rather280
than being allowed to produce nothing.282
Keep it that way. A user-supplied *string* inside the trust boundary is a very283
different thing from a user-supplied *callback*.