Reference#

Reference#

This chapter is the desk reference: the CLI, every format, every stable report code, every limit, and the design records, collected beside one another. Everything here is taken from the code’s own tables. Where the book and the binary disagree, trust the binary and file the difference as a bug.

The command line#

usage: zenfmt [options] INPUT

INPUT is a file path, or - for stdin. Stdin requires --from and either -o PATH or --stdout. The reason is plain: a stream has no extension to detect from and no name to derive the output path from.

Exit codes#

The formats#

19 readers, one writer. Every reader’s plugin id is ai.insan.zenfmt.<format>. Detection weighs both kinds of evidence: for in-memory input the content signature always runs, and when it contradicts the extension, content wins with a core.extension-mismatch note. File inputs whose extension routes are read directly. --from overrides everything.

Word processing. DOCX maps styles to headings through basedOn chains, synthesizes lists from numbering properties, folds merged table cells, and carries footnotes. Comments and text boxes are counted omissions; tracked insertions and deletions additionally ride as revision facets, and style names, page size, and image bytes are carried too. Legacy DOC resolves Heading 1 through 9 from the binary stylesheet and extracts hyperlink fields; other named styles survive as style facets. ODT resolves automatic styles, images, sections, and inline footnotes. RTF covers tables, lists, fields, footnotes, and outline headings.

Spreadsheets. All five spreadsheet readers project one sheet to one h2 plus one table, first row as header, with typed cells. Dates render ISO. Percentages multiply out. Formulas keep their cached values, and a note says so.

Presentations. A slide projects to a title heading plus body content: lists, tables, links, images. Speaker notes land in a container classed notes. Every presentation conversion carries its projection warning. Charts and animation do not survive, and the reader says so rather than pretending; shape geometry, though, now rides in layout facets in EMU.

Publishing. EPUB walks container, then package, then spine, and parses chapters with the HTML machinery. DRM is refused outright. PDF is native Zig text extraction: xref and object streams, FlateDecode, ToUnicode CMaps, width metrics, heading tiers from font sizes. It carries a layout-projection note on every conversion, because a PDF has pages, not structure.

Report codes#

Every diagnostic carries a stable code, asserted by at least one test. The catalog below groups the codes by namespace. Severity is the worst the code is issued at. Class is the exit class when the code is fatal; “none” marks notes and warnings, which fail a conversion only under --strict.

Engine (core.*)#

Markdown writer (markdown.*)#

The writer’s codes are loss notes. Markdown cannot represent the construct, the writer degraded it deliberately, and the manifest says so.

Office Open XML (docx.*, xlsx.*, pptx.*)#

OpenDocument (odt.*, ods.*, odp.*)#

Legacy binary Office (doc.*, xls.*, ppt.*, xlsb.*)#

Publishing (epub.*, pdf.*, html.*)#

Lightweight markup (text.*, csv.*, rtf.*, asciidoc.*, rst.*)#

Server (server.*)#

The zenfmt server (ZDS 0016) reuses the engine’s report shape for every server-origin failure: same fields, same JSON, the server. prefix. The HTTP status travels beside the envelope; the exit class mirrors the engine’s mapping.

Limits#

Every bound has a name, a default, and a --limit NAME=VALUE override. Depth overrides above the hard cap of 4096 are refused. The cap sizes the walker stacks, and no input is worth an unbounded stack.

Environment#

Building and testing zenfmt needs exactly Zig 0.16.0. Building the design records and this book additionally needs Typst 0.15 or later. The benchmark optionally uses pandoc and Node.js (for anydoc). Both are competitors, not dependencies.

zig build                 # the CLI into zig-out/bin/
zig build test            # the full suite
zig build fmt-check       # formatting
zig build docs            # ZDS records, index, and site
zig build benchmark       # the conversion benchmark (see its chapter)

The design records#

The Zen Discussion records under docs/zds/ carry the decisions this book describes. Each format record states its mapping table, its deliberate omissions with their report codes, and its round-trip expectations. That is the review-time half of the honesty contract. The report system is the runtime half.