Proposal: Migrate RISC-V ISA Specification from AsciiDoc to Typst

[sequencer]

Executive Summary

This issue proposes migrating the RISC-V ISA Manual and extension specifications from the current AsciiDoc/Ruby/Docker toolchain to Typst. This transition aims to resolve persistent build latency issues, simplify the contributor experience, and enforce strict consistency in instruction definitions through programmable styling.

Jiuyang's team is willing to execute this migration.

The Current Problem

The current documentation infrastructure has accumulated significant technical debt, creating friction for both new and experienced contributors:

• Prohibitive Build Times: Generating the full PDF via asciidoctor-pdf takes minutes. This destroys the local feedback loop, forcing authors to rely on CI to check rendering.
• Complex Dependency Chain: Building locally requires a fragile stack of Ruby (Gems), Python, Node.js (WaveDrom), and Docker. "It works on my machine" is a frequent issue.
• Static Content vs. Dynamic Data: Instruction tables are currently static AsciiDoc text. There is no programmatic link between the specification text and the machine-readable definitions (e.g., riscv-opcodes), leading to synchronization errors and inconsistent formatting across different extensions.

Why Typst?

Typst is a modern, Rust-based typesetting system that serves as a "successor" to LaTeX/AsciiDoc.

• Instant Feedback: Typst uses incremental compilation, reducing build times from minutes to milliseconds. You can type in your editor and see the PDF update instantly.(See https://marketplace.visualstudio.com/items?itemName=myriad-dreamin.tinymist)
• Zero-Dependency Toolchain: The entire build system is a single binary (approx. 30MB). No Docker, no Ruby, no Python required.
• Programmable Markup: Typst is a scripting language. We can define functions like #instruction(...) that act as a single source of truth, automatically generating the register bit-fields, assembly syntax, and operation tables in a standardized format.

Migration Example: AsciiDoc vs. Typst

Typst syntax is very similar to AsciiDoc (using = for headers, * for bold), making the transition easy for writers. However, it separates content from presentation much more effectively.

1. The Old Way (AsciiDoc) Authors manually format tables. If the style guide changes, every file must be edited manually.

[cols="1,1,1,1,1", options="header"]

|===
| imm[11:0] | rs1 | funct3 | rd | opcode
| 12 | 5 | 3 | 5 | 7
|===

Typst calls a function. The layout is defined globally, allowing us to change the visual style of the entire manual by editing one file.

// proposed: semantic data definition
#instruction(
  name: "ADDI",
  description: "Add Immediate",
  format: "I-Type",
  encoding: (
    (bits: 12, name: "imm[11:0]"),
    (bits: 5,  name: "rs1"),
    (bits: 3,  name: "000"),
    (bits: 5,  name: "rd"),
    (bits: 7,  name: "0010011"),
  )
)

This Typst code can automatically generate the standard bit-field diagram (replacing bytefield-svg and wavedrom), the syntax summary, and ensuring the opcode matches the official spec.

Next Steps

We believe this migration is critical for the scalability of RISC-V documentation. Jiuyang's team is prepared to lead this initiative, starting with a pilot conversion of the Unprivileged ISA to demonstrate feature parity and the improved workflow.

[ved-rivos]

May want to start this discussion in the documentation sig : https://lists.riscv.org/g/sig-documentation

[wmat]

Can you open this issue here: https://github.com/riscv-admin/docs-sig/issues