Atv0.2.1Repositorysigil-doc

docs/section-profiles.md

Release v0.2.1 · Default-branch version

Document

Content profiles: what a @section may contain

docs/root-profiles.md describes how a delegating language names its root container. This document is the same idea one level down the tree: how a delegating language says what a @section may contain, and what counts as a document node at all.

Both are needed by the same consumer. (folio doc reader) has @note and @project as roots, and folio's notes are written as a ## Tasks heading with tasks underneath it — so it needs a @section whose children may be folio work items.

The problem this solves, measured

Before SD-P7 there were three closed enumerations between a @task and a @section, and the first one a manuscript hits is not the one you would guess:

gatewherepredicate
1author-normalize, on every lowered command's resultdocument-node?
2author-flatten, on every child of a flattening containerdocument-node?
3make-section → require-listblock-node?

A manuscript writing @section[…]{ @task{…} } never reaches make-section. It fails in author-normalize with

sigil/doc author: @task must produce a document node or proper list of nodes

which names @task rather than @section, so the message does not even point at the container that has the policy. A repair confined to make-section is therefore enough for a converter that builds records programmatically, and not enough for a reader.

That is why a content profile carries two predicates rather than one.

The value

(make-content-profile name node-predicate section-child-predicate admitted refused
                      describer: <optional, see below>)

exported from (sigil doc model) and re-exported from (sigil doc).

  • node-predicate — what counts as a document node in this language. Consumed by (sigil doc private author-runtime).
  • section-child-predicate — what may be a child of a section. Consumed by make-section-with-profile.
  • admitted — a non-empty list of values the profile declares must be legal section children.
  • refused — a non-empty list of values the profile declares must never be legal section children.

sigil-doc-content-profile is the default: document-node? and block-node?, which are the two constants the model and the author runtime used before this existed. #lang sigil/doc is unchanged.

Why a profile carries witnesses

A predicate is opaque. There is no way to ask a closure what it admits, so there is no way to check a containment rule that lives inside one — a comment saying "this must never admit a milestone" is enforced by nobody.

So a profile declares the values it must admit and the values it must never admit, and make-content-profile checks the predicate against both. Widening a profile's predicate to admit something it declared refused makes the profile fail to construct, at the line that writes it.

make-content-profile refuses a profile when:

  • its section-child-predicate refuses a core block node. The core block vocabulary is a floor: a profile may widen the section child set, never narrow it. A profile that narrowed it would be a fork of the grammar wearing a profile's clothes, and a sigil/doc document would mean different things depending on whose profile happened to be installed. The check samples one witness per kind, so it stops a profile dropping a whole construct and does not stop one narrowing within a kind (an aside admitted, a warning refused). That limit is real and is stated rather than implied.
  • it declares a core block node refused. The floor applies in both directions; without this, a predicate discriminating by identity could honour such a declaration and still pass the sampled check above.
  • any declared witness fails the profile's own node-predicate. This is what stops a profile declaring a bare symbol refused — refused by every sane predicate, so the refusal check would pass for free — while its predicate admitted whatever it liked.
  • either predicate admits a value that is no profile's node — a symbol, a number, a string, a boolean, the empty list, a procedure. This is the floor on REFUSAL, and it is what makes the guard above worth anything: (lambda (x) #t) satisfies "every declared witness is a node of this language" for free, so without it a profile declares a junk predicate instead of a junk witness and arrives at exactly the same place. Found by adversarial review, which is worth saying: the first version of this list had the hole it describes.
  • its section-child-predicate refuses a declared admitted witness, which is how a profile says it genuinely extends the child set rather than merely claiming to.
  • its section-child-predicate admits a declared refused witness.
  • it declares the same value both admitted and refused. That already fails one of the two checks above, but it is a defect in the declaration and gets a message that says so instead of one blaming the predicate.
  • either witness list is empty, which would make every check above pass over nothing.
  • either predicate raises rather than answering, which would turn every section construction into a crash far from the profile that caused it.

The limit, stated

This makes a declared exclusion enforceable. It cannot invent an exclusion nobody declared: a profile that never names structural containers can still admit them. What it cannot do is name them refused and admit them anyway, and it cannot lose the declaration without that appearing in a diff.

Installing a profile in a delegating language

(sigil doc private parser) emits generated syntax that calls runtime procedures by bare name. Those names resolve in the manuscript's own scope, which the reader's prelude decides — so a delegating language installs its profile by binding those names to wrappers. No change to sigil-doc, and no fork of the paragraph-run rules.

The parser emits three names from the author runtime:

nameemitted forinside an author-at?
author-atevery command and every rootit is the wrapper
author-normalizeevery command's result, and the hoisted #%sigil/doc-expression:N lambdas built for @(…) forms found inside a root bodyyes — the hoisted lambda is only ever called from inside a root body
author-paragraph-runbare-prose runsyes — a run is lowered as a child of the enclosing command and spliced into its author-at expression

Wrapping author-at alone is therefore sufficient, and an earlier version of this document said otherwise. It claimed the other two were emitted outside any author-at and had to be wrapped for that reason. That was wrong: read author-expression and command-expression in private/parser.sgl — a command's lowered children are spliced into the expression that author-at wraps. Wrapping all three is harmless defence in depth, and the worked example below does it, but a delegating-language author should know which one is load-bearing.

