AtlatestRepositorysigil-doc

sigil-doc / tree / docsprint-backend.md

Read it rendered

1# Print backend
2
3`sigil-doc` print output has two layers. `(sigil doc print)` converts a checked
4publication and its trusted D3 presentations into backend-neutral print IR. It
5resolves references before output and preserves documents, headings, paragraphs,
6inline emphasis/code, code blocks, admonitions, exercises, anchors, examples, and
7project results. `(sigil doc render typst)` serializes that IR to deterministic
8Typst source. It is an adapter, not a layout engine.
9
10## Publication policy and Typst themes
12Customization is split deliberately. `make-print-options` produces an
13immutable, backend-neutral publication policy: chapter numbering (`none`,
14`arabic`, `roman-upper`, or `roman-lower`), section numbering and depth,
15chapter-author display (`never`, `always`, or `when-different`), contents depth
16and unnumbered-heading inclusion, next/odd chapter starts, chapter label style,
17and running-header content. The only supported author placement in this slice is
18`beneath-title`; other placements are rejected rather than silently ignored.
20`make-typst-theme` produces an immutable visual theme. It owns paper and
21margins; prose/code fonts and sizes; title, chapter, and section typography;
22heading, accent, and syntax colors; code background, padding, and wrap column;
23admonition colors; chapter-author typography; running-header typography; and
24page-number placement. Dimensions are constructed as typed values such as
25`(make-typst-length 18 'mm)`. Papers, units, enum values, numeric ranges,
26six-digit colors, and font names are validated. Ordinary fields cannot inject
27raw Typst.
29The renderer remains compatible with the D6 one-argument call and accepts
30explicit values by keyword:
32```scheme
33(print-publication->typst publication
34 options: practical-sigil-print-options
35 theme: practical-sigil-theme)
36```
38`default-print-options` and `default-typst-theme` reproduce the original D6
39Typst bytes exactly. The checked-in Practical Sigil configuration lives in
40`book/practical-sigil/book.sgl`, with themes and policies in `theme.sgl`. It
41defines the byte-compatible `current` edition and a visibly different A5
42`compact-study` edition. These are ordinary Sigil modules evaluated only by an
43explicit build; loading an `.sgd` manuscript or opening it in Slate does not run
44theme code.
46This first surface intentionally defers independent exercise/example counters,
47front-matter/main-matter page resets, appendix numbering, arbitrary renderer
48procedures, and raw Typst templates. Each requires additional semantic or
49counter-model pressure; none is represented by a no-op option. CLI theme
50overrides are also deferred—the checked-in book configuration is authoritative.
52## Backend decision
54D6 uses **Typst 0.14.0**. It is available through the existing Guix toolchain,
55produces tagged PDF and real outlines/bookmarks, has first-class stable labels and
56page references, embeds fonts, and
57accepts `SOURCE_DATE_EPOCH` for reproducible PDF metadata. The checked environment
58uses `Libertinus Serif` for prose and `DejaVu Sans Mono` for block code. These are
59static, broad-Unicode fonts available in the same Guix environment. No web font or
60other network asset is loaded.
62Sigil/Scheme source highlighting is performed offline by `sigil-doc`, before
63Typst runs. A passive tokenizer preserves every character while distinguishing
64comments, escaped strings, core Scheme forms, numbers, and plain syntax into
65colored, copyable text spans. It does not import a Typst syntax package, call
66Press, execute subject code, or rely on a language-name label. The D6 gate
67checks extracted source text and raster histograms for four distinct semantic
68colors.
70LaTeX remains a possible later backend because it can consume the same print IR.
71HTML plus paged media was not chosen: the locally available browser does not expose
72the same direct, deterministic outline/page-reference contract, and it would blur
73the existing Press site boundary. Sigil does not implement shaping, line breaking,
74pagination, font embedding, outlines, or PDF serialization.
76Typst raw blocks do not wrap long tokens. The adapter therefore inserts a hard line
77break after 88 Unicode scalar values and renders block code at 8 pt. The committed
78gate compiles a 240-character token, checks the three visible pieces in extracted
79text, checks every word bounding box remains within the Letter page, and retains a
80rasterized page for visual review. This is a print-only presentation transform; the
81semantic source remains unchanged.
83## Build
85Run inside the pinned tool environment:
87```sh
88guix shell typst poppler -- \
89 tools/build-practical-sigil-pdf.sh build/practical-sigil.pdf
90```
92`SOURCE_DATE_EPOCH` defaults to zero in the wrapper, and Typst runs with one job.
93The generated `.typ` file is retained beside the PDF for inspection. The build does
94not evaluate code blocks or examples. Example/project observations enter print IR
95only as immutable, source-bound verified presentations created by D3.
97The current semantic model has no image/figure node, so D6 does not invent one or
98silently reinterpret another node as a figure. When manuscript pressure adds a
99backend-neutral figure node, the closed adapter will fail until it gains an explicit
100mapping and sizing rule.