Format integration

A handler emits different output per format because the targets are fundamentally different — typeset LaTeX, a CSS-styled archive, word-processor documents. How each is produced, and what a handler must respect to behave correctly everywhere:

LaTeX (PDF)

PDF handlers return raw LaTeX — a RawBlock (or RawInline) of markup — and rely on commands defined in the handler's macros.tex, which the engine injects into the document preamble. The document is then typeset with XeLaTeX.

Because each handler's output is an opaque block of LaTeX, handlers must follow nesting-safe composition rules (wrapping content in an environment rather than splicing strings). This is the structural reason aggregation isn't supported — see Handlers.

EPUB

EPUB handlers add CSS classes to the element; the styling comes from each handler's style.css, which the engine collects and links into every page. EPUB is the only format where extra classes you add survive to the output, so it's the most directly stylable.

Fonts are a two-part mechanism that must agree: CSS @font-face rules tell the reader which fonts to use, and the build copies the matching .otf files into the archive. Keystone embeds only the fonts your book references — discovered by the pre-scan described in the pipeline. The DejaVu system fonts are the exception: they fall back via CSS rather than embedding as files.

DOCX and ODT

These formats build on a styled reference document. Handlers don't emit markup; they attach a custom-style that names a paragraph or character style defined in that reference doc. Word and LibreOffice then render the style.

A paragraph can carry only one custom style, and the TeX Live fonts aren't available in word processors, so each font maps to a system fallback (Georgia for Libertine, and so on). PDF-only effects (raw LaTeX, running headers, watermark) simply don't appear.

Format capabilities

Filter code never pattern-matches the raw format string. It asks a small set of capability questions — whether the format uses TeX, uses CSS, or embeds fonts — through the engine's format registry. A handler implements the formats it can serve and lets the rest pass through; an attribute that works in one format but silently does nothing in two others is a sign the concern belongs in a different handler.

This is why some shortcuts note "PDF only" or "PDF and EPUB" in the reference — the underlying handler genuinely can't express that effect in the other formats, so it's an honest no-op there rather than a broken approximation.