sigil-doc
sigil-doc is Sigil's programmable document language. A document is an ordinary Sigil program with a prose-oriented reader:
#lang sigil/doc
@(define-syntax strong
(syntax-rules () ((_ child) (em child))))
@article ["A Small Document" "An Author"]
@section ["First Section"]
@p: Prose can contain @strong{ordinary author macros}.
@end section
@end articleCommands are ordinary imported or manuscript-local bindings. Everything in [...] is read and evaluated as standard Sigil, including multiline forms, keywords, macros, and computed values. Top-level @(...) forms can import modules or define functions and macros; @(...) inside a document computes a node or proper list of nodes at that position.
Every command supports the same body notations:
@name[...] { ... } balanced body
@name[...] named multiline body
...
@end name
@name[...]: ... remainder of the physical line
@name[...] {} explicit empty bodyHorizontal whitespace around arguments and braces is cosmetic, indentation is never semantic, and whitespace immediately inside a body is delimiter padding. Inline commands use braces; named and line bodies are available only at a block boundary. @code{identifier} is inline code; @code["sigil"]{...} is a language-labelled block, and @code[#f]{...} is an unlabelled block. Named and colon @code bodies are also blocks. Subject source inside these forms is data and is not executed during document authoring.
Executable examples, their expectations and hidden checks are described in `docs/examples.md`.
Evaluation binds the resulting semantic value as document. The package includes backend-neutral model/traversal/publication modules, static HTML fragments, and a backend-neutral print adapter with a Typst source backend. Press consumes the HTML fragments for sites; sigil-doc invokes an existing typesetter for PDF rather than implementing typography or pagination.
Build the current two-chapter Practical Sigil print edition with:
guix shell typst poppler -- \
tools/build-practical-sigil-pdf.sh build/practical-sigil.pdfThe .typ source is retained beside the deterministic, tagged PDF. See `docs/print-backend.md` for the backend decision, reproducibility contract, font strategy, and long-code wrapping rule.
Print customization is ordinary checked-in Sigil code. The publication policy in (sigil doc print) controls numbering, chapter authors, contents, chapter starts, and running-header content. The immutable typst-theme in (sigil doc render typst) controls paper, margins, fonts, typography, colors, code treatment, headers, and page-number placement. Practical Sigil keeps these decisions in book/practical-sigil/book.sgl and theme.sgl, separate from its semantic .sgd chapters. The default edition remains byte-compatible with D6; the same configuration also demonstrates a distinct A5 compact-study edition.
A distinct @pre form for non-code preformatted material is intentionally deferred until a real manuscript establishes its semantic model; it is not an alias for code in D2.
The chapter-sized pressure fixture is `test/fixtures/practical-sigil-chapter.sgd`. With a compiler that supports alternate readers, evaluate it with:
sigil -L src -L test eval -f test/fixtures/practical-sigil-chapter.sgdInspecting a document without running it
(sigil doc inspect) returns a manuscript's raw command tree with exact spans and evaluates no author code, so a program can learn a document's structure without trusting it. The ordinary reader path returns lowered syntax, which must be evaluated to yield structure; the inspection surface exists for consumers that cannot do that, such as an indexer pointed at untrusted or half-written documents.
sigil -L src -L test eval -f test/sd-p4-witness-probe.sglSee `docs/passive-parse-api.md` for the node and span representation, the guarantees, and the explicit non-guarantees.
The root container, and the two languages
#lang sigil/doc admits exactly one @article at top level — the generic standalone document. The book/print genre is a sibling language, #lang sigil/doc/book, which admits exactly one @chapter. That is ruling D8: the base language stays generic, and genres are languages rather than extra roots in the base.
Root policy is a value rather than a constant, so both of those languages are the same parser with a different profile, and a language in another package can name its own roots without forking the grammar or the location machinery:
(import (sigil doc reader))
(define folio-profile (make-document-profile "folio/doc" '(note project) 'one-or-more))
(parse-document-parts-with-profile folio-profile source source-name header-end)The root-policy diagnostics are derived from the profile, so each language reports its own name and its own roots. See `docs/root-profiles.md` for the profile fields, the two shipped languages, what a profile deliberately does not vary, and why the root comes from the #lang line rather than from an import.