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 font files into the archive. Keystone embeds only the fonts your book references — discovered by the pre-scan described in the pipeline.

DOCX and ODT

These formats build on a styled reference document. The common pattern is a handler attaching a custom-style that names a paragraph or character style defined in that reference doc, which Word or LibreOffice then renders. But a docx/odt hook is as free as any other — it can also emit raw word-processor markup (as pagebreak does) or restructure content. It can reuse any style already in the reference document; adding a new named style is the one thing the template can't do — see Customizing.

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 — the cross-format honesty the single-responsibility rule depends on.

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.