The site that genuinely has no wrapper is a different one. A @(…) form at the manuscript's TOP LEVEL is hoisted by parse-document-parts-with-profile as raw syntax, with no author-at, no author-normalize and no profile installed. Nothing there can build a node anyway — author-location raises outside an author-at — but if that ever changes, this is the hole.

These three are not the only names the parser calls in manuscript scope. It also emits make-srcloc (from every loc-datum), and make-text and make-paragraph when it lowers prose. A delegating prelude must therefore keep those reachable too, which importing (sigil doc) does. test/gate-sd-p7.sh arm 3 re-derives the author-runtime names from parser.sgl and fails if that set has moved.

author-flatten is deliberately not in that list and must not be wrapped: it is called lexically from inside (sigil doc author)'s own commands, so a prelude binding could never reach it. It consults the ambient profile itself. That is the reason the profile is ambient rather than an extra argument — threading it as an argument would mean changing the syntax the parser emits, which would move the lowered output SD-P1 and SD-P3 pin byte for byte.

(define-library (folio doc author)
  (import (sigil core)
          (prefix (sigil doc private author-runtime) sd:)
          (folio doc model))
  (export author-at author-normalize author-paragraph-run ...)
  (begin
    (define (author-at loc thunk)
      (sd:with-content-profile folio-content-profile
        (lambda () (sd:author-at loc thunk))))
    (define (author-normalize value loc command)
      (sd:with-content-profile folio-content-profile
        (lambda () (sd:author-normalize value loc command))))
    (define (author-paragraph-run values loc)
      (sd:with-content-profile folio-content-profile
        (lambda () (sd:author-paragraph-run values loc))))
    ...))

and the reader's prelude imports that module instead of (sigil doc private author-runtime), keeping (sigil doc author) whole so @section, @p, @code and the rest are reused unchanged:

(make-syntax '(import (sigil doc) (sigil doc author) (folio doc author)) loc)

Installation is one-directional, deliberately

with-content-profile swaps the ambient cell in both dynamic-wind thunks, so LEAVING an extent restores the outer profile on every exit — a normal return, a raise, or a continuation re-entered later.

ENTERING is not symmetric, and this is the sentence to read carefully. Nothing installs a profile on the way in. #lang sigil/doc's prelude imports the author runtime unwrapped and relies on the module-level default, so a sigil/doc manuscript loaded by author code running inside a delegating language's extent evaluates with that delegating language's profile ambient, not with sigil-doc-content-profile.

That is accepted rather than overlooked. Installing in the default prelude would add a form to the emitted sequence that test/test-root-profile.sgl pins, and the anti-narrowing floor makes any inherited ambient profile a superset of the core block vocabulary — so an inner manuscript can never be refused something sigil/doc would have allowed, and its own vocabulary cannot build the foreign nodes the wider profile would admit. The behaviour is pinned by an arm in test/test-section-profile.sgl so it stays deliberate.

Reopen it if any of three things become true: manuscripts gain a feature that embeds another language's nodes directly, a profile is ever allowed to NARROW rather than only widen, or the runtime becomes multi-threaded — the ambient cell is module-level and two concurrent parses would observe each other through it.

A worked example lives in test/sd-p7/folio/: a complete delegating language in three small modules, exercised end to end by test/fixtures/sd-p7-folio-note.sgd through the real #lang path.

Constructing sections directly

A converter that builds records without a manuscript does not go near the author runtime and needs only the constructor:

(make-section-with-profile folio-content-profile id title children loc)

The four-argument make-section is unchanged and still checks block-node? directly — it does not consult the default profile, so its behaviour does not depend on any profile having been built correctly.

What is not parameterized

make-document, make-admonition, make-exercise, make-list-item and make-table-cell still check block-node?. Only the section-child predicate was ruled on, and a container that quietly accepted a wider set than anyone asked for is exactly where a laundering route would hide.

Naming and locating a refusal: the describer

make-content-profile takes an optional describer: keyword. It is called only when a child has already been refused, receives only that child, and returns the text of the diagnostic.

(make-content-profile "folio/doc" folio-node? folio-section-child?
                      admitted refused
                      describer: folio-describe-refusal)

A profile without one gets child belongs to the wrong semantic category, unlocated, byte-identical to what make-section has always raised. That is what keeps sigil/doc untouched, and it has its own gate arm asserting both halves: the exact wording, and the absence of a location.

Why the describer, and not the model, does the locating

You would expect the model to point at the offending child itself. It cannot, for foreign nodes, and foreign nodes are the whole point:

node-location is a closed enumeration over the core kinds and raises on anything else — the same shape as the block-node? enumeration that made this parameter necessary, one layer down. So the core model can locate a paragraph and cannot locate a milestone, and a milestone is exactly what a laundering attempt smuggles into a section.

The delegating language can locate its own nodes, so the describer is the only place where the offending child's position is both knowable and expressible. It therefore returns the complete wording, location included, and the model contributes no location of its own.

Opening node-location would mean the core model learning to locate vocabulary it does not own — the same error as making it name folio's classes — so SD-P7 deliberately did not.

What a describer may not do

It cannot decide acceptance. By the time it runs the refusal is already determined; it never sees the predicate, the accepted children, or the verdict, and there is no path by which its return value reaches the decision. A describer that raises, or returns a non-string, gets the model's own fixed wording rather than being allowed to produce nothing.

Keep it that way. A user-supplied string inside the trust boundary is a very different thing from a user-supplied callback.