AtlatestRenderedmarkdown

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

Read the source

Readme

A section can now hold a delegating language's own nodes

sigil/doc's semantic model decided what a @section may contain with a closed list of core kinds. A language built on top of it, such as folio's #lang folio/doc, could not put its own nodes under a section at all, so a note written as a ## Tasks heading with tasks underneath had no representation. This release makes that policy a value a language supplies, with sigil/doc's own behaviour unchanged.

Changes

  • A content profile says what counts as a document node in a language and what may be a child of a section. make-content-profile and make-section-with-profile are exported from (sigil doc).
  • A profile carries witnesses: values it declares must be legal section children, and values it declares must never be. The constructor checks the predicate against both, so a containment rule that lives inside a closure is enforced rather than merely commented. Widening a profile past its own declaration makes the profile fail to construct, at the line that writes it.
  • A profile may widen the section child set and never narrow it. The core block vocabulary is a floor, so a sigil/doc document means the same thing whichever profile is installed.
  • The author runtime consults the profile as well. This is what a reader actually needed: a manuscript's @task{...} inside a @section was refused in author-normalize and never reached make-section, so a change confined to the constructor would have fixed a converter and not a reader.
  • @section reuses the ambient profile, so a delegating language keeps sigil/doc's author vocabulary instead of forking it.
  • New: docs/section-profiles.md, and a complete worked delegating language under test/sd-p7/folio/ exercised end to end through the real #lang path.

Upgrade notes

Nothing is required. make-section keeps its four-argument spelling and still checks the core block kinds directly, so existing callers, manuscripts and renderers are unaffected. #lang sigil/doc uses sigil-doc-content-profile, whose predicates are the two constants the model used before.

A language that wants its own nodes under a section builds a profile, calls make-section-with-profile, and binds the three runtime names the parser emits so its profile is installed for the manuscript's extent. docs/section-profiles.md has the whole contract.

Known limitation

A profile's declared refusals are enforced, and a profile that declares nothing about a kind is not constrained about that kind. The mechanism protects against a profile that declares something wrong, not against one that declares nothing.

A profile is deliberately NOT required to state its stance on nested structural containers. The model cannot require a stance on a concept it does not own, so the obligation belongs to the consuming language: a delegating language's own gate is where silence about its structural containers should be made impossible.

Profile inheritance is one-directional by the same reasoning. Leaving an extent restores the previous profile; entering one does not install a profile. The core block vocabulary is a floor, so any inherited ambient profile is a superset of sigil/doc's and an inner manuscript cannot construct a node its own language forbids.