ADR-0100: The manual is rendered, with working links and search

Status: Accepted
Date: 2026-09-11
Deciders: jka
Decision: D100

Context

ADR-0099 displayed Markdown source. The densest manual pages are mostly tables, and the contents page is almost entirely links, which could not be followed. rio's manual read worse inside rio than in a text editor.

Decision

Parsing and painting are separate. help_blocks turns a page into block descriptors (heading, para, item, code, table, quote, rule) with no widget involved; help_paint draws them. The parser is a pure function that tests call with a string.

Rendering rules:

Prose is re-wrapped to the window width; the source's hand wrapping is discarded. Code blocks and tables do not wrap and scroll horizontally.
Tables use the fixed-pitch font, with column widths measured on the text as displayed (markup removed), and bold cells use the monospace bold so columns stay aligned. The alignment row is dropped.
Links are per-link tags; a click resolves the tag under the pointer. topic.md, topic.md#heading and #heading all go through one navigation procedure. Anchors are GitHub-style slugs derived from heading text. Back and Forward are provided.
Links to rio's other documents (../README.md) are followed. Paths that are absolute or climb out of rio's directory are refused.

Search. A Find box above the contents turns the list into the sections that mention the text, each with a hit count. Choosing one opens the page at that heading with every occurrence highlighted in the find colour. Matching is line by line in the GUI, on text with markup removed.

Alternatives considered

Searching through the core's project search, as ADR-0091 anticipated. Rejected for the same reason as ADR-0099: over a remote core it would search the server's files. The manual is about 50 KB, so reading it on each keystroke needs no index.

Consequences

The manual renders legibly and its cross-references work.
The same renderer displays agent plans (ADR-0101).
A documentation check verifies that every #anchor in the manual names a real heading, using the viewer's own slug function, so renaming a heading cannot silently break links.