ADR-0099: rio shows its own manual
- Status: Accepted; amended by ADR-0100
- Date: 2026-09-11
- Deciders: jka
- Decision: D99
Context
ADR-0091 placed the manual in docs/ with file names as topic ids and index.md as
contents, which is most of what a help viewer needs. The Help menu existed with only
About rio, and F1 was unbound.
Decision
Help ▸ Contents… (F1) opens a help window: the contents as a rich list on the left (ADR-0043), the selected topic on the right.
- The GUI reads
docs/from its own installation, not through the core. Help is part of the GUI. With a remote core, reading through the core would show the server's manual, possibly for a different version, or nothing. - It is a non-modal, single-instance window, like the Extensions window. Whether help should become a dock panel (ADR-0035) is left open until it has been used.
- F1 is the keymap command
help(ADR-0023), so it can be remapped and the shortcut documentation check covers it. - A missing topic is reported inside the window rather than raised as an error.
The first version showed the Markdown source in the editor font.
Consequences
- The manual is available offline wherever rio runs.
- Tests check that the code's
docs/location is the real directory and that the topics offered are exactly those listed inindex.md. - rio is deployed by cloning its repository, so
docs/is always present beside the code; no separate packaging step is needed. - ADR-0100 added rendering, links and search.