Atv0.2.1Repositorysigil-doc

docs/print-backend.md

Release v0.2.1 · Default-branch version

Document

Print backend

sigil-doc print output has two layers. (sigil doc print) converts a checked publication and its trusted D3 presentations into backend-neutral print IR. It resolves references before output and preserves documents, headings, paragraphs, inline emphasis/code, code blocks, admonitions, exercises, anchors, examples, and project results. (sigil doc render typst) serializes that IR to deterministic Typst source. It is an adapter, not a layout engine.

Publication policy and Typst themes

Customization is split deliberately. make-print-options produces an immutable, backend-neutral publication policy: chapter numbering (none, arabic, roman-upper, or roman-lower), section numbering and depth, chapter-author display (never, always, or when-different), contents depth and unnumbered-heading inclusion, next/odd chapter starts, chapter label style, and running-header content. The only supported author placement in this slice is beneath-title; other placements are rejected rather than silently ignored.

make-typst-theme produces an immutable visual theme. It owns paper and margins; prose/code fonts and sizes; title, chapter, and section typography; heading, accent, and syntax colors; code background, padding, and wrap column; admonition colors; chapter-author typography; running-header typography; and page-number placement. Dimensions are constructed as typed values such as (make-typst-length 18 'mm). Papers, units, enum values, numeric ranges, six-digit colors, and font names are validated. Ordinary fields cannot inject raw Typst.

The renderer remains compatible with the D6 one-argument call and accepts explicit values by keyword:

(print-publication->typst publication
  options: practical-sigil-print-options
  theme: practical-sigil-theme)

default-print-options and default-typst-theme reproduce the original D6 Typst bytes exactly. The checked-in Practical Sigil configuration lives in book/practical-sigil/book.sgl, with themes and policies in theme.sgl. It defines the byte-compatible current edition and a visibly different A5 compact-study edition. These are ordinary Sigil modules evaluated only by an explicit build; loading an .sgd manuscript or opening it in Slate does not run theme code.

This first surface intentionally defers independent exercise/example counters, front-matter/main-matter page resets, appendix numbering, arbitrary renderer procedures, and raw Typst templates. Each requires additional semantic or counter-model pressure; none is represented by a no-op option. CLI theme overrides are also deferred—the checked-in book configuration is authoritative.

Backend decision

D6 uses Typst 0.14.0. It is available through the existing Guix toolchain, produces tagged PDF and real outlines/bookmarks, has first-class stable labels and page references, embeds fonts, and accepts SOURCE_DATE_EPOCH for reproducible PDF metadata. The checked environment uses Libertinus Serif for prose and DejaVu Sans Mono for block code. These are static, broad-Unicode fonts available in the same Guix environment. No web font or other network asset is loaded.

Sigil/Scheme source highlighting is performed offline by sigil-doc, before Typst runs. A passive tokenizer preserves every character while distinguishing comments, escaped strings, core Scheme forms, numbers, and plain syntax into colored, copyable text spans. It does not import a Typst syntax package, call Press, execute subject code, or rely on a language-name label. The D6 gate checks extracted source text and raster histograms for four distinct semantic colors.

LaTeX remains a possible later backend because it can consume the same print IR. HTML plus paged media was not chosen: the locally available browser does not expose the same direct, deterministic outline/page-reference contract, and it would blur the existing Press site boundary. Sigil does not implement shaping, line breaking, pagination, font embedding, outlines, or PDF serialization.

Typst raw blocks do not wrap long tokens. The adapter therefore inserts a hard line break after 88 Unicode scalar values and renders block code at 8 pt. The committed gate compiles a 240-character token, checks the three visible pieces in extracted text, checks every word bounding box remains within the Letter page, and retains a rasterized page for visual review. This is a print-only presentation transform; the semantic source remains unchanged.

Build

Run inside the pinned tool environment:

guix shell typst poppler -- \
  tools/build-practical-sigil-pdf.sh build/practical-sigil.pdf

SOURCE_DATE_EPOCH defaults to zero in the wrapper, and Typst runs with one job. The generated .typ file is retained beside the PDF for inspection. The build does not evaluate code blocks or examples. Example/project observations enter print IR only as immutable, source-bound verified presentations created by D3.

The current semantic model has no image/figure node, so D6 does not invent one or silently reinterpret another node as a figure. When manuscript pressure adds a backend-neutral figure node, the closed adapter will fail until it gains an explicit mapping and sizing rule.