From cb1ff8c32e4e525d19edf0113507a0bdde6bf669 Mon Sep 17 00:00:00 2001 From: wmat Date: Mon, 8 Jun 2026 10:29:54 -0400 Subject: [PATCH 01/26] Changes for Antora instructions. Signed-off-by: Bill Traynor wmat@riscv.org --- docs-resources | 2 +- local_build.md | 90 +++++++++++++++++++++++++++-------- src/a_few_basics.adoc | 4 +- src/authoring.adoc | 17 +++++-- src/build-infrastructure.adoc | 6 +++ src/docs-dev-guide.adoc | 2 + src/intro.adoc | 17 +++++++ 7 files changed, 110 insertions(+), 28 deletions(-) diff --git a/docs-resources b/docs-resources index 0904c8a..62576cd 160000 --- a/docs-resources +++ b/docs-resources @@ -1 +1 @@ -Subproject commit 0904c8ad991d189c882a922563060a7806c78f55 +Subproject commit 62576cdd285615473c279eb9acecade9e0fe0e1f diff --git a/local_build.md b/local_build.md index 0ce4a3c..e63e2b0 100644 --- a/local_build.md +++ b/local_build.md @@ -218,6 +218,26 @@ wavedrom-cli WARNING: For the MacOS, if you upgrade from a prior version to Big Sur, you must reinstall first the NPM and then the NPM version of the wavedrom-cli. +## Run a local Kroki server for diagrams + +The RISC-V documentation site uses [Kroki](https://kroki.io) to render diagrams (including WaveDrom, Bytefield, Graphviz, and others) server-side. The dev playbook at `antora-dev.riscv.org` is configured to reach a local Kroki instance on port 9870. + +Start the Kroki server with Docker: + +```cmd +docker run -d -p 9870:8000 yuzutech/kroki +``` + +The `-d` flag runs it in the background. The container will restart automatically on subsequent Docker starts unless explicitly stopped. + +To stop it: + +```cmd +docker stop $(docker ps -q --filter ancestor=yuzutech/kroki) +``` + +The dev playbook already has `kroki-server-url: http://localhost:9870` set in its `asciidoc.attributes`, so no additional configuration is needed once the container is running. + ## Graphviz is used for diagrams in some appendices To support graphviz on the Mac, use brew @@ -264,47 +284,75 @@ You can then add a bibliography to your appendices and use bibtex conventions to Details of how to work with bibtex and the RISC-V bibliogrpahy are in the example.pdf file. -## AsciiDoc book headers and styles +## AsciiDoc document header and styles -Attributes in the book headers for RISC-V AsciiDoc content control aspects of the pdf build. Together with the `risc-v_spec-pdf.yml` file, they enable, among other things, numbered headings, a TOC, running headers and footers, footnotes at chapter ends, custom fonts, admonitions, an index, and an optional colophon. +Attributes in the document header for RISC-V AsciiDoc content control aspects of the pdf build. Together with the `docs-resources/themes/riscv-pdf.yml` file, they enable, among other things, numbered headings, a TOC, running headers and footers, footnotes at chapter ends, custom fonts, admonitions, an index, and an optional colophon. -In addition, properties in the book header within this repo point to the `images` directory and also the `resources/riscv-spec.bib` file that contains the RISC-V `bibtex` entries for use in creating a bibliography as one of the appendices. +The entry point for the build is `modules/ROOT/pages/spec-sample.adoc`. This file contains the document header attributes and uses `include::` directives to pull in the chapter files. The `docs-resources/global-config.adoc` submodule file provides shared attributes such as `:company:` and `:doctype:`. -For shorter documents, you have the option of using a report header, however, we have not yet provided branding for it. +NOTE: The header is already in the template. The only changes you normally need to make are to update `:revnumber:`, `:revremark:`, and author metadata, then add chapter files using `include::chapter.adoc[]` in the order you want them to appear. -NOTE: The headers are already in the template files. The only changes you normally need to make are to add chapter-sized sections in using the syntax `include::filename.adoc[]` in the order by which you want them to appear. +## Create and add a new chapter file -## Create and name a new .adoc file - -- In your text editor, create a new file. -- Assign a name and save with the .adoc extension. -- In the first line, add `[file_name]` (using a meaningful string for the filename) and in the second line, use a double "==" to indicate a topic heading, add some content, and save the file with an `.adoc` file extension. -- In the header file, add `include::file_name.adoc` and save it. - -NOTE: Blank lines are not allowed in between the `include::file_name.adoc` files. +- In your text editor, create a new file in `modules/ROOT/pages/`. +- Assign a meaningful name and save it with the `.adoc` extension. +- Begin the file with a section heading (`==`) rather than a document title (`=`), since it will be included into `spec-sample.adoc`. +- Add an `include::chapter-name.adoc[]` line in `modules/ROOT/pages/spec-sample.adoc` in the position where you want the chapter to appear. +- Add an `xref:chapter-name.adoc[Chapter Title]` entry to `modules/ROOT/nav.adoc` so the chapter appears in the Antora site navigation. ## HTML build Building in HTML is a good way to check that your content under development builds properly. -As soon as you have installed Asciidoctor, you can build HTML content from any `.adoc` file on your own machine--simply CD into the directory that contains your `.adoc` files and run the following: +The simplest approach from the repository root is: + +```cmd +make +``` + +This builds both PDF and HTML output to the `build/` directory, using Docker if available or native tooling otherwise. + +To build HTML only without the Makefile, run: + +```cmd +asciidoctor modules/ROOT/pages/spec-sample.adoc +``` + +For pdf output without the Makefile, cd into the repository root and use: + +```cmd +asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg \ + -r asciidoctor-bibtex -r asciidoctor-diagram \ + -a pdf-theme=docs-resources/themes/riscv-pdf.yml \ + -a pdf-fontsdir=docs-resources/fonts/ \ + modules/ROOT/pages/spec-sample.adoc +``` + +ALERT: When copying/pasting commands for the CLI on the Windows OS, check that no substitutions are being made. We have seen the `=` get replaced with a `#`, causing an error message about fonts. + +## Antora site build + +To preview how the specification will appear as a multi-page HTML site (as it will be published on the RISC-V documentation site), use: ```cmd -asciidoctor any_file_name.adoc +make antora ``` -This generates a file named `any_file_name.html`. -For pdf output, cd into this cloned directory and use this command: +Output is written to `build/site/`. This requires Node.js 18+ and either `antora` on your PATH or `npx` available. + +### Install Antora ```cmd -asciidoctor-pdf -r asciidoctor-mathematical -a mathematical-format=svg -r asciidoctor-bibtex -r asciidoctor-diagram book_header.adoc -a pdf-style=resources/themes/riscv-pdf.yml -a pdf-fontsdir=resources/fonts/ +npm install -g antora ``` -This generates a file named `book_header.pdf` that makes use of the graphics, styles, and fonts that is identical to example.pdf. +Verify: -ALERT: When copying/pasting commands for the CLI on the Windows OS, check that no substitutions are being made. We have seen the '=' get replaced with a '#', causing an error message about fonts. +```cmd +antora --version +``` -For your own content, change the name of the header file to a meaningful file name, and change the `include::filename.adoc` as needed. +If you prefer not to install globally, `make antora` will automatically fall back to `npx antora` if `antora` is not on your PATH. ## AsciiDoc and Asciidoctor toolchain documentation diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc index 404c214..5629fec 100644 --- a/src/a_few_basics.adoc +++ b/src/a_few_basics.adoc @@ -88,7 +88,7 @@ The following example is a valid sequence of headers. Index ``` -NOTE: Settings in the header file (`book_header.adoc` in the docs-templates repo) trigger auto-generation of Appendix prefixes and of the Index (among other things). +NOTE: Settings in the header file (`modules/ROOT/pages/spec-sample.adoc` in the docs-spec-template repo) trigger auto-generation of Appendix prefixes and of the Index (among other things). === Lists @@ -331,7 +331,7 @@ Either table renders with table headers. ==== Table captions -The `book_header.adoc` file in the docs-templates repo sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style. +The `modules/ROOT/pages/spec-sample.adoc` file in the docs-spec-template repo sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style. To set a caption for a table or image, use the pattern as follows: diff --git a/src/authoring.adoc b/src/authoring.adoc index 3e6b0dc..3f5ab82 100644 --- a/src/authoring.adoc +++ b/src/authoring.adoc @@ -10,15 +10,24 @@ Asciidoctor toolchains: === RISC-V AsciiDoc authoring assets -Please view the https://github.com/riscv/docs-templates[readme] in the docs-templates repo for information about the automated build processes. +Please view the https://github.com/riscv/docs-spec-template[readme] in the docs-spec-template repo for information about the automated build processes. -The docs-templates repo also contains assets, such as fonts, styles, directory structure, and themes that you need for RISC-V specifications, along with a https://github.com/riscv/docs-dev-guide/blob/main/local_build.md[document] that takes you through a local install process that supports all of the required features for a local build. +The docs-spec-template repo contains assets such as fonts, styles, directory structure, and themes needed for RISC-V specifications. It uses an Antora-compatible directory structure with source files in `modules/ROOT/pages/`. See <> for a full description of the layout. -Although testing your markup by building a PDF is good practice, you can catch many common errors by simply downloading Asciidoctor and building the HTML output by using the following command: +A https://github.com/riscv/docs-dev-guide/blob/main/local_build.md[local build guide] takes you through the local install process that supports all of the required features. + +Although testing your markup by building a PDF is good practice, you can catch many common errors by simply downloading Asciidoctor and building the HTML output using the following command from the repository root: + +[source,cmd] +---- +asciidoctor modules/ROOT/pages/spec-sample.adoc +---- + +Or more simply, using the Makefile: [source,cmd] ---- -asciidoctor book_header.adoc +make ---- === Writing diff --git a/src/build-infrastructure.adoc b/src/build-infrastructure.adoc index 9eb6cf3..a37cd66 100644 --- a/src/build-infrastructure.adoc +++ b/src/build-infrastructure.adoc @@ -4,6 +4,12 @@ Most RISC-V AsciiDoc documents use a `Makefile` to simplify the build process. F If Docker is already installed, the `Makefile` will invoke `docker` for the build process. Otherwise, it will build natively. +=== Source directory + +In the Antora-based template, AsciiDoc source files live in `modules/ROOT/pages/` rather than a flat `src/` directory. The `Makefile` sets `SRC_DIR := modules/ROOT/pages` accordingly. The entry point for the PDF and HTML build is `modules/ROOT/pages/spec-sample.adoc`. + +For a full description of the Antora directory structure and how to register your specification with the RISC-V documentation site, see <>. + As an author of a document, there are some conventions to be aware of: - The version, date, and state (draft, frozen, ratified) of the document should be specified in the `.adoc` file for that document via use of the `:revnumber:` and `:revremark:` keywords. An example usage is the following: diff --git a/src/docs-dev-guide.adoc b/src/docs-dev-guide.adoc index 3e5238e..0b787a4 100755 --- a/src/docs-dev-guide.adoc +++ b/src/docs-dev-guide.adoc @@ -74,6 +74,8 @@ include::intro.adoc[] include::authoring.adoc[] +include::antora-structure.adoc[] + include::a_few_basics.adoc[] include::index_bib.adoc[] diff --git a/src/intro.adoc b/src/intro.adoc index d9c1255..ebcd357 100644 --- a/src/intro.adoc +++ b/src/intro.adoc @@ -17,3 +17,20 @@ RISC-V documentation contributors: - Create a Linux foundation ID with https://lfx.linuxfoundation.org/[LFX]. - Become a https://riscv.org/membership/[member of the RISC-V International] organization. + +[[getting-help]] +=== Getting help + +If you have questions about authoring, the build toolchain, or the Antora documentation site, the following resources are available: + +https://lists.riscv.org/g/sig-documentation[sig-documentation mailing list]:: +The primary venue for discussion about RISC-V documentation tooling, processes, and the Antora site. Post here for questions about the build infrastructure, the dev playbook, or contributing a new specification. + +mailto:help@riscv.org[help@riscv.org]:: +General RISC-V support address for questions that don't fit the mailing list. + +https://github.com/riscv/docs-dev-guide/issues[docs-dev-guide GitHub issues]:: +File an issue here if you find something incorrect or missing in this guide. + +https://github.com/riscv-admin/antora-dev.riscv.org/issues[antora-dev.riscv.org GitHub issues]:: +File an issue here for problems with the RISC-V Antora documentation site or the dev playbook. From ad7908aad2cae822a1c8d028d15a229184f899d6 Mon Sep 17 00:00:00 2001 From: wmat Date: Mon, 8 Jun 2026 11:13:54 -0400 Subject: [PATCH 02/26] More changes for Antora instructions. Signed-off-by: Bill Traynor wmat@riscv.org --- src/build-infrastructure.adoc | 55 +++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/src/build-infrastructure.adoc b/src/build-infrastructure.adoc index a37cd66..8aa233f 100644 --- a/src/build-infrastructure.adoc +++ b/src/build-infrastructure.adoc @@ -75,3 +75,58 @@ errors. This can be adjusted by altering the `asciidoc` invocation in the `Makef This document repository currently adheres to all of these conventions, and may be a useful starting point for other specifications. + +[[spec-types]] +=== ISA vs. non-ISA specifications + +How a specification is authored and where it lives depends on whether it is an ISA or non-ISA specification. + +ISA specifications:: +Extensions to the RISC-V Unprivileged or Privileged ISA are authored as chapters within a branch or fork of the https://github.com/riscv/riscv-isa-manual[riscv-isa-manual] repository. The specification state and revision information are set within the relevant chapter file(s) in that branch, consistent with the conventions of the ISA manual. + +Non-ISA specifications:: +All other RISC-V specifications are authored in their own autonomous GitHub repository, using the https://github.com/riscv/docs-spec-template[docs-spec-template] as the starting point. The repository layout, build infrastructure, and GitHub Actions workflows are all provided by the template. + +[[spec-lifecycle]] +=== Specification lifecycle + +RISC-V specifications progress through four defined states. The current state is set via the `:revremark:` attribute in the document header and is displayed on the cover page of every build. The canonical definitions of each state are maintained at https://riscv.org/spec-state[riscv.org/spec-state]. + +Draft:: +The specification is under active development. Everything is subject to change. Use `:revremark: This document is in the link:http://riscv.org/spec-state[Development state]` or simply `:revremark: Draft`. + +Stable:: +The specification is feature-complete but may still change in response to public review feedback. Use `:revremark: Stable`. + +Frozen:: +The specification has completed public review. Only critical bug fixes are permitted. Implementations based on this version may proceed at the implementer's risk. Use `:revremark: Frozen`. + +Ratified:: +The specification has been formally ratified by RISC-V International. No further changes will be made to this version. Use `:revremark: Ratified`. + +==== State advancement is manual + +State advancement is *not* automated. No process or workflow automatically promotes a specification from one state to the next. Authors must update `:revremark:` in the source document by hand, following approval through the appropriate RISC-V governance process. + +==== Non-ISA specifications: releasing a new state + +For non-ISA specifications, each state transition should be accompanied by a corresponding GitHub release so the published PDF is permanently associated with that state. The `build-pdf.yml` GitHub Actions workflow supports this via a manual `workflow_dispatch` trigger. + +To publish a release at a new state: + +. Update `:revremark:` in `modules/ROOT/pages/spec-sample.adoc` to the new state. +. Update `:revnumber:` to the appropriate version string. +. Commit and push the changes. +. In GitHub, navigate to *Actions → Create Specification Document → Run workflow*. +. Select the matching `revision_mark` (Draft, Stable, Frozen, or Ratified). +. Set `prerelease` and `draft` flags as appropriate. +. Run the workflow — it will build the PDF, create a git tag, and publish a GitHub release. + +[NOTE] +==== +The `revision_mark` selected in the workflow dispatch sets the `REVMARK` environment variable passed to `make`, which overrides `:revremark:` in the built PDF. Ensure the value you select matches what is set in the source document so the two are consistent. +==== + +==== ISA specifications: state within the ISA manual + +For ISA specifications, the specification state is not tracked via a standalone GitHub release workflow. Instead, the state is reflected within the chapter(s) of the relevant ISA manual — either the Unprivileged or Privileged specification — in the branch of https://github.com/riscv/riscv-isa-manual[riscv-isa-manual] where the author is working. The state and revision information should follow the conventions established within that repository and be consistent with the overall state of the ISA manual branch. From dbe6198c37f11857b0c287c902a673e4b6960284 Mon Sep 17 00:00:00 2001 From: wmat Date: Mon, 8 Jun 2026 11:19:04 -0400 Subject: [PATCH 03/26] Updates for Antora. Signed-off-by: Bill Traynor wmat@riscv.org --- src/antora-structure.adoc | 158 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 src/antora-structure.adoc diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc new file mode 100644 index 0000000..aafd799 --- /dev/null +++ b/src/antora-structure.adoc @@ -0,0 +1,158 @@ +[[antora-structure]] +== Antora repository structure + +RISC-V specification repositories use an https://docs.antora.org[Antora]-compatible directory structure. This enables individual specification repositories to be assembled into the RISC-V documentation site by Antora while also supporting a standalone PDF and HTML build via `make`. + +=== Repository layout + +A specification repository contains the following top-level files and directories: + +---- +antora.yml <1> +Makefile <2> +docs-resources/ <3> +modules/ + ROOT/ + nav.adoc <4> + images/ <5> + pages/ <6> + spec-sample.adoc + intro.adoc + chapter2.adoc + ... +---- +<1> Antora component descriptor — identifies this repo as an Antora component. +<2> Makefile — drives the PDF/HTML build. +<3> Git submodule providing shared fonts, themes, and images. +<4> Navigation file — defines the sidebar structure for the Antora site. +<5> Symlink to `docs-resources/images` so Antora can find shared images. +<6> All AsciiDoc source files live here. + +=== antora.yml + +The `antora.yml` file at the repository root is the Antora https://docs.antora.org/antora/latest/component-version-descriptor/[component descriptor]. It identifies the repository as an Antora content component and provides metadata used when the site is assembled. + +[source,yaml] +---- +name: spec-sample <1> +title: RISC-V Example Specification (Zexmpl) <2> +version: ~ <3> +nav: + - modules/ROOT/nav.adoc <4> +---- +<1> Component name — used in Antora cross-references from other components (`xref:spec-sample:page.adoc[]`). Rename to match your specification. +<2> Human-readable title shown in the site UI. Update this for your specification. +<3> `~` means unversioned. Set to a version string (e.g., `1.0`) once the specification is released. +<4> Path to the navigation file, relative to `antora.yml`. + +When creating a new specification repository from the template, at minimum rename `name` and `title` to match your specification. + +=== modules/ROOT/pages/ + +All AsciiDoc source files live in `modules/ROOT/pages/`. This is the Antora convention for the default (ROOT) module's page content. + +The entry point for the standalone PDF and HTML build is `spec-sample.adoc`, which uses AsciiDoc `include::` directives to pull in the other chapter files. For the Antora site build, each file in `pages/` becomes a separate HTML page. + +When adding a new chapter: + +. Create the `.adoc` file in `modules/ROOT/pages/`. +. Add an `include::` directive for it in `spec-sample.adoc` (for the PDF build). +. Add an `xref:` entry for it in `modules/ROOT/nav.adoc` (for the Antora site build). + +=== modules/ROOT/nav.adoc + +The `nav.adoc` file defines the navigation sidebar shown in the Antora site. It uses a nested list of `xref:` macros. + +[source,adoc] +---- +* xref:spec-sample.adoc[RISC-V Example Specification] +** xref:intro.adoc[Introduction] +** xref:chapter2.adoc[The Second Chapter] +** xref:contributors.adoc[Contributors] +** xref:bibliography.adoc[Bibliography] +---- + +Add a new entry here each time you add a chapter to `pages/`. The order of entries controls the sidebar order. + +=== modules/ROOT/images/ + +This directory is a symlink to `docs-resources/images`, which contains the shared RISC-V logo and other common images. Antora requires images to be located within the module directory tree, which is why the symlink exists rather than referencing `docs-resources/` directly. + +Place any specification-specific images in this directory alongside the symlinked shared images, or manage them via the symlink target in `docs-resources/`. + +[[dev-playbook]] +=== Publishing to the RISC-V documentation site + +The RISC-V documentation site is assembled from all specification repositories by a central Antora playbook maintained at https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org]. Specification authors do not manage their own playbook — instead, they submit a pull request to that repository to register their specification as a content source. + +==== Naming your branch + +By convention, Antora-ready branches are named with the version and an `-antora` suffix: + +---- +v1.0-antora +v20250312-antora +---- + +Create this branch from your specification's release tag or working branch once the Antora directory structure is in place. + +==== Adding a content source + +In the playbook at `antora/antora-playbook.yml`, add an entry to the `content.sources` list. Use an existing entry as a model and follow the comment convention used throughout the file: + +[source,yaml] +---- +# My Specification — component: my-spec | chapters 5–12 +- url: https://github.com/riscv/my-spec.git + branches: [v1.0-antora] + start_page: ROOT::index.adoc + start_path: / + worktrees: true + submodules: true +---- + +The `component` name in the comment must match the `name` field in your `antora.yml`. Set `submodules: true` if your repository uses git submodules (e.g., `docs-resources`). Set `worktrees: true` if your repository contains symlinks. + +==== Adding numbering rules + +The playbook uses custom extensions to number chapters and appendices in the site navigation. Add a corresponding entry for your specification to both the `nav_numbering_extension` and `section_numbering_extension` blocks. Both blocks share the same rules via a YAML anchor (`&numbering_rules` / `*numbering_rules`), so you only need to add your entry once, in the `nav_numbering_extension` block: + +[source,yaml] +---- +# --- My Specification -------------------------------------------------- +- component: my-spec <1> + module: ROOT <2> + branches: ['v1.0-antora'] <3> + chapters: {start: 5, end: 12} <4> + appendices: {start: 13, end: 14} <5> +---- +<1> Must match the `name` in your `antora.yml`. +<2> Use `ROOT` for single-module specifications (the standard case). +<3> Must match the branch name(s) listed in your `content.sources` entry. +<4> The range of nav entries (top-level `*` items in `nav.adoc`) that are numbered chapters. Count from the first entry in `nav.adoc` — entries before your first chapter (e.g., a preface or overview page) are typically at position 1–4. +<5> Omit this line entirely if your specification has no appendices. + +==== Submitting the pull request + +. Fork or branch https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org]. +. Add your content source and numbering rules to `antora/antora-playbook.yml` as described above. +. Open a pull request against the `main` branch with a brief description of the specification being added. + +[[install-antora]] +=== Installing Antora + +Antora is needed to run a local site preview. It requires Node.js version 18 or later. Once Node.js is installed, install Antora globally: + +[source,cmd] +---- +npm install -g antora +---- + +Verify the installation: + +[source,cmd] +---- +antora --version +---- + +For Node.js installation instructions, see https://nodejs.org/en/download/[nodejs.org]. From e00e031f8c39940993bede77876738f73a68d04b Mon Sep 17 00:00:00 2001 From: wmat Date: Mon, 8 Jun 2026 11:42:10 -0400 Subject: [PATCH 04/26] Adds a changelog. Signed-off-by: Bill Traynor wmat@riscv.org --- CHANGES.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 CHANGES.md diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 0000000..9dd378e --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,38 @@ +# Changes + +## 2026-06-08 — Antora structure and documentation site guidance + +### New files + +- `src/antora-structure.adoc` — New section documenting the Antora-based repository layout used by RISC-V specification repositories. Covers `antora.yml`, `modules/ROOT/pages/`, `modules/ROOT/nav.adoc`, `modules/ROOT/images/`, and how to register a specification with the RISC-V documentation site by submitting a pull request to [riscv-admin/antora-dev.riscv.org](https://github.com/riscv-admin/antora-dev.riscv.org). Includes content-source entry format, chapter numbering rules configuration, branch naming conventions, and Antora installation instructions. + +### Modified files + +**`src/docs-dev-guide.adoc`** +- Added `include::antora-structure.adoc[]` between `authoring.adoc` and `a_few_basics.adoc`. + +**`src/authoring.adoc`** +- Updated repository reference from `docs-templates` to `docs-spec-template`. +- Replaced stale `asciidoctor book_header.adoc` quick-build command with the correct entry point (`asciidoctor modules/ROOT/pages/spec-sample.adoc`) and a `make` alternative. +- Updated description of template repo to reflect Antora-based directory structure. + +**`src/a_few_basics.adoc`** +- Updated two references to `book_header.adoc` (lines 91 and 334) to `modules/ROOT/pages/spec-sample.adoc` in the docs-spec-template repo. + +**`src/build-infrastructure.adoc`** +- Added `=== Source directory` subsection noting that `SRC_DIR` is now `modules/ROOT/pages/` and cross-referencing the antora-structure section. +- Added `[[spec-types]]` subsection distinguishing ISA specifications (authored on a branch/fork of riscv-isa-manual) from non-ISA specifications (authored in an autonomous repository using docs-spec-template). +- Added `[[spec-lifecycle]]` section defining the four specification states (Draft, Stable, Frozen, Ratified) with `:revremark:` examples and a link to `riscv.org/spec-state`. +- Documented that state advancement is entirely manual — no automation promotes a specification between states. +- Documented the non-ISA release process using the `workflow_dispatch` GitHub Actions trigger, including the `revision_mark` input and a note on keeping it consistent with `:revremark:` in the source. +- Documented that ISA specification state is managed within the relevant chapter(s) of the riscv-isa-manual branch where the author is working. + +**`src/intro.adoc`** +- Added `[[getting-help]]` subsection consolidating help resources: `sig-documentation` mailing list, `help@riscv.org`, docs-dev-guide GitHub issues, and antora-dev.riscv.org GitHub issues. + +**`local_build.md`** +- Updated `## AsciiDoc book headers and styles` section to reference `modules/ROOT/pages/spec-sample.adoc` as the document entry point and `docs-resources/global-config.adoc` for shared attributes. +- Updated `## Create and name a new .adoc file` to reflect the Antora workflow: new files go in `modules/ROOT/pages/`, are included in `spec-sample.adoc` for the PDF build, and registered in `modules/ROOT/nav.adoc` for the Antora site. +- Updated `## HTML build` section to use `make` and the correct entry point (`modules/ROOT/pages/spec-sample.adoc`) in place of stale `book_header.adoc` references. +- Added `## Antora site build` section covering `make antora`, output location, and Antora installation (`npm install -g antora`). +- Added `## Run a local Kroki server for diagrams` section with the Docker run command (`docker run -d -p 9870:8000 yuzutech/kroki`), a stop command, and a note that the dev playbook is already configured for `localhost:9870`. From 1d4a918e2aadf14726e4c2b39651ef4c24b455ab Mon Sep 17 00:00:00 2001 From: wmat Date: Mon, 8 Jun 2026 11:42:10 -0400 Subject: [PATCH 05/26] Adds a changelog. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- CHANGES.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 CHANGES.md diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 0000000..9dd378e --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,38 @@ +# Changes + +## 2026-06-08 — Antora structure and documentation site guidance + +### New files + +- `src/antora-structure.adoc` — New section documenting the Antora-based repository layout used by RISC-V specification repositories. Covers `antora.yml`, `modules/ROOT/pages/`, `modules/ROOT/nav.adoc`, `modules/ROOT/images/`, and how to register a specification with the RISC-V documentation site by submitting a pull request to [riscv-admin/antora-dev.riscv.org](https://github.com/riscv-admin/antora-dev.riscv.org). Includes content-source entry format, chapter numbering rules configuration, branch naming conventions, and Antora installation instructions. + +### Modified files + +**`src/docs-dev-guide.adoc`** +- Added `include::antora-structure.adoc[]` between `authoring.adoc` and `a_few_basics.adoc`. + +**`src/authoring.adoc`** +- Updated repository reference from `docs-templates` to `docs-spec-template`. +- Replaced stale `asciidoctor book_header.adoc` quick-build command with the correct entry point (`asciidoctor modules/ROOT/pages/spec-sample.adoc`) and a `make` alternative. +- Updated description of template repo to reflect Antora-based directory structure. + +**`src/a_few_basics.adoc`** +- Updated two references to `book_header.adoc` (lines 91 and 334) to `modules/ROOT/pages/spec-sample.adoc` in the docs-spec-template repo. + +**`src/build-infrastructure.adoc`** +- Added `=== Source directory` subsection noting that `SRC_DIR` is now `modules/ROOT/pages/` and cross-referencing the antora-structure section. +- Added `[[spec-types]]` subsection distinguishing ISA specifications (authored on a branch/fork of riscv-isa-manual) from non-ISA specifications (authored in an autonomous repository using docs-spec-template). +- Added `[[spec-lifecycle]]` section defining the four specification states (Draft, Stable, Frozen, Ratified) with `:revremark:` examples and a link to `riscv.org/spec-state`. +- Documented that state advancement is entirely manual — no automation promotes a specification between states. +- Documented the non-ISA release process using the `workflow_dispatch` GitHub Actions trigger, including the `revision_mark` input and a note on keeping it consistent with `:revremark:` in the source. +- Documented that ISA specification state is managed within the relevant chapter(s) of the riscv-isa-manual branch where the author is working. + +**`src/intro.adoc`** +- Added `[[getting-help]]` subsection consolidating help resources: `sig-documentation` mailing list, `help@riscv.org`, docs-dev-guide GitHub issues, and antora-dev.riscv.org GitHub issues. + +**`local_build.md`** +- Updated `## AsciiDoc book headers and styles` section to reference `modules/ROOT/pages/spec-sample.adoc` as the document entry point and `docs-resources/global-config.adoc` for shared attributes. +- Updated `## Create and name a new .adoc file` to reflect the Antora workflow: new files go in `modules/ROOT/pages/`, are included in `spec-sample.adoc` for the PDF build, and registered in `modules/ROOT/nav.adoc` for the Antora site. +- Updated `## HTML build` section to use `make` and the correct entry point (`modules/ROOT/pages/spec-sample.adoc`) in place of stale `book_header.adoc` references. +- Added `## Antora site build` section covering `make antora`, output location, and Antora installation (`npm install -g antora`). +- Added `## Run a local Kroki server for diagrams` section with the Docker run command (`docker run -d -p 9870:8000 yuzutech/kroki`), a stop command, and a note that the dev playbook is already configured for `localhost:9870`. From 928e9949cee23f5adfd904d6613b9b0eda2a9a26 Mon Sep 17 00:00:00 2001 From: wmat Date: Mon, 8 Jun 2026 11:13:54 -0400 Subject: [PATCH 06/26] More changes for Antora instructions. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/build-infrastructure.adoc | 55 +++++++++++++++++++++++++++++++++++ 1 file changed, 55 insertions(+) diff --git a/src/build-infrastructure.adoc b/src/build-infrastructure.adoc index 9eb6cf3..6c07a5b 100644 --- a/src/build-infrastructure.adoc +++ b/src/build-infrastructure.adoc @@ -69,3 +69,58 @@ errors. This can be adjusted by altering the `asciidoc` invocation in the `Makef This document repository currently adheres to all of these conventions, and may be a useful starting point for other specifications. + +[[spec-types]] +=== ISA vs. non-ISA specifications + +How a specification is authored and where it lives depends on whether it is an ISA or non-ISA specification. + +ISA specifications:: +Extensions to the RISC-V Unprivileged or Privileged ISA are authored as chapters within a branch or fork of the https://github.com/riscv/riscv-isa-manual[riscv-isa-manual] repository. The specification state and revision information are set within the relevant chapter file(s) in that branch, consistent with the conventions of the ISA manual. + +Non-ISA specifications:: +All other RISC-V specifications are authored in their own autonomous GitHub repository, using the https://github.com/riscv/docs-spec-template[docs-spec-template] as the starting point. The repository layout, build infrastructure, and GitHub Actions workflows are all provided by the template. + +[[spec-lifecycle]] +=== Specification lifecycle + +RISC-V specifications progress through four defined states. The current state is set via the `:revremark:` attribute in the document header and is displayed on the cover page of every build. The canonical definitions of each state are maintained at https://riscv.org/spec-state[riscv.org/spec-state]. + +Draft:: +The specification is under active development. Everything is subject to change. Use `:revremark: This document is in the link:http://riscv.org/spec-state[Development state]` or simply `:revremark: Draft`. + +Stable:: +The specification is feature-complete but may still change in response to public review feedback. Use `:revremark: Stable`. + +Frozen:: +The specification has completed public review. Only critical bug fixes are permitted. Implementations based on this version may proceed at the implementer's risk. Use `:revremark: Frozen`. + +Ratified:: +The specification has been formally ratified by RISC-V International. No further changes will be made to this version. Use `:revremark: Ratified`. + +==== State advancement is manual + +State advancement is *not* automated. No process or workflow automatically promotes a specification from one state to the next. Authors must update `:revremark:` in the source document by hand, following approval through the appropriate RISC-V governance process. + +==== Non-ISA specifications: releasing a new state + +For non-ISA specifications, each state transition should be accompanied by a corresponding GitHub release so the published PDF is permanently associated with that state. The `build-pdf.yml` GitHub Actions workflow supports this via a manual `workflow_dispatch` trigger. + +To publish a release at a new state: + +. Update `:revremark:` in `modules/ROOT/pages/spec-sample.adoc` to the new state. +. Update `:revnumber:` to the appropriate version string. +. Commit and push the changes. +. In GitHub, navigate to *Actions → Create Specification Document → Run workflow*. +. Select the matching `revision_mark` (Draft, Stable, Frozen, or Ratified). +. Set `prerelease` and `draft` flags as appropriate. +. Run the workflow — it will build the PDF, create a git tag, and publish a GitHub release. + +[NOTE] +==== +The `revision_mark` selected in the workflow dispatch sets the `REVMARK` environment variable passed to `make`, which overrides `:revremark:` in the built PDF. Ensure the value you select matches what is set in the source document so the two are consistent. +==== + +==== ISA specifications: state within the ISA manual + +For ISA specifications, the specification state is not tracked via a standalone GitHub release workflow. Instead, the state is reflected within the chapter(s) of the relevant ISA manual — either the Unprivileged or Privileged specification — in the branch of https://github.com/riscv/riscv-isa-manual[riscv-isa-manual] where the author is working. The state and revision information should follow the conventions established within that repository and be consistent with the overall state of the ISA manual branch. From b33c164b0b60d9fe6d1c5adace0914ec52855059 Mon Sep 17 00:00:00 2001 From: wmat Date: Mon, 8 Jun 2026 11:19:04 -0400 Subject: [PATCH 07/26] Updates for Antora. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/antora-structure.adoc | 158 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 158 insertions(+) create mode 100644 src/antora-structure.adoc diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc new file mode 100644 index 0000000..aafd799 --- /dev/null +++ b/src/antora-structure.adoc @@ -0,0 +1,158 @@ +[[antora-structure]] +== Antora repository structure + +RISC-V specification repositories use an https://docs.antora.org[Antora]-compatible directory structure. This enables individual specification repositories to be assembled into the RISC-V documentation site by Antora while also supporting a standalone PDF and HTML build via `make`. + +=== Repository layout + +A specification repository contains the following top-level files and directories: + +---- +antora.yml <1> +Makefile <2> +docs-resources/ <3> +modules/ + ROOT/ + nav.adoc <4> + images/ <5> + pages/ <6> + spec-sample.adoc + intro.adoc + chapter2.adoc + ... +---- +<1> Antora component descriptor — identifies this repo as an Antora component. +<2> Makefile — drives the PDF/HTML build. +<3> Git submodule providing shared fonts, themes, and images. +<4> Navigation file — defines the sidebar structure for the Antora site. +<5> Symlink to `docs-resources/images` so Antora can find shared images. +<6> All AsciiDoc source files live here. + +=== antora.yml + +The `antora.yml` file at the repository root is the Antora https://docs.antora.org/antora/latest/component-version-descriptor/[component descriptor]. It identifies the repository as an Antora content component and provides metadata used when the site is assembled. + +[source,yaml] +---- +name: spec-sample <1> +title: RISC-V Example Specification (Zexmpl) <2> +version: ~ <3> +nav: + - modules/ROOT/nav.adoc <4> +---- +<1> Component name — used in Antora cross-references from other components (`xref:spec-sample:page.adoc[]`). Rename to match your specification. +<2> Human-readable title shown in the site UI. Update this for your specification. +<3> `~` means unversioned. Set to a version string (e.g., `1.0`) once the specification is released. +<4> Path to the navigation file, relative to `antora.yml`. + +When creating a new specification repository from the template, at minimum rename `name` and `title` to match your specification. + +=== modules/ROOT/pages/ + +All AsciiDoc source files live in `modules/ROOT/pages/`. This is the Antora convention for the default (ROOT) module's page content. + +The entry point for the standalone PDF and HTML build is `spec-sample.adoc`, which uses AsciiDoc `include::` directives to pull in the other chapter files. For the Antora site build, each file in `pages/` becomes a separate HTML page. + +When adding a new chapter: + +. Create the `.adoc` file in `modules/ROOT/pages/`. +. Add an `include::` directive for it in `spec-sample.adoc` (for the PDF build). +. Add an `xref:` entry for it in `modules/ROOT/nav.adoc` (for the Antora site build). + +=== modules/ROOT/nav.adoc + +The `nav.adoc` file defines the navigation sidebar shown in the Antora site. It uses a nested list of `xref:` macros. + +[source,adoc] +---- +* xref:spec-sample.adoc[RISC-V Example Specification] +** xref:intro.adoc[Introduction] +** xref:chapter2.adoc[The Second Chapter] +** xref:contributors.adoc[Contributors] +** xref:bibliography.adoc[Bibliography] +---- + +Add a new entry here each time you add a chapter to `pages/`. The order of entries controls the sidebar order. + +=== modules/ROOT/images/ + +This directory is a symlink to `docs-resources/images`, which contains the shared RISC-V logo and other common images. Antora requires images to be located within the module directory tree, which is why the symlink exists rather than referencing `docs-resources/` directly. + +Place any specification-specific images in this directory alongside the symlinked shared images, or manage them via the symlink target in `docs-resources/`. + +[[dev-playbook]] +=== Publishing to the RISC-V documentation site + +The RISC-V documentation site is assembled from all specification repositories by a central Antora playbook maintained at https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org]. Specification authors do not manage their own playbook — instead, they submit a pull request to that repository to register their specification as a content source. + +==== Naming your branch + +By convention, Antora-ready branches are named with the version and an `-antora` suffix: + +---- +v1.0-antora +v20250312-antora +---- + +Create this branch from your specification's release tag or working branch once the Antora directory structure is in place. + +==== Adding a content source + +In the playbook at `antora/antora-playbook.yml`, add an entry to the `content.sources` list. Use an existing entry as a model and follow the comment convention used throughout the file: + +[source,yaml] +---- +# My Specification — component: my-spec | chapters 5–12 +- url: https://github.com/riscv/my-spec.git + branches: [v1.0-antora] + start_page: ROOT::index.adoc + start_path: / + worktrees: true + submodules: true +---- + +The `component` name in the comment must match the `name` field in your `antora.yml`. Set `submodules: true` if your repository uses git submodules (e.g., `docs-resources`). Set `worktrees: true` if your repository contains symlinks. + +==== Adding numbering rules + +The playbook uses custom extensions to number chapters and appendices in the site navigation. Add a corresponding entry for your specification to both the `nav_numbering_extension` and `section_numbering_extension` blocks. Both blocks share the same rules via a YAML anchor (`&numbering_rules` / `*numbering_rules`), so you only need to add your entry once, in the `nav_numbering_extension` block: + +[source,yaml] +---- +# --- My Specification -------------------------------------------------- +- component: my-spec <1> + module: ROOT <2> + branches: ['v1.0-antora'] <3> + chapters: {start: 5, end: 12} <4> + appendices: {start: 13, end: 14} <5> +---- +<1> Must match the `name` in your `antora.yml`. +<2> Use `ROOT` for single-module specifications (the standard case). +<3> Must match the branch name(s) listed in your `content.sources` entry. +<4> The range of nav entries (top-level `*` items in `nav.adoc`) that are numbered chapters. Count from the first entry in `nav.adoc` — entries before your first chapter (e.g., a preface or overview page) are typically at position 1–4. +<5> Omit this line entirely if your specification has no appendices. + +==== Submitting the pull request + +. Fork or branch https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org]. +. Add your content source and numbering rules to `antora/antora-playbook.yml` as described above. +. Open a pull request against the `main` branch with a brief description of the specification being added. + +[[install-antora]] +=== Installing Antora + +Antora is needed to run a local site preview. It requires Node.js version 18 or later. Once Node.js is installed, install Antora globally: + +[source,cmd] +---- +npm install -g antora +---- + +Verify the installation: + +[source,cmd] +---- +antora --version +---- + +For Node.js installation instructions, see https://nodejs.org/en/download/[nodejs.org]. From c54dc2dac4273bc7556ed046accdc596bf0c429f Mon Sep 17 00:00:00 2001 From: wmat Date: Mon, 8 Jun 2026 11:42:10 -0400 Subject: [PATCH 08/26] Adds a changelog. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- CHANGES.md | 38 ++++++++++++++++++++++++++++++++++++++ 1 file changed, 38 insertions(+) create mode 100644 CHANGES.md diff --git a/CHANGES.md b/CHANGES.md new file mode 100644 index 0000000..9dd378e --- /dev/null +++ b/CHANGES.md @@ -0,0 +1,38 @@ +# Changes + +## 2026-06-08 — Antora structure and documentation site guidance + +### New files + +- `src/antora-structure.adoc` — New section documenting the Antora-based repository layout used by RISC-V specification repositories. Covers `antora.yml`, `modules/ROOT/pages/`, `modules/ROOT/nav.adoc`, `modules/ROOT/images/`, and how to register a specification with the RISC-V documentation site by submitting a pull request to [riscv-admin/antora-dev.riscv.org](https://github.com/riscv-admin/antora-dev.riscv.org). Includes content-source entry format, chapter numbering rules configuration, branch naming conventions, and Antora installation instructions. + +### Modified files + +**`src/docs-dev-guide.adoc`** +- Added `include::antora-structure.adoc[]` between `authoring.adoc` and `a_few_basics.adoc`. + +**`src/authoring.adoc`** +- Updated repository reference from `docs-templates` to `docs-spec-template`. +- Replaced stale `asciidoctor book_header.adoc` quick-build command with the correct entry point (`asciidoctor modules/ROOT/pages/spec-sample.adoc`) and a `make` alternative. +- Updated description of template repo to reflect Antora-based directory structure. + +**`src/a_few_basics.adoc`** +- Updated two references to `book_header.adoc` (lines 91 and 334) to `modules/ROOT/pages/spec-sample.adoc` in the docs-spec-template repo. + +**`src/build-infrastructure.adoc`** +- Added `=== Source directory` subsection noting that `SRC_DIR` is now `modules/ROOT/pages/` and cross-referencing the antora-structure section. +- Added `[[spec-types]]` subsection distinguishing ISA specifications (authored on a branch/fork of riscv-isa-manual) from non-ISA specifications (authored in an autonomous repository using docs-spec-template). +- Added `[[spec-lifecycle]]` section defining the four specification states (Draft, Stable, Frozen, Ratified) with `:revremark:` examples and a link to `riscv.org/spec-state`. +- Documented that state advancement is entirely manual — no automation promotes a specification between states. +- Documented the non-ISA release process using the `workflow_dispatch` GitHub Actions trigger, including the `revision_mark` input and a note on keeping it consistent with `:revremark:` in the source. +- Documented that ISA specification state is managed within the relevant chapter(s) of the riscv-isa-manual branch where the author is working. + +**`src/intro.adoc`** +- Added `[[getting-help]]` subsection consolidating help resources: `sig-documentation` mailing list, `help@riscv.org`, docs-dev-guide GitHub issues, and antora-dev.riscv.org GitHub issues. + +**`local_build.md`** +- Updated `## AsciiDoc book headers and styles` section to reference `modules/ROOT/pages/spec-sample.adoc` as the document entry point and `docs-resources/global-config.adoc` for shared attributes. +- Updated `## Create and name a new .adoc file` to reflect the Antora workflow: new files go in `modules/ROOT/pages/`, are included in `spec-sample.adoc` for the PDF build, and registered in `modules/ROOT/nav.adoc` for the Antora site. +- Updated `## HTML build` section to use `make` and the correct entry point (`modules/ROOT/pages/spec-sample.adoc`) in place of stale `book_header.adoc` references. +- Added `## Antora site build` section covering `make antora`, output location, and Antora installation (`npm install -g antora`). +- Added `## Run a local Kroki server for diagrams` section with the Docker run command (`docker run -d -p 9870:8000 yuzutech/kroki`), a stop command, and a note that the dev playbook is already configured for `localhost:9870`. From 44d560843062c8ca84c4cc8514b9b1e5aab995df Mon Sep 17 00:00:00 2001 From: wmat Date: Wed, 10 Jun 2026 14:28:55 -0400 Subject: [PATCH 09/26] Addressing feedback. Signed-off-by: Bill Traynor wmat@riscv.org --- src/antora-structure.adoc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index aafd799..c2cf806 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -19,18 +19,22 @@ modules/ spec-sample.adoc intro.adoc chapter2.adoc + example.bib <7> ... + partials/ <8> ---- -<1> Antora component descriptor — identifies this repo as an Antora component. +<1> Antora component descriptor — identifies this repo as an Antora component and provides component metadata and configuration. <2> Makefile — drives the PDF/HTML build. <3> Git submodule providing shared fonts, themes, and images. <4> Navigation file — defines the sidebar structure for the Antora site. <5> Symlink to `docs-resources/images` so Antora can find shared images. <6> All AsciiDoc source files live here. +<7> BibTeX bibliography file. Referenced by `spec-sample.adoc` via the `:bibtex-file:` attribute. +<8> Optional directory for reusable AsciiDoc fragments (partials), such as Wavedrom diagram source files or content shared across chapters. Reference partials with `include::partial$filename.adoc[]`. === antora.yml -The `antora.yml` file at the repository root is the Antora https://docs.antora.org/antora/latest/component-version-descriptor/[component descriptor]. It identifies the repository as an Antora content component and provides metadata used when the site is assembled. +The `antora.yml` file at the repository root is the Antora https://docs.antora.org/antora/latest/component-version-descriptor/[component descriptor]. It serves two purposes: it identifies the repository as an Antora content component, and it provides the component metadata and configuration (name, title, version, navigation, and AsciiDoc attributes) used when the documentation site is assembled. [source,yaml] ---- From 0bf32948257a16917d8e0a489b84860fc9a6bf0c Mon Sep 17 00:00:00 2001 From: wmat Date: Wed, 10 Jun 2026 14:28:55 -0400 Subject: [PATCH 10/26] Addressing feedback. Signed-off-by: Bill Traynor wmat@riscv.org --- src/antora-structure.adoc | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index aafd799..c2cf806 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -19,18 +19,22 @@ modules/ spec-sample.adoc intro.adoc chapter2.adoc + example.bib <7> ... + partials/ <8> ---- -<1> Antora component descriptor — identifies this repo as an Antora component. +<1> Antora component descriptor — identifies this repo as an Antora component and provides component metadata and configuration. <2> Makefile — drives the PDF/HTML build. <3> Git submodule providing shared fonts, themes, and images. <4> Navigation file — defines the sidebar structure for the Antora site. <5> Symlink to `docs-resources/images` so Antora can find shared images. <6> All AsciiDoc source files live here. +<7> BibTeX bibliography file. Referenced by `spec-sample.adoc` via the `:bibtex-file:` attribute. +<8> Optional directory for reusable AsciiDoc fragments (partials), such as Wavedrom diagram source files or content shared across chapters. Reference partials with `include::partial$filename.adoc[]`. === antora.yml -The `antora.yml` file at the repository root is the Antora https://docs.antora.org/antora/latest/component-version-descriptor/[component descriptor]. It identifies the repository as an Antora content component and provides metadata used when the site is assembled. +The `antora.yml` file at the repository root is the Antora https://docs.antora.org/antora/latest/component-version-descriptor/[component descriptor]. It serves two purposes: it identifies the repository as an Antora content component, and it provides the component metadata and configuration (name, title, version, navigation, and AsciiDoc attributes) used when the documentation site is assembled. [source,yaml] ---- From d64a5a5d9708062cd437927bae3b6f3bda842abb Mon Sep 17 00:00:00 2001 From: Bill Traynor Date: Wed, 10 Jun 2026 15:10:58 -0400 Subject: [PATCH 11/26] Update src/authoring.adoc Co-authored-by: Kersten Richter Signed-off-by: Bill Traynor --- src/authoring.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/authoring.adoc b/src/authoring.adoc index 3f5ab82..872e6d6 100644 --- a/src/authoring.adoc +++ b/src/authoring.adoc @@ -16,7 +16,7 @@ The docs-spec-template repo contains assets such as fonts, styles, directory str A https://github.com/riscv/docs-dev-guide/blob/main/local_build.md[local build guide] takes you through the local install process that supports all of the required features. -Although testing your markup by building a PDF is good practice, you can catch many common errors by simply downloading Asciidoctor and building the HTML output using the following command from the repository root: +Although testing your markup by building a PDF is a good practice, you can catch many common errors by downloading Asciidoctor and building the HTML output using the following command from the repository root: [source,cmd] ---- From 46808466ddcd959ad7b9988897cb4493e1f4df79 Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 08:58:55 -0400 Subject: [PATCH 12/26] Use repository, not repo. Vale is keeping me honest. Replacing repo with repository. Signed-off-by: Bill Traynor wmat@riscv.org --- src/a_few_basics.adoc | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc index 5629fec..272c76e 100644 --- a/src/a_few_basics.adoc +++ b/src/a_few_basics.adoc @@ -88,7 +88,7 @@ The following example is a valid sequence of headers. Index ``` -NOTE: Settings in the header file (`modules/ROOT/pages/spec-sample.adoc` in the docs-spec-template repo) trigger auto-generation of Appendix prefixes and of the Index (among other things). +NOTE: Settings in the header file (`modules/ROOT/pages/spec-sample.adoc` in the docs-spec-template repository) trigger auto-generation of Appendix prefixes and of the Index (among other things). === Lists @@ -331,7 +331,7 @@ Either table renders with table headers. ==== Table captions -The `modules/ROOT/pages/spec-sample.adoc` file in the docs-spec-template repo sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style. +The `modules/ROOT/pages/spec-sample.adoc` file in the docs-spec-template repository sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style. To set a caption for a table or image, use the pattern as follows: @@ -944,4 +944,3 @@ TIP: They can contain any type of content, including admonitions like this, and const { expect, expectCalledWith, heredoc } = require('../test/test-utils') ---- **** - From 345e33f63df87e63be2f41d724da1981c7b097f4 Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 09:12:08 -0400 Subject: [PATCH 13/26] Replace appendices with appendixes Vale doesn't like appendices, so replacing with appendixes. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/a_few_basics.adoc | 2 +- src/antora-structure.adoc | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc index 272c76e..d180d9c 100644 --- a/src/a_few_basics.adoc +++ b/src/a_few_basics.adoc @@ -331,7 +331,7 @@ Either table renders with table headers. ==== Table captions -The `modules/ROOT/pages/spec-sample.adoc` file in the docs-spec-template repository sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style. +The `modules/ROOT/pages/spec-sample.adoc` file in the docs-spec-template repository sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. You can set captions for tables, blocks, and illustrations. If you do not offer a caption, Asciidoctor defaults to the _basic_ cross-reference style. To set a caption for a table or image, use the pattern as follows: diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index c2cf806..10b969e 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -119,7 +119,7 @@ The `component` name in the comment must match the `name` field in your `antora. ==== Adding numbering rules -The playbook uses custom extensions to number chapters and appendices in the site navigation. Add a corresponding entry for your specification to both the `nav_numbering_extension` and `section_numbering_extension` blocks. Both blocks share the same rules via a YAML anchor (`&numbering_rules` / `*numbering_rules`), so you only need to add your entry once, in the `nav_numbering_extension` block: +The playbook uses custom extensions to number chapters and appendixes in the site navigation. Add a corresponding entry for your specification to both the `nav_numbering_extension` and `section_numbering_extension` blocks. Both blocks share the same rules via a YAML anchor (`&numbering_rules` / `*numbering_rules`), so you only need to add your entry once, in the `nav_numbering_extension` block: [source,yaml] ---- @@ -134,7 +134,7 @@ The playbook uses custom extensions to number chapters and appendices in the sit <2> Use `ROOT` for single-module specifications (the standard case). <3> Must match the branch name(s) listed in your `content.sources` entry. <4> The range of nav entries (top-level `*` items in `nav.adoc`) that are numbered chapters. Count from the first entry in `nav.adoc` — entries before your first chapter (e.g., a preface or overview page) are typically at position 1–4. -<5> Omit this line entirely if your specification has no appendices. +<5> Omit this line entirely if your specification has no appendixes. ==== Submitting the pull request From 2f0cbbddb24423d674a08b0678b13f3178e92b03 Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 09:33:33 -0400 Subject: [PATCH 14/26] Vale fixes Fixed some issues flagged by Vale such as passive voice, etc. Signed-off-by: Bill Traynor wmat@riscv.org --- src/antora-structure.adoc | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index 10b969e..e5ccb7d 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -1,11 +1,11 @@ [[antora-structure]] == Antora repository structure -RISC-V specification repositories use an https://docs.antora.org[Antora]-compatible directory structure. This enables individual specification repositories to be assembled into the RISC-V documentation site by Antora while also supporting a standalone PDF and HTML build via `make`. +RISC-V specification repositories use an https://docs.antora.org[Antora]-compatible directory structure. This enables Antora to assemble individual specification repositories into the RISC-V documentation site while also supporting a standalone PDF and HTML build using `make`. === Repository layout -A specification repository contains the following top-level files and directories: +A specification repository has the following top-level files and directories: ---- antora.yml <1> @@ -23,10 +23,10 @@ modules/ ... partials/ <8> ---- -<1> Antora component descriptor — identifies this repo as an Antora component and provides component metadata and configuration. -<2> Makefile — drives the PDF/HTML build. +<1> Antora component descriptor: identifies this repo as an Antora component and provides component metadata and configuration. +<2> Makefile: drives the PDF/HTML build. <3> Git submodule providing shared fonts, themes, and images. -<4> Navigation file — defines the sidebar structure for the Antora site. +<4> Navigation file: defines the sidebar structure for the Antora site. <5> Symlink to `docs-resources/images` so Antora can find shared images. <6> All AsciiDoc source files live here. <7> BibTeX bibliography file. Referenced by `spec-sample.adoc` via the `:bibtex-file:` attribute. @@ -34,7 +34,7 @@ modules/ === antora.yml -The `antora.yml` file at the repository root is the Antora https://docs.antora.org/antora/latest/component-version-descriptor/[component descriptor]. It serves two purposes: it identifies the repository as an Antora content component, and it provides the component metadata and configuration (name, title, version, navigation, and AsciiDoc attributes) used when the documentation site is assembled. +The `antora.yml` file at the repository root is the Antora https://docs.antora.org/antora/latest/component-version-descriptor/[component descriptor] and serves two purposes: it identifies the repository as an Antora content component, and it provides the component metadata and configuration (name, title, version, navigation, and AsciiDoc attributes) that Antora uses to assemble the documentation site. [source,yaml] ---- @@ -44,9 +44,9 @@ version: ~ <3> nav: - modules/ROOT/nav.adoc <4> ---- -<1> Component name — used in Antora cross-references from other components (`xref:spec-sample:page.adoc[]`). Rename to match your specification. +<1> Component name: used in Antora cross-references from other components (`xref:spec-sample:page.adoc[]`). Rename to match your specification. <2> Human-readable title shown in the site UI. Update this for your specification. -<3> `~` means unversioned. Set to a version string (e.g., `1.0`) once the specification is released. +<3> `~` means unversioned. Set to a version string (e.g., `1.0`) when you release the specification. <4> Path to the navigation file, relative to `antora.yml`. When creating a new specification repository from the template, at minimum rename `name` and `title` to match your specification. @@ -80,25 +80,25 @@ Add a new entry here each time you add a chapter to `pages/`. The order of entri === modules/ROOT/images/ -This directory is a symlink to `docs-resources/images`, which contains the shared RISC-V logo and other common images. Antora requires images to be located within the module directory tree, which is why the symlink exists rather than referencing `docs-resources/` directly. +This directory is a symlink to `docs-resources/images`, which hasshared RISC-V logo and other common images. Antora requries locating images in the module directory tree, which is why the symlink exists rather than referencing `docs-resources/` directly. -Place any specification-specific images in this directory alongside the symlinked shared images, or manage them via the symlink target in `docs-resources/`. +Place any specification-specific images in this directory alongside the symlinked shared images, or manage them by using the symlink target in `docs-resources/`. [[dev-playbook]] === Publishing to the RISC-V documentation site -The RISC-V documentation site is assembled from all specification repositories by a central Antora playbook maintained at https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org]. Specification authors do not manage their own playbook — instead, they submit a pull request to that repository to register their specification as a content source. +A central Antora playbook maintained at https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org] assembles the RISC-V documentation site from all specification repositories. Specification authors do not manage their own playbook. Instead, they submit a pull request to that repository to register their specification as a content source. ==== Naming your branch -By convention, Antora-ready branches are named with the version and an `-antora` suffix: +By convention, name Antora-ready branches with the version and an `-antora` suffix: ---- v1.0-antora v20250312-antora ---- -Create this branch from your specification's release tag or working branch once the Antora directory structure is in place. +Create this branch from your specification's release tag or working branch after the Antora directory structure is in place. ==== Adding a content source @@ -115,11 +115,11 @@ In the playbook at `antora/antora-playbook.yml`, add an entry to the `content.so submodules: true ---- -The `component` name in the comment must match the `name` field in your `antora.yml`. Set `submodules: true` if your repository uses git submodules (e.g., `docs-resources`). Set `worktrees: true` if your repository contains symlinks. +The `component` name in the comment must match the `name` field in your `antora.yml`. Set `submodules: true` if your repository uses git submodules (e.g., `docs-resources`). Set `worktrees: true` if your repository has symlinks. ==== Adding numbering rules -The playbook uses custom extensions to number chapters and appendixes in the site navigation. Add a corresponding entry for your specification to both the `nav_numbering_extension` and `section_numbering_extension` blocks. Both blocks share the same rules via a YAML anchor (`&numbering_rules` / `*numbering_rules`), so you only need to add your entry once, in the `nav_numbering_extension` block: +The playbook uses custom extensions to number chapters and appendixes in the site navigation. Add a corresponding entry for your specification to both the `nav_numbering_extension` and `section_numbering_extension` blocks. Both blocks share the same rules from a YAML anchor (`&numbering_rules` / `*numbering_rules`), so you only need to add a single entry in the 'nav_numbering_extension` block: [source,yaml] ---- @@ -133,19 +133,19 @@ The playbook uses custom extensions to number chapters and appendixes in the sit <1> Must match the `name` in your `antora.yml`. <2> Use `ROOT` for single-module specifications (the standard case). <3> Must match the branch name(s) listed in your `content.sources` entry. -<4> The range of nav entries (top-level `*` items in `nav.adoc`) that are numbered chapters. Count from the first entry in `nav.adoc` — entries before your first chapter (e.g., a preface or overview page) are typically at position 1–4. +<4> The range of nav entries (top-level `*` items in `nav.adoc`) to number as chapters. Count from the first entry in `nav.adoc` — entries before your first chapter (e.g., a preface or overview page) are typically at position 1 through 4. <5> Omit this line entirely if your specification has no appendixes. ==== Submitting the pull request . Fork or branch https://github.com/riscv-admin/antora-dev.riscv.org[riscv-admin/antora-dev.riscv.org]. . Add your content source and numbering rules to `antora/antora-playbook.yml` as described above. -. Open a pull request against the `main` branch with a brief description of the specification being added. +. Open a pull request against the `main` branch with a brief description of the specification added. [[install-antora]] === Installing Antora -Antora is needed to run a local site preview. It requires Node.js version 18 or later. Once Node.js is installed, install Antora globally: +You need Antora to run a local site preview. It requires Node.js version 18 or later. Once you install Node.js, install Antora globally: [source,cmd] ---- From b1aa801bfb4db6cb289c7cfd0836bc399e2abc80 Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 09:53:08 -0400 Subject: [PATCH 15/26] More fixes to satisfy Vale Removal of some passive voice issues, etc. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/a_few_basics.adoc | 57 ++++++++++++++++++++----------------------- 1 file changed, 27 insertions(+), 30 deletions(-) diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc index d180d9c..9f230ee 100644 --- a/src/a_few_basics.adoc +++ b/src/a_few_basics.adoc @@ -1,10 +1,7 @@ [[a_few_basics]] == AsciiDoc basics -pseudoinstruction -pseudo-instruction - -AsciiDoc is fully documented, and its documentation is actively maintained. This document contains some information on AsciiDoc markup to get you started. +AsciiDoc is fully documented, and its documentation is actively maintained. This document has information about AsciiDoc markup to get you started. For details and additional options, see: @@ -14,7 +11,7 @@ For details and additional options, see: In addition, you can ask questions in -Best practice is to test the PDF build frequently to ensure that you have not accidentally introduced something that breaks the build. +Best practice is to test the PDF build often to ensure that you have not accidentally introduced something that breaks the build. [NOTE] ==== @@ -25,7 +22,7 @@ Send questions to help@riscv.org. In AsciiDoc, normal paragraphs do not require markup. -To create a new paragraph, put a space after the previous line of text and continue. +To create a new paragraph, put a space after the earlier line of text and continue. ==== Basics of blocks and indents @@ -33,12 +30,12 @@ To create a new paragraph, put a space after the previous line of text and conti * You can add indented, explanatory paragraphs to lists. + -Add a `+` directly above the line of text that you want to be indented within the list. +Add a `+` directly preceding the line of text that you want to indent within the list. * Another point. + Using the `+` to create an indented paragraph works only within the context of a numbered or bulleted list. -AsciiDoc/Asciidoctor supports code blocks with syntax highlighting for many languages. You can use either periods or dashes to indicate code blocks, and use macros to indicate that the block contains code in the specified language, as in the following example: +AsciiDoc/Asciidoctor supports code blocks with syntax highlighting for many languages. You can use either periods or dashes to indicate code blocks, and use macros to indicate that the block has code in the specified language, as in the following example: [source,adoc] @@ -92,7 +89,7 @@ NOTE: Settings in the header file (`modules/ROOT/pages/spec-sample.adoc` in the === Lists -Unordered lists are created with the `*` before the list item. Ordered lists require a `.` Add a space between any supporting text at the beginning of a list. +Create unordered lists with the `*` before the list item. Ordered lists require a `.` Add a space between any supporting text at the beginning of a list. ==== Unordered list @@ -167,7 +164,7 @@ Example output: .. second nested item . back to original level. -You can also create an unordered list that contains a nested ordered list (or an ordered list that contains a nested unordered list). +You can also create an unordered list that has a nested ordered list (or an ordered list that has a nested unordered list). [source,adoc] ---- @@ -249,9 +246,9 @@ Follow these general rules when you create a table. * Avoid tables in the middle of lists. * Do not use tables to lay out a page. For example, if you have a long list of items, do not use a 2 column table to save space. The information should make sense side by side. -* Do not create a table that has a single row or a single column, unless you are following a previous layout. For example, if each section in a chapter includes a table of options, then use a table even if one of the sections has only a single option. +* Do not create a table that has a single row or a single column, unless you are following an earlier layout. For example, if each section in a chapter includes a table of options, then use a table even if one of the sections has only a single option. * Always use table headers and captions to make your tables more accessible. -* Use introductory sentences for your table. For example, "The following table contains the options for the CSR." You can use either a period or a colon for your introductory sentence. +* Use introductory sentences for your table. For example, "The following table has the options for the CSR." You can use either a period or a colon for your introductory sentence. * Do not refer to the "table above" or the "below table". Use words such as "The following table" or "The preceeding table". [WARNING] @@ -369,7 +366,7 @@ kind of trap. ==== AsciiDoc tables from CSV data. -AsciiDoc tables can also be created directly from CSV data. Set the format block attribute to `csv` and insert the data inside the block delimiters directly: +You can also create AsciiDoc tables directly from CSV data. Set the format block attribute to `csv` and insert the data inside the block delimiters directly: [source,adoc] ---- @@ -381,7 +378,7 @@ The Lumineers,Ho Hey,Folk Rock |=== ---- -The previous example renders as follows: +The prior example renders as follows: [%header,format=csv] |=== @@ -391,7 +388,7 @@ The Lumineers,Ho Hey,Folk Rock |=== -There are numerous formatting options available. While some of the property settings are cryptic, they can be quite useful. There are numerous examples available at https://asciidoc.org/newtables.html. Here one example of what can be done with spans alignment in tables from that page: +There are many formatting options available. While some of the property settings are cryptic, they can be quite useful. There are examples available at https://asciidoc.org/newtables.html. Here is an example showing spans alignment in tables from that page: [source,adoc] ---- @@ -416,7 +413,7 @@ Which renders as follows: The following example is code for a numbered encoding table with link target. -NOTE: Annotations have been added to the code to illustrate their use. +NOTE: We have added annotations to the code to illustrate their use. [source,adoc] ---- @@ -435,7 +432,7 @@ NOTE: Annotations have been added to the code to illustrate their use. . Link target. . Numbered table title. -The previous example results in the following table. +The earlier example results in the following table. [#proposed-16bit-encodings-1] .proposed 16-bit encodings-1 @@ -451,11 +448,11 @@ The previous example results in the following table. === Unicode symbols -For PDFs, five-digit unicode symbols generally don't work and some other unicode symbols are buggy. This failure happens because the Ruby asciidoctor-pdf toolchain makes use of Prawn to build PDFs and it's Prawn that has the problems. +For PDFs, five-digit unicode symbols generally do not work and some other unicode symbols are buggy. This failure happens because the Ruby asciidoctor-pdf toolchain makes use of Prawn to build PDFs and it is Prawn that has the problems. Here are a few unicode examples from https://en.wikipedia.org/wiki/List_of_XML_and_HTML_character_entity_references that might be useful: -As an example, ♦ is encoded as follows: +As an example, encode ♦ as follows: ```unicode ♦ @@ -510,7 +507,7 @@ sym,num,name === Mathematical notations -WARNING: Asciidoctor-mathematical has some limitations. For inline expressions, the graphical representations appear small and they are centered vertically. In some cases where there is a single-character Asciidoctor-mathematical expression, it unintentionally looks like a superscript. For this reason, always use viable alternatives like _italics_ or unicode (see <>). +WARNING: Asciidoctor-mathematical has some limitations. For inline expressions, the graphical representations are displayed small and center vertically. In some cases where there is a single-character Asciidoctor-mathematical expression, it unintentionally is displayed as a superscript. For this reason, always use viable options such as _italics_ or unicode (see <>). ==== Superscripts and subscripts @@ -572,14 +569,14 @@ latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$] [TIP] ==== -Latexmath rendering has some limitations with respect to sizing and placement inline. This happens because of how the images for the mathematical symbols are rendered within the build process. For this reason, please avoid using single character latexmath expressions inline and preferentially make use of unicode or superscripts and subscripts when possible. +Latexmath rendering has some limitations with respect to sizing and placement inline. This happens because of how the images for the mathematical renders symbols within the build process. For this reason, avoid using single character latexmath expressions inline and preferentially make use of unicode or superscripts and subscripts when possible. ==== ==== Stem content The `:stem: latexmath` setting makes use of asciidoctor-mathematical for asciidoctor-pdf output. -Asciidoctor Mathematical is a Ruby gem that uses native extensions. It has a few system prerequisites which limit installation to Linux and macOS. Please refer to the https://github.com/riscv/docs-templates[README in the RISC-V docs-templates repo] for information on the asciidoctor-mathematical install. +Asciidoctor Mathematical is a Ruby gem that uses native extensions. It has a few system prerequisites that limit installation to Linux and macOS. See the https://github.com/riscv/docs-templates[README in the RISC-V docs-templates repo] for information on the asciidoctor-mathematical install. [source,adoc] ---- @@ -594,7 +591,7 @@ sqrt(4) = 2 sqrt(4) = 2 ++++ -In some cases, you might want to make use of unicode characters. Keep in mind that asciidoctor-pdf supports only decimal character references. See https://github.com/asciidoctor/asciidoctor-pdf/issues/486 +In some cases, you might want to make use of unicode characters. Remember that asciidoctor-pdf supports only decimal character references. See https://github.com/asciidoctor/asciidoctor-pdf/issues/486 For updates to asciidoctor-pdf, see https://github.com/asciidoctor/asciidoctor-pdf. @@ -621,14 +618,14 @@ Important:: Information that a user must have. For example, "After you set your IMPORTANT: example of important type -Tip:: Used for Non-normative text such as clarification or hints for implementers or to convey design rationale and why other options were discontinued. RISC-V tech team is working on a solution that will allow these admonitions to be turned off. +Tip:: Used for Non-normative text such as clarification or hints for implementers or to convey design rationale and why the team discontinued other options. RISC-V tech team is working on a solution that enables users to turn off these admonitions. TIP: example of tip type As a general rule, follow these guidelines for admonitions: * Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. -* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition. +* If the information is necessary, make it part of the topic and even add a heading. do not put it in an admonition. * Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) * Do not include results, steps, or prerequisites in admonitions. * Make your admonition clear and concise. @@ -642,7 +639,7 @@ For a single paragraph admonition, use a double colon: NOTE: Note content. ---- -which renders as: +that renders as: NOTE: Note content. @@ -664,14 +661,14 @@ As a general rule, follow these guidelines for admonitions: ==== ---- -which renders as: +that renders as: [IMPORTANT] ==== As a general rule, follow these guidelines for admonitions: * Understand that admonitions are interruptions. They should be relevant to the topic, but not necessary. If the reader skips reading it, they can still succeed. -* If the information is necessary, make it part of the topic and even add a heading. Don't put it in an admonition. +* If the information is necessary, make it part of the topic and even add a heading. do not put it in an admonition. * Limit admonitions to a maximum of 3 on a page (standard PDF page - longer HTML pages can use more.) * Do not include results, steps, or prerequisites in admonitions. * Make your admonition clear and concise. @@ -686,7 +683,7 @@ You can add a title to your admonition block. [WARNING] .Security vulnerability ==== -*Be aware that RLB introduces a security vulnerability if it is set after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn’t make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*. +*Be aware that RLB introduces a security vulnerability if you set iiiiiit after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn't make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*. ==== ---- @@ -695,7 +692,7 @@ Rendered: [WARNING] .Security vulnerability ==== -*Be aware that RLB introduces a security vulnerability if it is set after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It doesn’t make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*. +*Be aware that RLB introduces a security vulnerability if you set it after the boot process is over.* Use with caution, even when you use it temporarily. Editable PMP rules in M-mode gives a false sense of security since it only takes a few malicious instructions to lift any PMP restrictions this way. It does not make sense to have a security control in place and leave it unprotected. Rule Locking Bypass is only meant as a way to optimize the allocation of PMP rules, catch errors durring debugging, and allow the bootrom/firmware to register executable _Shared-Region_ rules. If developers / vendors have no use for such functionality, they should never set ``mseccfg.RLB`` and if possible hard-wire it to 0. In any case *RLB should be disabled and locked as soon as possible*. ==== ==== RISC-V admonition icon colors From 76e9f6dd52a0e4fbdee08942e2690e95b073f08a Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 09:54:46 -0400 Subject: [PATCH 16/26] Replace Fatal with unrecoverable. Replacing the word Fatal with unrecoverable. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/a_few_basics.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc index 9f230ee..e9ec6f5 100644 --- a/src/a_few_basics.adoc +++ b/src/a_few_basics.adoc @@ -357,7 +357,7 @@ kind of trap. .Characteristics of traps. [cols="<,^,^,^,^",options="header",] |=== -| |Contained |Requested |Invisible |Fatal +| |Contained |Requested |Invisible |Unrecoverable |Execution terminates |No |Nolatexmath:[$^{1}$] |No |Yes |Software is oblivious |No |No |Yes |Yeslatexmath:[$^{2}$] |Handled by environment |No |Yes |Yes |Yes From 7036154356bb22ffbcace89dd13d591148c161c3 Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 10:06:09 -0400 Subject: [PATCH 17/26] Added git-submodules descriptor. Was missing the docs-resources indicator. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/antora-structure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index e5ccb7d..b1bc660 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -25,7 +25,7 @@ modules/ ---- <1> Antora component descriptor: identifies this repo as an Antora component and provides component metadata and configuration. <2> Makefile: drives the PDF/HTML build. -<3> Git submodule providing shared fonts, themes, and images. +<3> docs-resources: Git submodule providing shared fonts, themes, and images. <4> Navigation file: defines the sidebar structure for the Antora site. <5> Symlink to `docs-resources/images` so Antora can find shared images. <6> All AsciiDoc source files live here. From cd303f5362b8e2c093d11d56a8406e9c80a880b3 Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 10:09:48 -0400 Subject: [PATCH 18/26] Describe the nav file better. Expanded on the nav.adoc file description as per KR's suggestion. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/antora-structure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index b1bc660..71936c1 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -26,7 +26,7 @@ modules/ <1> Antora component descriptor: identifies this repo as an Antora component and provides component metadata and configuration. <2> Makefile: drives the PDF/HTML build. <3> docs-resources: Git submodule providing shared fonts, themes, and images. -<4> Navigation file: defines the sidebar structure for the Antora site. +<4> nav.adoc file: the navigation file that defines the sidebar structure for the Antora site. <5> Symlink to `docs-resources/images` so Antora can find shared images. <6> All AsciiDoc source files live here. <7> BibTeX bibliography file. Referenced by `spec-sample.adoc` via the `:bibtex-file:` attribute. From 9014732cc060b4b9449587d7100d73ff350eba2b Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 10:12:04 -0400 Subject: [PATCH 19/26] Itemize pages directory. Added in the name of the pages directory that was omitted. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/antora-structure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index 71936c1..5344f98 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -28,7 +28,7 @@ modules/ <3> docs-resources: Git submodule providing shared fonts, themes, and images. <4> nav.adoc file: the navigation file that defines the sidebar structure for the Antora site. <5> Symlink to `docs-resources/images` so Antora can find shared images. -<6> All AsciiDoc source files live here. +<6> Pages direcotory: all AsciiDoc source files live here. <7> BibTeX bibliography file. Referenced by `spec-sample.adoc` via the `:bibtex-file:` attribute. <8> Optional directory for reusable AsciiDoc fragments (partials), such as Wavedrom diagram source files or content shared across chapters. Reference partials with `include::partial$filename.adoc[]`. From 597ffc8efeefeb5e73e987d795e655cef024409b Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 10:14:57 -0400 Subject: [PATCH 20/26] Added resource file description. Added in the missing Resources file. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/antora-structure.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index 5344f98..630db3f 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -28,8 +28,8 @@ modules/ <3> docs-resources: Git submodule providing shared fonts, themes, and images. <4> nav.adoc file: the navigation file that defines the sidebar structure for the Antora site. <5> Symlink to `docs-resources/images` so Antora can find shared images. -<6> Pages direcotory: all AsciiDoc source files live here. -<7> BibTeX bibliography file. Referenced by `spec-sample.adoc` via the `:bibtex-file:` attribute. +<6> Pages directory: all AsciiDoc source files live here. +<7> Resources directory: resource files that are not asciidoc or images such as the bibliography file. Referenced by `spec-sample.adoc` via the `:bibtex-file:` attribute. <8> Optional directory for reusable AsciiDoc fragments (partials), such as Wavedrom diagram source files or content shared across chapters. Reference partials with `include::partial$filename.adoc[]`. === antora.yml From 7fab7d5d87f23362c57c33985e35af5fe6f2cf74 Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 10:22:42 -0400 Subject: [PATCH 21/26] Explain antora.yml attributes with example. Added name and title attribute example from Debug. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/antora-structure.adoc | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index 630db3f..ba5f57c 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -27,10 +27,10 @@ modules/ <2> Makefile: drives the PDF/HTML build. <3> docs-resources: Git submodule providing shared fonts, themes, and images. <4> nav.adoc file: the navigation file that defines the sidebar structure for the Antora site. -<5> Symlink to `docs-resources/images` so Antora can find shared images. +<5> Images: Symlink to `docs-resources/images` so Antora can find shared images. <6> Pages directory: all AsciiDoc source files live here. <7> Resources directory: resource files that are not asciidoc or images such as the bibliography file. Referenced by `spec-sample.adoc` via the `:bibtex-file:` attribute. -<8> Optional directory for reusable AsciiDoc fragments (partials), such as Wavedrom diagram source files or content shared across chapters. Reference partials with `include::partial$filename.adoc[]`. +<8> Partials directory: Optional directory for reusable AsciiDoc fragments (partials), such as Wavedrom diagram source files or content shared across chapters. Reference partials with `include::partial$filename.adoc[]`. === antora.yml @@ -44,12 +44,15 @@ version: ~ <3> nav: - modules/ROOT/nav.adoc <4> ---- -<1> Component name: used in Antora cross-references from other components (`xref:spec-sample:page.adoc[]`). Rename to match your specification. +<1> Component name: used in Antora cross-references from other components (`xref:spec-sample:page.adoc[]`). Rename to match your specification. This attribute is used in the URL. <2> Human-readable title shown in the site UI. Update this for your specification. <3> `~` means unversioned. Set to a version string (e.g., `1.0`) when you release the specification. <4> Path to the navigation file, relative to `antora.yml`. -When creating a new specification repository from the template, at minimum rename `name` and `title` to match your specification. +When creating a new specification repository from the template, at minimum rename `name` and `title` to match your specification. For example, the Debug Specification uses: + +name: debug +title: Debug Specification === modules/ROOT/pages/ From a85bdb03467fe346aaca9e9db268a944aa8756a3 Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 10:25:26 -0400 Subject: [PATCH 22/26] Add version numbering Add suggestion for numbering development versions. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/antora-structure.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index ba5f57c..a98dd80 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -46,10 +46,10 @@ nav: ---- <1> Component name: used in Antora cross-references from other components (`xref:spec-sample:page.adoc[]`). Rename to match your specification. This attribute is used in the URL. <2> Human-readable title shown in the site UI. Update this for your specification. -<3> `~` means unversioned. Set to a version string (e.g., `1.0`) when you release the specification. +<3> `~` means unversioned. Set to a version string (e.g., `1.0`) when you release the specification. During development, use standard two digit versioning such as 0.1, 0.2, etc. <4> Path to the navigation file, relative to `antora.yml`. -When creating a new specification repository from the template, at minimum rename `name` and `title` to match your specification. For example, the Debug Specification uses: +When creating a new specification repository from the template, at minimum rename `name` and `title` to match your specification. For example, the Debug Specification uses: name: debug title: Debug Specification From 8bf51733e3060136de06776a1a9dde1b0559097a Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 10:28:43 -0400 Subject: [PATCH 23/26] Fixing description of nav attribute. Added the description of the nav attribute. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/antora-structure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index a98dd80..5bc1ebc 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -47,7 +47,7 @@ nav: <1> Component name: used in Antora cross-references from other components (`xref:spec-sample:page.adoc[]`). Rename to match your specification. This attribute is used in the URL. <2> Human-readable title shown in the site UI. Update this for your specification. <3> `~` means unversioned. Set to a version string (e.g., `1.0`) when you release the specification. During development, use standard two digit versioning such as 0.1, 0.2, etc. -<4> Path to the navigation file, relative to `antora.yml`. +<4> nav: Path to the navigation file, relative to `antora.yml`. Using the template for non-ISA specifications, this should always be the same path, i.e. modules/ROOT/nav.adoc. When creating a new specification repository from the template, at minimum rename `name` and `title` to match your specification. For example, the Debug Specification uses: From 0d8e6f468200b80b4ed640498d568c6a16d832b4 Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 10:34:20 -0400 Subject: [PATCH 24/26] Describe page-group and other attributes. Described the page-group attribute and others. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/antora-structure.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index 5bc1ebc..fb1b17f 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -49,7 +49,7 @@ nav: <3> `~` means unversioned. Set to a version string (e.g., `1.0`) when you release the specification. During development, use standard two digit versioning such as 0.1, 0.2, etc. <4> nav: Path to the navigation file, relative to `antora.yml`. Using the template for non-ISA specifications, this should always be the same path, i.e. modules/ROOT/nav.adoc. -When creating a new specification repository from the template, at minimum rename `name` and `title` to match your specification. For example, the Debug Specification uses: +When creating a new specification repository from the template, set the page-group attribute to "development" and update it to reflect specification state through the specification lifecycle. Update the `name` and `title` attributes to match your specification. For example, the Debug Specification uses: name: debug title: Debug Specification From 98d0cc42403eab158546e96464e24b75ade54e53 Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 10:38:12 -0400 Subject: [PATCH 25/26] Removed text about nested xrefs and updated description. As our nave isn't really nested, removed that wording. Better described the nav file. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/antora-structure.adoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index fb1b17f..22073f2 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -68,7 +68,7 @@ When adding a new chapter: === modules/ROOT/nav.adoc -The `nav.adoc` file defines the navigation sidebar shown in the Antora site. It uses a nested list of `xref:` macros. +The `nav.adoc` file defines the navigation sidebar shown in the Antora site. [source,adoc] ---- @@ -79,7 +79,7 @@ The `nav.adoc` file defines the navigation sidebar shown in the Antora site. It ** xref:bibliography.adoc[Bibliography] ---- -Add a new entry here each time you add a chapter to `pages/`. The order of entries controls the sidebar order. +Add a new entry here each time you add a chapter to `pages/`. The order of entries controls the left navigation order in the HTML version in the RISC-V Specifications Library. === modules/ROOT/images/ From c6e9839ba53d6b0964a0b0c47e38c742716f0add Mon Sep 17 00:00:00 2001 From: wmat Date: Tue, 14 Jul 2026 10:42:06 -0400 Subject: [PATCH 26/26] Updated images dir description. Removed incorrect description of what the images directory is. Signed-off-by: Bill Traynor wmat@riscv.org Signed-off-by: wmat --- src/antora-structure.adoc | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/src/antora-structure.adoc b/src/antora-structure.adoc index 22073f2..657086e 100644 --- a/src/antora-structure.adoc +++ b/src/antora-structure.adoc @@ -83,9 +83,7 @@ Add a new entry here each time you add a chapter to `pages/`. The order of entri === modules/ROOT/images/ -This directory is a symlink to `docs-resources/images`, which hasshared RISC-V logo and other common images. Antora requries locating images in the module directory tree, which is why the symlink exists rather than referencing `docs-resources/` directly. - -Place any specification-specific images in this directory alongside the symlinked shared images, or manage them by using the symlink target in `docs-resources/`. +Antora locates images in the module directory tree. Images used in the specification will be stored in the images directory. [[dev-playbook]] === Publishing to the RISC-V documentation site