114 lines
5.3 KiB
Markdown
114 lines
5.3 KiB
Markdown
# iftypeset (pubstyle) — publication-quality typesetting pipeline
|
||
|
||
This project is a **thin, deterministic runtime** for turning Markdown into high‑quality HTML/PDF using:
|
||
|
||
- **A machine‑readable rule registry** (Chicago / Bringhurst pointers; paraphrased rules only)
|
||
- **Typeset profiles** (`spec/profiles/*.yaml`) that map typographic intent → render tokens
|
||
- **Post‑render QA gates** (`spec/quality_gates.yaml`) that fail builds when layout degrades
|
||
|
||
It is designed to be embedded into constrained workers (e.g. Forgejo PDF export with `--network=none`) and also run as a standalone CLI.
|
||
|
||
**Status:** working spec + seeded rule registry. See `STATUS.md`.
|
||
|
||
## Constraints (non-negotiable)
|
||
|
||
- **No bulk OCR/transcription** of Chicago/Bringhurst into this repo (copyright).
|
||
- Rule records are **paraphrases only**, backed by **pointers** (e.g. `CMOS18 §X.Y pNNN (scan pMMM)`).
|
||
- Chicago OCR (when needed) must be **ephemeral** (extract just enough to locate pointers; do not store page text).
|
||
- Optional profile `webtypography_nc` is **CC BY-NC 4.0** (non-commercial only). See `docs/18-webtypography-nc.md`.
|
||
|
||
## Quickstart (current)
|
||
|
||
From `ai-workspace/iftypeset/`:
|
||
|
||
- (Optional) Install deps into a venv: `python3 -m venv .venv && . .venv/bin/activate && python -m pip install -r requirements.txt`
|
||
- Install the console entrypoint: `python3 -m pip install -e .`
|
||
- Validate spec + rebuild indexes: `iftypeset validate-spec --spec spec --build-indexes`
|
||
- One-shot CI pipeline (recommended): `iftypeset run --input fixtures/sample.md --out out --profile web_pdf --degraded-ok`
|
||
- Multi-doc run (directory or glob): `iftypeset run --input fixtures --out out --profile web_pdf --degraded-ok`
|
||
- Lint Markdown (emits `out/lint-report.json` + `out/manual-checklist.md`): `iftypeset lint --input fixtures/sample.md --out out --profile web_pdf`
|
||
- Lint with auto-fix + post-fix diagnostics: `iftypeset lint --input fixtures/sample.md --out out --profile web_pdf --fix --fix-mode rewrite --lint-fixed`
|
||
- Render HTML + CSS: `iftypeset render-html --input fixtures/sample.md --out out --profile web_pdf`
|
||
- Run QA gates (HTML fallback if no PDF): `iftypeset qa --out out --profile web_pdf`
|
||
- Render PDF (if an engine is installed): `iftypeset render-pdf --input fixtures/sample.md --out out --profile web_pdf`
|
||
- Coverage + trust contract + HTML index: `iftypeset report --spec spec --out out` (writes `out/report/index.html`)
|
||
- Environment/determinism report: `iftypeset doctor --spec spec --out out`
|
||
- Portable review bundle: `iftypeset bundle --out out` (writes `out/iftypeset-bundle.tar.gz`)
|
||
- Run self-check tests: `python3 -m unittest discover -s tests -p 'test_*.py'`
|
||
- Inspect profiles/gates/rules:
|
||
- `iftypeset profiles list`
|
||
- `iftypeset gates show --profile web_pdf`
|
||
- `iftypeset rules list --category links`
|
||
- `iftypeset rules show HOUSE.LINKS.URLS.PREFER_HTTPS`
|
||
|
||
If you do not want to install the console entrypoint, you can still run:
|
||
|
||
- `PYTHONPATH=src python3 -m iftypeset.cli <command> ...`
|
||
|
||
## Config file (`iftypeset.yaml`)
|
||
|
||
You can set repo defaults in `./iftypeset.yaml`. CLI flags always win.
|
||
|
||
Example:
|
||
|
||
```yaml
|
||
defaults:
|
||
spec: spec
|
||
out: out
|
||
profile: web_pdf
|
||
lint:
|
||
fail_on: must
|
||
degraded_ok: true
|
||
run:
|
||
skip_pdf: false
|
||
require_pdf: false
|
||
engine: playwright
|
||
```
|
||
|
||
To use a different config path: `iftypeset --config /path/to/iftypeset.yaml <command> ...`
|
||
|
||
## Enforcement limits (read this)
|
||
|
||
- **Not all rules are automated.** Manual rules (tagged `manual_checklist=true`) appear in `out/manual-checklist.md`.
|
||
- **PDF QA is heuristic.** It depends on text extraction and will miss some layout failures.
|
||
- **Renderer variance exists.** Profiles aim for determinism, but output still depends on the PDF engine + fonts.
|
||
- **Trust contract is explicit.** Run `iftypeset report` to generate `out/trust-contract.md` with current limits.
|
||
|
||
## Lint suppression (explicit, auditable)
|
||
|
||
You can suppress specific rules in a document when needed:
|
||
|
||
- Inline directive (applies to the next non-empty line):
|
||
- `<!-- iftypeset:ignore CMOS.PUNCTUATION.PARENS_BRACKETS.BALANCE -->`
|
||
- Front matter allowlist:
|
||
- `iftypeset_ignore: [CMOS.PUNCTUATION.PARENS_BRACKETS.BALANCE, LINK.WRAP.RISK]`
|
||
|
||
Suppression works by rule id or diagnostic code and should be used sparingly.
|
||
|
||
## Session resilience (avoid “lost work”)
|
||
|
||
If a chat/session resets, trust the repo, not the transcript:
|
||
|
||
- Quick resume: `./scripts/resume.sh`
|
||
- Audit repo state: `./scripts/audit.sh`
|
||
- Run CI sanity checks: `./scripts/ci.sh`
|
||
- Create a portable restore point: `./scripts/checkpoint.sh "short note"`
|
||
|
||
Details: `docs/07-session-resilience.md`
|
||
Handoff snapshot: `docs/08-handoff.md`
|
||
Project status: `docs/09-project-status.md`
|
||
Downloadable summary: `docs/11-project-summary.md`
|
||
Rendering pipeline: `docs/17-rendering-pipeline.md`
|
||
Non-commercial WebTypography profile: `docs/18-webtypography-nc.md`
|
||
Agent notes: `AGENTS.md`
|
||
External review pack: `docs/14-external-review.md`
|
||
Docker runtime: `docs/15-docker.md`
|
||
|
||
## PDF renderers
|
||
|
||
`render-pdf` defaults to `playwright` and does not fall back silently.
|
||
|
||
- `playwright` (preferred; supports header/footer templates and avoids Chromium CLI “date/path” headers/footers)
|
||
- Optional (explicit `--engine` only): `wkhtmltopdf`, `weasyprint`
|
||
|
||
If no engine is present, the command exits with a clear message but still leaves HTML artifacts for QA.
|