AtlatestRepositorysigil-doc

sigil-doc / tree / docsv0.1.3-tag-message.md

Read it rendered

1A section can now hold a delegating language's own nodes
2
3`sigil/doc`'s semantic model decided what a `@section` may contain with a closed
4list of core kinds. A language built on top of it, such as folio's `#lang
5folio/doc`, could not put its own nodes under a section at all, so a note
6written as a `## Tasks` heading with tasks underneath had no representation.
7This release makes that policy a value a language supplies, with `sigil/doc`'s
8own behaviour unchanged.
9
10## Changes
12- A **content profile** says what counts as a document node in a language and
13 what may be a child of a section. `make-content-profile` and
14 `make-section-with-profile` are exported from `(sigil doc)`.
15- A profile carries **witnesses**: values it declares must be legal section
16 children, and values it declares must never be. The constructor checks the
17 predicate against both, so a containment rule that lives inside a closure is
18 enforced rather than merely commented. Widening a profile past its own
19 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 core
21 block vocabulary is a floor, so a `sigil/doc` document means the same thing
22 whichever profile is installed.
23- The author runtime consults the profile as well. This is what a reader
24 actually needed: a manuscript's `@task{...}` inside a `@section` was refused
25 in `author-normalize` and never reached `make-section`, so a change confined
26 to the constructor would have fixed a converter and not a reader.
27- `@section` reuses the ambient profile, so a delegating language keeps
28 `sigil/doc`'s author vocabulary instead of forking it.
29- New: `docs/section-profiles.md`, and a complete worked delegating language
30 under `test/sd-p7/folio/` exercised end to end through the real `#lang` path.
32## Upgrade notes
34Nothing is required. `make-section` keeps its four-argument spelling and still
35checks the core block kinds directly, so existing callers, manuscripts and
36renderers are unaffected. `#lang sigil/doc` uses `sigil-doc-content-profile`,
37whose predicates are the two constants the model used before.
39A language that wants its own nodes under a section builds a profile, calls
40`make-section-with-profile`, and binds the three runtime names the parser emits
41so its profile is installed for the manuscript's extent.
42`docs/section-profiles.md` has the whole contract.
44## Known limitation
46A profile's declared refusals are enforced, and a profile that declares nothing
47about a kind is not constrained about that kind. The mechanism protects against
48a profile that declares something wrong, not against one that declares nothing.
50A profile is deliberately NOT required to state its stance on nested structural
51containers. The model cannot require a stance on a concept it does not own, so
52the obligation belongs to the consuming language: a delegating language's own
53gate is where silence about its structural containers should be made impossible.
55Profile inheritance is one-directional by the same reasoning. Leaving an extent
56restores the previous profile; entering one does not install a profile. The core
57block vocabulary is a floor, so any inherited ambient profile is a superset of
58`sigil/doc`'s and an inner manuscript cannot construct a node its own language
59forbids.