AtlatestRenderedmarkdown

sigil-doc / tree / docsroot-profiles.md

Read the source

Readme

Root profiles — parameterizing the root container

#lang sigil/doc used to hardcode "exactly one @chapter" as the only legal document root. SD-P1 makes the root-command set and its multiplicity a parameter of the reader, so a delegating language can deliver its own roots without forking the grammar.

SD-P8 then used that parameter on sigil/doc itself (ruling D8, 2026-08-22): the base language is generic and genres are languages. #lang sigil/doc admits exactly one @article; @chapter moved to the sibling genre language #lang sigil/doc/book. See Two shipped languages below.

The two root-policy diagnostics are DERIVED from the profile, so a language's messages follow its root set with no second copy to keep in step. SD-P8 is the first change to exercise that: moving the base root set reworded both of its messages without touching the formatter.

What a profile is

(import (sigil doc reader))

(define folio-profile (make-document-profile "folio/doc" '(note project) 'one-or-more))
fieldmeaning
nameprefixes the two root-policy diagnostics, so a delegating profile reports folio/doc: where the policy genuinely differs
rootsnon-empty list of distinct command-name symbols legal at top level
multiplicity'one or 'one-or-more

The built-in sigil-doc-profile is ("sigil/doc" (article) one), and the genre profile sigil-doc-book-profile in (sigil doc book reader) is ("sigil/doc/book" (chapter) one).

Everything is validated at construction, not at parse time: an empty root set, a non-symbol root, a duplicate root, an unknown multiplicity, or an empty name all raise immediately. A profile admitting no root would otherwise reject every document with a message naming no command — an always-red gate wearing a manuscript error's clothes.

A profile is immutable and owns its aggregates. document-profile-roots hands back a copy, and mutating the list you passed to the constructor cannot widen a profile afterwards.

'zero-or-more is deliberately absent. It would legalise a rootless document and so retire the diagnostic that catches an empty or truncated file. The vocabulary is closed because widening one later is cheap and narrowing one is not.

Parsing with a profile

(define parts (parse-document-parts-with-profile profile source source-name header-end))
(define author-forms (car parts))   ; top-level @(...) forms, in manuscript order
(define roots (cadr parts))         ; lowered root syntax, in manuscript order

roots is a list under both multiplicities, so a delegating reader never has to discriminate on the shape. parse-document-forms-with-profile and parse-document-source-with-profile are the single-root conveniences; they raise if the profile actually delivered several roots.

The three-argument parse-document-source / parse-document-forms spellings are unchanged and use sigil-doc-profile.

Reading a whole manuscript

read-language-source-with-profile is the convenience path for a profile that keeps the sigil/doc author vocabulary and varies only the root container:

  • 'one → the sequence #lang sigil/doc has always produced: prelude imports, the manuscript's author forms, (define document <root>), document.
  • 'one-or-more → (define document-roots (list …)) and document-roots, in manuscript order.

A profile usually exists to change the author environment, and such a language should call parse-document-parts-with-profile and assemble its own forms — its own prelude imports around the same roots. That is the intended shape for #lang folio/doc: delegate the complete grammar and every location here, change only the vocabulary and the roots.

What a profile does NOT vary

  • Grammar-level diagnostics. fail-at messages (unexpected EOF; missing '}', mismatched named block terminator, …) keep the sigil/doc: prefix. The grammar is precisely what a profile must not fork, and D1/D2 pin those exact strings.
  • The passive surface. (sigil doc inspect) enforces no root policy at all and never did; it reports what a manuscript declares. See docs/passive-parse-api.md.
  • Anything about @ scanning, bodies, escapes, or locations.

Two shipped languages

sigil-doc ships the base plus the genres it owns. Today that is two languages, and they differ only in their root profile.

#langmoduleroot setmultiplicitywhat it is for
sigil/doc(sigil doc reader)(article)onethe generic standalone document — README, design doc, spec, memo, blog post
sigil/doc/book(sigil doc book reader)(chapter)onethe book/print genre; one manuscript is one chapter

The whole of the genre language is a profile and a two-line reader:

(define-library (sigil doc book reader)
  (import (sigil core) (sigil doc reader))
  (export read-language-source sigil-doc-book-profile)
  (begin
    (define sigil-doc-book-profile
      (make-document-profile "sigil/doc/book" '(chapter) 'one))
    (define (read-language-source source context)
      (read-language-source-with-profile sigil-doc-book-profile source context))))

#lang a/b/c resolves to the module (a b c reader), which is why a multi-segment language id needs nothing special from the reader.

Why @chapter is not a base root. A chapter is a part of an assembly, and the assembly lives in this package too — make-print-publication in (sigil doc publication), driven by a module such as book/practical-sigil/book.sgl. The language that hands you @chapter should be the one that owns book assembly. While @chapter was the base's only root, the base's most common root was a fragment of a workflow the base does not contain, and every standalone document had to call itself a chapter.

Why the root comes from #lang and not from an import. Everything below the root is already import-extensible: an author command is an ordinary binding and a manuscript can @(import …) more of them. The root is different in kind — it is the document's type, the first fact a tool wants, and root policy is enforced at parse time from nothing but the source text. Making roots importable would either drag module resolution into the reader (so what a document is depends on installed package state, and an indexer whose normal case is scanning files it will reject could no longer classify one) or abolish root policy altogether, retiring the diagnostic that catches an empty or truncated file. So: imports extend what a document can say; the #lang line declares what a document is.

Where a new genre goes. With its product owner, not here. #lang folio/doc is the proof that a package outside sigil-doc can own a genre: it constructs its own profile, delegates the complete grammar to (sigil doc reader), and ships its own reader module. sigil-doc ships book because Practical Sigil and print publication live here.

Reachable model kinds

The semantic model has two document kinds, article and chapter, and both are now producible from source by a shipped language. book was a third; SD-P8 removed it, because it was constructed nowhere in this package or in folio and a book is an assembly (make-print-publication) rather than a document kind. make-document now refuses it by name: kind must be article or chapter.

Note the boundary, which D8 fixed deliberately: root commands are the profile's vocabulary and document kinds are the model's. A profile may name any command symbol; what that command constructs is the model's business. A genre needing genuinely new semantics follows folio's pattern — its own records, lowered to core kinds for publication — rather than a new core kind.

@text{} and @expr{} are ordinary commands

The parser represents prose as a five-slot (text () value start end) node and author expressions as (expr () syntax start end), while a command has six slots. @text{…} and @expr{…} are legal author commands whose head symbol collides with those pseudo-kinds.

Every classification in the lowering path — including this phase's root allowlist, which is itself a head-symbol test — now discriminates on slot count, which is exact. An author's @text{} is dispatched as the command it is; the parser's own prose nodes are never confused with it.

The measured before/after is test/sd-p1-classification-probe.sgl with its two transcripts in test/transcripts/sd-p1/.