AtlatestRepositorysigil-doc
1
# Print backend3
`sigil-doc` print output has two layers. `(sigil doc print)` converts a checked4
publication and its trusted D3 presentations into backend-neutral print IR. It5
resolves references before output and preserves documents, headings, paragraphs,6
inline emphasis/code, code blocks, admonitions, exercises, anchors, examples, and7
project results. `(sigil doc render typst)` serializes that IR to deterministic8
Typst source. It is an adapter, not a layout engine.10
## Publication policy and Typst themes12
Customization is split deliberately. `make-print-options` produces an13
immutable, backend-neutral publication policy: chapter numbering (`none`,14
`arabic`, `roman-upper`, or `roman-lower`), section numbering and depth,15
chapter-author display (`never`, `always`, or `when-different`), contents depth16
and unnumbered-heading inclusion, next/odd chapter starts, chapter label style,17
and running-header content. The only supported author placement in this slice is18
`beneath-title`; other placements are rejected rather than silently ignored.20
`make-typst-theme` produces an immutable visual theme. It owns paper and21
margins; prose/code fonts and sizes; title, chapter, and section typography;22
heading, accent, and syntax colors; code background, padding, and wrap column;23
admonition colors; chapter-author typography; running-header typography; and24
page-number placement. Dimensions are constructed as typed values such as25
`(make-typst-length 18 'mm)`. Papers, units, enum values, numeric ranges,26
six-digit colors, and font names are validated. Ordinary fields cannot inject27
raw Typst.29
The renderer remains compatible with the D6 one-argument call and accepts30
explicit values by keyword:32
```scheme33
(print-publication->typst publication34
options: practical-sigil-print-options35
theme: practical-sigil-theme)36
```38
`default-print-options` and `default-typst-theme` reproduce the original D639
Typst bytes exactly. The checked-in Practical Sigil configuration lives in40
`book/practical-sigil/book.sgl`, with themes and policies in `theme.sgl`. It41
defines the byte-compatible `current` edition and a visibly different A542
`compact-study` edition. These are ordinary Sigil modules evaluated only by an43
explicit build; loading an `.sgd` manuscript or opening it in Slate does not run44
theme code.46
This first surface intentionally defers independent exercise/example counters,47
front-matter/main-matter page resets, appendix numbering, arbitrary renderer48
procedures, and raw Typst templates. Each requires additional semantic or49
counter-model pressure; none is represented by a no-op option. CLI theme50
overrides are also deferred—the checked-in book configuration is authoritative.52
## Backend decision54
D6 uses **Typst 0.14.0**. It is available through the existing Guix toolchain,55
produces tagged PDF and real outlines/bookmarks, has first-class stable labels and56
page references, embeds fonts, and57
accepts `SOURCE_DATE_EPOCH` for reproducible PDF metadata. The checked environment58
uses `Libertinus Serif` for prose and `DejaVu Sans Mono` for block code. These are59
static, broad-Unicode fonts available in the same Guix environment. No web font or60
other network asset is loaded.62
Sigil/Scheme source highlighting is performed offline by `sigil-doc`, before63
Typst runs. A passive tokenizer preserves every character while distinguishing64
comments, escaped strings, core Scheme forms, numbers, and plain syntax into65
colored, copyable text spans. It does not import a Typst syntax package, call66
Press, execute subject code, or rely on a language-name label. The D6 gate67
checks extracted source text and raster histograms for four distinct semantic68
colors.70
LaTeX remains a possible later backend because it can consume the same print IR.71
HTML plus paged media was not chosen: the locally available browser does not expose72
the same direct, deterministic outline/page-reference contract, and it would blur73
the existing Press site boundary. Sigil does not implement shaping, line breaking,74
pagination, font embedding, outlines, or PDF serialization.76
Typst raw blocks do not wrap long tokens. The adapter therefore inserts a hard line77
break after 88 Unicode scalar values and renders block code at 8 pt. The committed78
gate compiles a 240-character token, checks the three visible pieces in extracted79
text, checks every word bounding box remains within the Letter page, and retains a80
rasterized page for visual review. This is a print-only presentation transform; the81
semantic source remains unchanged.83
## Build85
Run inside the pinned tool environment:87
```sh88
guix shell typst poppler -- \89
tools/build-practical-sigil-pdf.sh build/practical-sigil.pdf90
```92
`SOURCE_DATE_EPOCH` defaults to zero in the wrapper, and Typst runs with one job.93
The generated `.typ` file is retained beside the PDF for inspection. The build does94
not evaluate code blocks or examples. Example/project observations enter print IR95
only as immutable, source-bound verified presentations created by D3.97
The current semantic model has no image/figure node, so D6 does not invent one or98
silently reinterpret another node as a figure. When manuscript pressure adds a99
backend-neutral figure node, the closed adapter will fail until it gains an explicit100
mapping and sizing rule.