AtlatestRepositorysigil-doc
1# sigil-doc
2
3`sigil-doc` is Sigil's programmable document language. A document is an
4ordinary Sigil program with a prose-oriented reader:
5
6```scheme
7#lang sigil/doc
8
9@(define-syntax strong
10 (syntax-rules () ((_ child) (em child))))
12@article ["A Small Document" "An Author"]
14@section ["First Section"]
16@p: Prose can contain @strong{ordinary author macros}.
18@end section
19@end article
20```
22Commands are ordinary imported or manuscript-local bindings. Everything in
23`[...]` is read and evaluated as standard Sigil, including multiline forms,
24keywords, macros, and computed values. Top-level `@(...)` forms can import
25modules or define functions and macros; `@(...)` inside a document computes a
26node or proper list of nodes at that position.
28Every command supports the same body notations:
30```text
31@name[...] { ... } balanced body
32@name[...] named multiline body
33 ...
34@end name
35@name[...]: ... remainder of the physical line
36@name[...] {} explicit empty body
37```
39Horizontal whitespace around arguments and braces is cosmetic, indentation is
40never semantic, and whitespace immediately inside a body is delimiter padding.
41Inline commands use braces; named and line bodies are available only at a block
42boundary. `@code{identifier}` is inline code; `@code["sigil"]{...}` is a
43language-labelled block, and `@code[#f]{...}` is an unlabelled block. Named and
44colon `@code` bodies are also blocks. Subject source inside these forms is data
45and is not executed during document authoring.
47Executable examples, their expectations and hidden checks are described in
48[`docs/examples.md`](docs/examples.md).
50Evaluation binds the resulting semantic value as `document`. The package
51includes backend-neutral model/traversal/publication modules, static HTML
52fragments, and a backend-neutral print adapter with a Typst source backend.
53Press consumes the HTML fragments for sites; `sigil-doc` invokes an existing
54typesetter for PDF rather than implementing typography or pagination.
56Build the current two-chapter *Practical Sigil* print edition with:
58```sh
59guix shell typst poppler -- \
60 tools/build-practical-sigil-pdf.sh build/practical-sigil.pdf
61```
63The `.typ` source is retained beside the deterministic, tagged PDF. See
64[`docs/print-backend.md`](docs/print-backend.md) for the backend decision,
65reproducibility contract, font strategy, and long-code wrapping rule.
67Print customization is ordinary checked-in Sigil code. The publication policy
68in `(sigil doc print)` controls numbering, chapter authors, contents, chapter
69starts, and running-header content. The immutable `typst-theme` in
70`(sigil doc render typst)` controls paper, margins, fonts, typography, colors,
71code treatment, headers, and page-number placement. Practical Sigil keeps these
72decisions in `book/practical-sigil/book.sgl` and `theme.sgl`, separate from its
73semantic `.sgd` chapters. The default edition remains byte-compatible with D6;
74the same configuration also demonstrates a distinct A5 compact-study edition.
76A distinct `@pre` form for non-code preformatted material is intentionally
77deferred until a real manuscript establishes its semantic model; it is not an
78alias for code in D2.
80The chapter-sized pressure fixture is
81[`test/fixtures/practical-sigil-chapter.sgd`](test/fixtures/practical-sigil-chapter.sgd).
82With a compiler that supports alternate readers, evaluate it with:
84```sh
85sigil -L src -L test eval -f test/fixtures/practical-sigil-chapter.sgd
86```
88## Inspecting a document without running it
90`(sigil doc inspect)` returns a manuscript's raw command tree with exact spans
91and evaluates no author code, so a program can learn a document's structure
92without trusting it. The ordinary reader path returns *lowered* syntax, which
93must be evaluated to yield structure; the inspection surface exists for
94consumers that cannot do that, such as an indexer pointed at untrusted or
95half-written documents.
97```sh
98sigil -L src -L test eval -f test/sd-p4-witness-probe.sgl
99```
101See [`docs/passive-parse-api.md`](docs/passive-parse-api.md) for the node and
102span representation, the guarantees, and the explicit non-guarantees.
104## The root container, and the two languages
106`#lang sigil/doc` admits exactly one `@article` at top level — the generic standalone
107document. The book/print genre is a sibling language, `#lang sigil/doc/book`, which admits
108exactly one `@chapter`. That is ruling D8: the base language stays generic, and genres are
109languages rather than extra roots in the base.
111Root policy is a value rather than a constant, so both of those languages are the same
112parser with a different profile, and a language in another package can name its own roots
113without forking the grammar or the location machinery:
115```sigil
116(import (sigil doc reader))
118(define folio-profile (make-document-profile "folio/doc" '(note project) 'one-or-more))
119(parse-document-parts-with-profile folio-profile source source-name header-end)
120```
122The root-policy diagnostics are derived from the profile, so each language reports its own
123name and its own roots. See [`docs/root-profiles.md`](docs/root-profiles.md) for the
124profile fields, the two shipped languages, what a profile deliberately does *not* vary,
125and why the root comes from the `#lang` line rather than from an import.