iftypeset v0.1 — Demo Acceptance Pack

This doc defines what “ship‑ready” means for iftypeset (pubstyle): a deterministic Markdown → HTML → PDF pipeline with enforceable quality gates and auditable artifacts.

Goals

Produce consistently good-looking outputs from plain Markdown without manual layout heroics.
Provide machine-verifiable QA gates (layout/report JSON) suitable for CI.
Keep the system renderer-agnostic via adapters (Chromium / WeasyPrint / Prince / Antenna House / Vivliostyle, etc.).
Preserve legal constraints: rules are paraphrases + pointers, never book text.

Definition of Done (v0.1)

“Done” means the following commands are boring and reliable:

lint emits deterministic diagnostics and a manual checklist.
render-html emits deterministic HTML + CSS for a profile.
qa runs on HTML (always) and on PDF (when available) and fails builds when gates exceed thresholds.
report shows rule coverage and doesn’t regress.

Profiles to Support in v0.1

web_pdf (screen-first): tolerant, readable, strong accessibility defaults.
dense_tech (specs): tighter measure targets, code/tables common, strict numbering/citations.
memo (internal): conservative, low typographic complexity.

Fixture Set (minimum)

Create and maintain fixtures that represent real “pain” documents. v0.1 should ship with at least these:

Memo (short, mixed content) — bullets + links + a couple of headings
- Stress: heading hierarchy, link wrapping, list spacing.
Dense technical note — headings, numbered sections, code blocks, small tables
- Stress: code wrapping/overflow policy, table overflow policy, numbering monotonicity.
Report with many links — long URLs/DOIs/emails, references section
- Stress: link wrap policy, footnote/reference formatting, readability.
Table-heavy checklist — 3–5 tables, some wide
- Stress: table overflow handling, header repeat policy (HTML), clipping detection (PDF when possible).
Degraded input — hard-wrapped paragraphs + inconsistent headings
- Stress: degraded-mode contract: unwrap/recover safely + emit degraded-mode report.

Acceptance Gates (must pass)

Lint gates (always on)

No schema/spec validation failures.
lint-report.json is produced and deterministic across two runs.
manual-checklist.md is produced and contains only rules tagged manual_checklist=true.

HTML render gates (always on)

render.html and render.css produced deterministically.
CSS tokens reflect chosen profile (page size, margins, font stacks, line-height).
No external fetches in HTML (self-contained mode must embed local assets).

QA gates (HTML fallback; PDF when available)

Minimum v0.1 gate set:

max_link_wrap_incidents (catch “unbreakable” URLs / DOIs / emails).
max_table_overflow_incidents (wide tables).
max_code_overflow_incidents (wide code blocks).
max_stranded_headings (keep-with-next heuristic).
max_heading_numbering_errors (basic numbering monotonicity).

PDF-only gates (enable when a PDF engine is available):

widows/orphans
overfull lines (glyph boxes exceed text block)

Multi-renderer Compatibility (design requirement)

v0.1 should treat the PDF engine as an adapter. Acceptance criteria:

render-pdf --engine auto:
- selects an available engine,
- writes render-log.json including engine name + version,
- fails clearly if no engine available (but keeps HTML artifacts).

Renderer capability differences must be explicit in render-log.json and qa-report.json (e.g., “widow/orphan detection unavailable for HTML-only run”).

Demo Script (for humans)

For a convincing “this is real” demo:

Run lint + show lint-report.json and manual-checklist.md.
Run render-html + open out/render.html (show the profile look).
Run qa + show qa-report.json (pass/fail, counts).
If PDF engine exists, show the rendered PDF and the same QA gates on PDF.

Release Checklist (v0.1)

At least 30 fixtures exist and are exercised in CI.
CI fails when QA thresholds are exceeded (no “green by vibes”).
CI fails on spec regression (coverage floors, schema validation).
Degraded mode emits its report artifacts and never silently “fixes” content.
Renderer adapters are documented (how auto chooses, how to pin).

4.3 KiB Raw Export PDF Blame History Unescape Escape