AtlatestRepositorysigil-doc
1
A section can now hold a delegating language's own nodes3
`sigil/doc`'s semantic model decided what a `@section` may contain with a closed4
list of core kinds. A language built on top of it, such as folio's `#lang5
folio/doc`, could not put its own nodes under a section at all, so a note6
written as a `## Tasks` heading with tasks underneath had no representation.7
This release makes that policy a value a language supplies, with `sigil/doc`'s8
own behaviour unchanged.10
## Changes12
- A **content profile** says what counts as a document node in a language and13
what may be a child of a section. `make-content-profile` and14
`make-section-with-profile` are exported from `(sigil doc)`.15
- A profile carries **witnesses**: values it declares must be legal section16
children, and values it declares must never be. The constructor checks the17
predicate against both, so a containment rule that lives inside a closure is18
enforced rather than merely commented. Widening a profile past its own19
declaration makes the profile fail to construct, at the line that writes it.20
- A profile may **widen** the section child set and never narrow it. The core21
block vocabulary is a floor, so a `sigil/doc` document means the same thing22
whichever profile is installed.23
- The author runtime consults the profile as well. This is what a reader24
actually needed: a manuscript's `@task{...}` inside a `@section` was refused25
in `author-normalize` and never reached `make-section`, so a change confined26
to the constructor would have fixed a converter and not a reader.27
- `@section` reuses the ambient profile, so a delegating language keeps28
`sigil/doc`'s author vocabulary instead of forking it.29
- New: `docs/section-profiles.md`, and a complete worked delegating language30
under `test/sd-p7/folio/` exercised end to end through the real `#lang` path.32
## Upgrade notes34
Nothing is required. `make-section` keeps its four-argument spelling and still35
checks the core block kinds directly, so existing callers, manuscripts and36
renderers are unaffected. `#lang sigil/doc` uses `sigil-doc-content-profile`,37
whose predicates are the two constants the model used before.39
A language that wants its own nodes under a section builds a profile, calls40
`make-section-with-profile`, and binds the three runtime names the parser emits41
so its profile is installed for the manuscript's extent.42
`docs/section-profiles.md` has the whole contract.44
## Known limitation46
A profile's declared refusals are enforced, and a profile that declares nothing47
about a kind is not constrained about that kind. The mechanism protects against48
a profile that declares something wrong, not against one that declares nothing.50
A profile is deliberately NOT required to state its stance on nested structural51
containers. The model cannot require a stance on a concept it does not own, so52
the obligation belongs to the consuming language: a delegating language's own53
gate is where silence about its structural containers should be made impossible.55
Profile inheritance is one-directional by the same reasoning. Leaving an extent56
restores the previous profile; entering one does not install a profile. The core57
block vocabulary is a floor, so any inherited ambient profile is a superset of58
`sigil/doc`'s and an inner manuscript cannot construct a node its own language59
forbids.