> Documentation version: 3. [HTML page](maintain-roc-docs.html)

<a id="maintain-the-documentation-renderer"></a>

# Maintain the documentation renderer

Use this chapter when changing ` tools/roc-docs/ `, its dependencies or output
adapters. The [utility reference](roc-docs.md#build-documentation-with-roc-docs)
owns the supported source and presentation contract.

<a id="build-and-test-the-executable"></a>

## 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.

``` sh
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.

<a id="review-the-complete-publication"></a>

## Review the complete publication

Build the manual as [the contributor guide](contributing.md#change-the-manual)
describes, then run the browser audit with Node 22.4+ and Chrome on the test host:

``` sh
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 `.

<a id="keep-module-responsibilities-distinct"></a>

## 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.

<a id="update-fonts-and-dependencies"></a>

## 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.

<a id="verify-independently"></a>

## 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.