AtlatestRepositorysigil-doc
1
# sigil-doc3
`sigil-doc` is Sigil's programmable document language. A document is an4
ordinary Sigil program with a prose-oriented reader:6
```scheme7
#lang sigil/doc9
@(define-syntax strong10
(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 section19
@end article20
```22
Commands are ordinary imported or manuscript-local bindings. Everything in23
`[...]` is read and evaluated as standard Sigil, including multiline forms,24
keywords, macros, and computed values. Top-level `@(...)` forms can import25
modules or define functions and macros; `@(...)` inside a document computes a26
node or proper list of nodes at that position.28
Every command supports the same body notations:30
```text31
@name[...] { ... } balanced body32
@name[...] named multiline body33
...34
@end name35
@name[...]: ... remainder of the physical line36
@name[...] {} explicit empty body37
```39
Horizontal whitespace around arguments and braces is cosmetic, indentation is40
never semantic, and whitespace immediately inside a body is delimiter padding.41
Inline commands use braces; named and line bodies are available only at a block42
boundary. `@code{identifier}` is inline code; `@code["sigil"]{...}` is a43
language-labelled block, and `@code[#f]{...}` is an unlabelled block. Named and44
colon `@code` bodies are also blocks. Subject source inside these forms is data45
and is not executed during document authoring.47
Executable examples, their expectations and hidden checks are described in48
[`docs/examples.md`](docs/examples.md).50
Evaluation binds the resulting semantic value as `document`. The package51
includes backend-neutral model/traversal/publication modules, static HTML52
fragments, and a backend-neutral print adapter with a Typst source backend.53
Press consumes the HTML fragments for sites; `sigil-doc` invokes an existing54
typesetter for PDF rather than implementing typography or pagination.56
Build the current two-chapter *Practical Sigil* print edition with:58
```sh59
guix shell typst poppler -- \60
tools/build-practical-sigil-pdf.sh build/practical-sigil.pdf61
```63
The `.typ` source is retained beside the deterministic, tagged PDF. See64
[`docs/print-backend.md`](docs/print-backend.md) for the backend decision,65
reproducibility contract, font strategy, and long-code wrapping rule.67
Print customization is ordinary checked-in Sigil code. The publication policy68
in `(sigil doc print)` controls numbering, chapter authors, contents, chapter69
starts, and running-header content. The immutable `typst-theme` in70
`(sigil doc render typst)` controls paper, margins, fonts, typography, colors,71
code treatment, headers, and page-number placement. Practical Sigil keeps these72
decisions in `book/practical-sigil/book.sgl` and `theme.sgl`, separate from its73
semantic `.sgd` chapters. The default edition remains byte-compatible with D6;74
the same configuration also demonstrates a distinct A5 compact-study edition.76
A distinct `@pre` form for non-code preformatted material is intentionally77
deferred until a real manuscript establishes its semantic model; it is not an78
alias for code in D2.80
The chapter-sized pressure fixture is81
[`test/fixtures/practical-sigil-chapter.sgd`](test/fixtures/practical-sigil-chapter.sgd).82
With a compiler that supports alternate readers, evaluate it with:84
```sh85
sigil -L src -L test eval -f test/fixtures/practical-sigil-chapter.sgd86
```88
## Inspecting a document without running it90
`(sigil doc inspect)` returns a manuscript's raw command tree with exact spans91
and evaluates no author code, so a program can learn a document's structure92
without trusting it. The ordinary reader path returns *lowered* syntax, which93
must be evaluated to yield structure; the inspection surface exists for94
consumers that cannot do that, such as an indexer pointed at untrusted or95
half-written documents.97
```sh98
sigil -L src -L test eval -f test/sd-p4-witness-probe.sgl99
```101
See [`docs/passive-parse-api.md`](docs/passive-parse-api.md) for the node and102
span representation, the guarantees, and the explicit non-guarantees.104
## The root container, and the two languages106
`#lang sigil/doc` admits exactly one `@article` at top level — the generic standalone107
document. The book/print genre is a sibling language, `#lang sigil/doc/book`, which admits108
exactly one `@chapter`. That is ruling D8: the base language stays generic, and genres are109
languages rather than extra roots in the base.111
Root policy is a value rather than a constant, so both of those languages are the same112
parser with a different profile, and a language in another package can name its own roots113
without forking the grammar or the location machinery:115
```sigil116
(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
```122
The root-policy diagnostics are derived from the profile, so each language reports its own123
name and its own roots. See [`docs/root-profiles.md`](docs/root-profiles.md) for the124
profile fields, the two shipped languages, what a profile deliberately does *not* vary,125
and why the root comes from the `#lang` line rather than from an import.