Maintain the documentation renderer — The roc-automation manual

Use this chapter when changing tools/roc-docs/, its dependencies or output adapters. The utility reference owns the supported source and presentation contract.

Build and test the executable§

Use compiler nightly-2026-10-28-bad769b. Package URLs in the app headers pin the renderer dependencies. Keep Roc commands sharing a package cache sequential. The build driver uses --opt=interpreter and produces --opt=speed executables; compilation requires substantially more memory than rendering.

export ROC=/absolute/path/to/roc
"$ROC" fmt --check tools/roc-docs
python3 tools/roc-docs/tests/run_roc_tests.py
"$ROC" --opt=interpreter tools/roc-docs/build.roc -- x86_64-linux
export ROC_DOCS_BINARY="$PWD/dist/roc-docs-x86_64-linux"
python3 tools/roc-docs/tests/test_cli.py
python3 tools/roc-docs/tests/test_build.py

Select x86_64-linux, aarch64-linux or aarch64-darwin for the build host. The harness requires successful test/build summaries. It accepts only the pinned dependencies' allowlisted unreachable-code warnings; local warnings, other diagnostics and failed tests reject.

The native tests run the renderer with external tools unavailable on PATH. Poppler on the test host independently checks PDF text, destinations, tags and colours. These checks do not establish PDF/A or PDF/UA conformance.

Review the complete publication§

Build the manual as the contributor guide describes, then run the browser audit with Node 22.4+ and Chrome on the test host:

node tools/roc-docs/tests/check_html_browser.mjs .docs-out/site /tmp/roc-docs-screenshots

ROC_DOCS_BINARY must name the renderer under review. Set CHROME if Chrome is not in its default location. The audit checks every page’s links, images, source bytes and highlighting, then navigation, overflow and actual font styles at desktop/mobile widths in light/dark modes.

Inspect the complete PDF as contact sheets and representative pages at readable resolution. Review contents, headings, prose styles, long code, tables, callouts, diagrams and chapter transitions for clipping, overlap and awkward pagination. The Documentation workflow retains the manual and typography PDFs, page rasters and browser screenshots in docs-browser-review.

Keep module responsibilities distinct§

RepositoryBuild.roc loads bounded workspace files and stages publication.
SourceIncludes.roc selects local listing bytes; Preparation.roc adapts the pinned parser into HTML trees and Markdown for PDF.
Html.roc and site.css own website layout; Renderer.roc owns PDF adaptation, theme and font registration. SyntaxHighlight.roc remains independent of both.
ImageAssets.roc, Png.roc and Svg.roc admit images. DiagramAdapter.roc bounds and lays out Mermaid, DiagramSvg.roc serializes generated SVG, and VectorDrawing.roc adapts its geometry for PDF.

Keep generated diagram serialization separate from authored SVG validation. No source is executed and includes cannot fetch network content. Preserve listing whitespace and provenance; reject ambiguous source recovery, unsafe paths, delimiter injection and selections outside the documented profile.

prepare exposes intermediate Markdown, assets and an experimental inventory for inspection. It is not an input protocol for the shared build action. The inventory records source hashes, page routes, listing selections and distinct vector/raster image identities.

Update fonts and dependencies§

Use roc-font’s public face, byte and license accessors for measurement, embedding and generated assets. The package pin is the font identity; do not prepare derivatives or copy font files into the repository. Keep attribution in generated assets, SVG metadata and --licenses, with source notices in THIRD_PARTY_LICENSES.md and vendor/.

When changing a font or parser pin, check glyph coverage, text extraction, style selection, source whitespace and links across all outputs. PDF missing glyphs must reject before publication. Review the entire manual visually; compilation and small fixtures cannot establish that an authored book reads correctly.

Verify independently§

The Python reference adapter and inventory verifier under tests/ check source bytes, anchors, links, tables, images and Markdown exports. Keep expected-output fixtures independent of the native implementation, including scoped heading attributes, duplicate IDs and listing selections. Independent PDF readers check extracted characters, destinations, colours and vector geometry.

Exercise malformed input, resource limits, unsafe paths and output collisions; failures must preserve the previous publication. Keep native CLI/action tests and exact distributed-artifact tests on every supported execution platform.