diff --git a/modules/ROOT/pages/a_few_basics.adoc b/modules/ROOT/pages/a_few_basics.adoc index e9ec6f5..231815f 100644 --- a/modules/ROOT/pages/a_few_basics.adoc +++ b/modules/ROOT/pages/a_few_basics.adoc @@ -1,5 +1,5 @@ [[a_few_basics]] -== AsciiDoc basics += AsciiDoc basics AsciiDoc is fully documented, and its documentation is actively maintained. This document has information about AsciiDoc markup to get you started. @@ -18,13 +18,13 @@ Best practice is to test the PDF build often to ensure that you have not acciden Send questions to help@riscv.org. ==== -=== Paragraphs +== Paragraphs In AsciiDoc, normal paragraphs do not require markup. To create a new paragraph, put a space after the earlier line of text and continue. -==== Basics of blocks and indents +=== Basics of blocks and indents If you add an indent, your indented text becomes a block like this. @@ -57,7 +57,7 @@ add a1,a2,a3; # do an ADD See <> for additional information about blocks. -=== Headers +== Headers When you author in AsciiDoc, you cannot jump directly from a Head 1 to a Head 3 or 4. Your headers must appear in sequence from Head 1 to Head 2, and onward. If you skip over a header in the sequence, Asciidoctor throws an error. @@ -87,11 +87,11 @@ Index 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 +== Lists 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 +=== Unordered list To create an unordered list, place a `*` and a space before an item. Put each new list item on a new line. Add a space between any supporting text at the beginning of a list. @@ -110,7 +110,7 @@ Example output: * Unpriv * Debug -==== Ordered list +=== Ordered list To create an ordered (numbered) list, place a `.` and a space before an item. Put each new list item on a new line. Add a space between any supporting text at the beginning of a list. @@ -127,7 +127,7 @@ Example output: . Unpriv . Debug -==== Nested list +=== Nested list To create a nested unordered list, use `** ` before the nested item. @@ -181,7 +181,7 @@ Example output: .. second numbered item * another bullet -==== Add a title to a list +=== Add a title to a list Titles can help introduce your list content. @@ -200,14 +200,14 @@ Example output: . Unpriv . Debug -=== Hyperlinks and cross references +== Hyperlinks and cross references Asciidoctor automates some linking as follows: * Recognizes hyperlinks to Web pages and shortens them for readability. * Automatically creates an anchor for every section and discrete heading. -==== Hyperlinks +=== Hyperlinks To create highlighted links, use the pattern in the following example: @@ -219,7 +219,7 @@ https://asciidoctor.org[Asciidoctor] You can set https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro-ref/[attributes for your external links] -==== Cross references +=== Cross references Use macros for cross references (links within a document) as in the following example: @@ -236,12 +236,12 @@ For more information about options, see https://docs.asciidoctor.org/asciidoc/la [[tables_symbols_math]] -=== Tables +== Tables By using tables, you can group information into logical units, which can make the infromation presented easier to understand. [[tables-gen]] -==== General rules for tables +=== General rules for tables Follow these general rules when you create a table. * Avoid tables in the middle of lists. @@ -256,7 +256,7 @@ Follow these general rules when you create a table. *Never* use automated wrapping for table titles, figure captions, and example captions. Asciidoctor reads a hard return as an indicator to start a new "Normal" paragraph. ==== -==== Simple table +=== Simple table The following example shows a simple table with 2 rows and 2 columns. To indicate a new row, put a empty line between them. @@ -283,7 +283,7 @@ Results in the following table. |Cell in column 2, row 2 |=== -==== Adding table headers +=== Adding table headers Headers can add additional information to your table, making them easier to understand. @@ -326,7 +326,7 @@ Either table renders with table headers. |Cell in col 3, row 2 |=== -==== Table captions +=== 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. You can set captions for tables, blocks, and illustrations. If you do not offer a caption, Asciidoctor defaults to the _basic_ cross-reference style. @@ -364,7 +364,7 @@ kind of trap. |=== -==== AsciiDoc tables from CSV data. +=== AsciiDoc tables from CSV data. 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: @@ -446,7 +446,7 @@ The earlier example results in the following table. 3+|100|1|1|1 8+| field 2+| 00 | mnemonic4 |=== -=== Unicode symbols +== Unicode symbols 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. @@ -505,12 +505,12 @@ sym,num,name |=== -=== Mathematical notations +== Mathematical notations 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 +=== Superscripts and subscripts To indicate a superscript, enclose the string for the superscript in carets as in the following example: @@ -555,7 +555,7 @@ Renders as: of a shopping list, but I don't think the local bodega sells E=mc^2^," Lazarus replied. -==== Latexmath +=== Latexmath You can make use of LaTeX notation as in the following: @@ -572,7 +572,7 @@ latexmath:[$C = \alpha + \beta Y^{\gamma} + \epsilon$] 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 +=== Stem content The `:stem: latexmath` setting makes use of asciidoctor-mathematical for asciidoctor-pdf output. @@ -596,7 +596,7 @@ In some cases, you might want to make use of unicode characters. Remember that a For updates to asciidoctor-pdf, see https://github.com/asciidoctor/asciidoctor-pdf. [[blocks_notes_markers]] -=== Admonition blocks +== Admonition blocks Five types of standard link:https://docs.asciidoctor.org/asciidoc/latest/blocks/admonitions/[admonition blocks] are available in AsciiDoc. RISC-V uses these five types with the default icons. @@ -630,7 +630,7 @@ As a general rule, follow these guidelines for admonitions: * Do not include results, steps, or prerequisites in admonitions. * Make your admonition clear and concise. -==== Single paragraph admonition +=== Single paragraph admonition For a single paragraph admonition, use a double colon: @@ -643,7 +643,7 @@ that renders as: NOTE: Note content. -==== Admonition blocks +=== Admonition blocks An admonition block can contain any AsciiDoc content. @@ -674,7 +674,7 @@ As a general rule, follow these guidelines for admonitions: * Make your admonition clear and concise. ==== -==== Admonition with a title +=== Admonition with a title You can add a title to your admonition block. @@ -695,7 +695,7 @@ Rendered: *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 +=== RISC-V admonition icon colors The admonition icons are set in `risc-v_spec-pdf.yml`. RISC-V uses custom colors, as indicated in the <>. @@ -722,7 +722,7 @@ IMPORTANT,bf0000,b58f5b |=== -=== Code blocks +== Code blocks AsciiDoc enables code blocks that support syntax highlighting. @@ -787,7 +787,7 @@ With the following result: .... -=== Change bars +== Change bars Change indicators within text files are exceedingly useful and also can be equally complex to implement. Please consider the fact that much of the software programming for Git revolves around handling various kinds of change indicators. @@ -800,7 +800,7 @@ The suggested solution makes use of: - Git features. - a few procedures associated, specifically, with Git updates. -==== Indicate changes +=== Indicate changes Indicators for the changed lines must be inserted manually: @@ -826,7 +826,7 @@ For change bars associated with headings, place the change indicator after the h == [.Changed]#SELECT clause# ---- -==== Check for changed lines before a `git commit` +=== Check for changed lines before a `git commit` You can double check for all changed lines before committing by using this pattern: @@ -846,7 +846,7 @@ This lists the line numbers of changes within the specified file like the follow ---- -=== Footnotes +== Footnotes AsciiDoc has a limitation in that footnotes appear at the end of each chapter. Asciidoctor does not support footnotes appearing at the bottom of each page. @@ -877,7 +877,7 @@ A bold statement!footnote:disclaimer[Opinions are my own.] Another outrageous statement.footnote:disclaimer[] -=== Sidebars +== Sidebars Sidebars provide for a form of commentary. diff --git a/modules/ROOT/pages/antora-structure.adoc b/modules/ROOT/pages/antora-structure.adoc index 0411658..7a7e7b5 100644 --- a/modules/ROOT/pages/antora-structure.adoc +++ b/modules/ROOT/pages/antora-structure.adoc @@ -1,9 +1,9 @@ [[antora-structure]] -== Antora repository structure += Antora repository structure 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 +== Repository layout A specification repository has the following top-level files and directories: @@ -32,7 +32,7 @@ modules/ <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> 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 +== antora.yml 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. @@ -54,7 +54,7 @@ When creating a new specification repository from the template, set the page-gro name: debug title: Debug Specification -=== modules/ROOT/pages/ +== 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. @@ -62,11 +62,11 @@ The entry point for the standalone PDF and HTML build is `spec-sample.adoc`, whi 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). +. Create the `.adoc` file in `modules/ROOT/pages/`. Start it with a level-0 title, `= Chapter title`. Antora uses that line as the page title, so a page that starts with `==`, or has no title, is listed as "Untitled" on the site. +. Add an `include::` directive for it in `spec-sample.adoc` (for the PDF build), with a level offset: `include::../modules/ROOT/pages/my-chapter.adoc[leveloffset=+1]`. The offset turns the page's level-0 title into a chapter in the PDF. Without it, the PDF gets a second document title. . Add an `xref:` entry for it in `modules/ROOT/nav.adoc` (for the Antora site build). -=== modules/ROOT/nav.adoc +== modules/ROOT/nav.adoc The `nav.adoc` file defines the navigation sidebar shown in the Antora site. @@ -81,16 +81,16 @@ The `nav.adoc` file defines the navigation sidebar shown in the Antora site. 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/ +== modules/ROOT/images/ Antora locates images in the module directory tree. Store images used in the specification in the images directory. [[dev-playbook]] -=== Publishing to the RISC-V documentation site +== Publishing to the RISC-V documentation site 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 +=== Naming your branch By convention, name Antora-ready branches with the version and an `-antora` suffix: @@ -101,7 +101,7 @@ v20250312-antora Create this branch from your specification's release tag or working branch after the Antora directory structure is in place. -==== Adding a content source +=== 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: @@ -118,7 +118,7 @@ In the playbook at `antora/antora-playbook.yml`, add an entry to the `content.so 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 +=== 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 from a YAML anchor (`&numbering_rules` / `*numbering_rules`), so you only need to add a single entry in the 'nav_numbering_extension` block: @@ -137,14 +137,14 @@ The playbook uses custom extensions to number chapters and appendixes in the sit <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 +=== 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 added. [[install-antora]] -=== Installing Antora +== Installing Antora 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: diff --git a/modules/ROOT/pages/author-quickstart.adoc b/modules/ROOT/pages/author-quickstart.adoc index 352eb31..474dd3f 100644 --- a/modules/ROOT/pages/author-quickstart.adoc +++ b/modules/ROOT/pages/author-quickstart.adoc @@ -1,13 +1,13 @@ [[author-quickstart]] -== Template Quickstart: Writing a Spec += Template Quickstart: Writing a Spec This guide is for a specification author who has a GitHub repository that was created from the `docs-spec-template` repository. By using this template, you can single source your content for both PDF and the HTML output. You can use the GitHub repository actions to create build versions, interim releases, and milestone releases. Finally, you can build both the PDF and Antora HTML output locally by running the `makefile` and `npm` commands. -=== Before you begin +== Before you begin When your GitHub repository was created, the "spec-sample" identity is still baked in. Rename the files and update the metadata to reflect your spec's identity. -==== Rename your files +=== Rename your files The following table shows the files that you need to edit. @@ -72,7 +72,7 @@ As a reminder, be sure to update the `copyright.adoc` file and the `contributors // The admin normally sets this. If it is wrong, run `make set-mode MODE=doc` (or // `MODE=spec`) -- you do **not** need to re-create the repo. -==== Initialize the docs-resources repo +=== Initialize the docs-resources repo The docs-resources repo contains common utilities, graphics, and styling. Before you can use this repository, you must initialize it with the following command: @@ -83,9 +83,9 @@ git submodule update --remote --init After your submodule populates locally, you can use the repo contents to build your content locally. -=== Understand file structure +== Understand file structure -Create your chapter content `.adoc` files in the `modules/ROOT/pages/` location. Both the PDF and the HTML read these same files. The PDF is assembled by using the book header file (`src/.adoc`), which uses `include:` references to each chapter `.adoc` file. The HTML site navigation uses a navigation file (`modules/ROOT/nav.adoc`) to build HTML content. Update both of these files to keep the PDF and HTML content in synch. Otherwise, the source files remain the same for both PDF and HTML output. +Create your chapter content `.adoc` files in the `modules/ROOT/pages/` location. Both the PDF and the HTML read these same files. The PDF is assembled by using the book header file (`src/.adoc`), which uses `include::` references to each chapter `.adoc` file. Start each chapter file with a level-0 title (`= Chapter title`), and include it in the book header file with `leveloffset=+1` so that title becomes a chapter in the PDF. A chapter file without a level-0 title is listed as "Untitled" on the HTML site. The HTML site navigation uses a navigation file (`modules/ROOT/nav.adoc`) to build HTML content. Update both of these files to keep the PDF and HTML content in synch. Otherwise, the source files remain the same for both PDF and HTML output. [source] ---- @@ -120,7 +120,7 @@ Miss an `xref:` entry in the nav.adoc file and the chapter appears in the PDF bu Do not add PDF-only constructs or styling to the content chapter files. These types of changes are included in only the book header file. HTML styling is included in the Antora playbook as well as the Antora UI repository. -=== Building your content locally +== Building your content locally To build and view your content locally, run the following commands in your local repository. Start your docker instance before running these commands. @@ -140,11 +140,11 @@ the `make` PDF or on the HTML development site. To open your website locally, go to the `build` folder in your local specification directory and open the `index.html` file. -=== GitHub Action builds +== GitHub Action builds When you build your spec on GitHub, whether you are creating a PR or merging directly to main, the Actions workflow runs several actions, including building a PDF. It will not, however, increment your PDF version. -=== Understanding versioning +== Understanding versioning Versions are updated by using the Version-bot action in GitHub. After you run the Version-bot, a PR is created to update the version in the `antora.yml` file. Do not update the version manually; always run the Version-bot to change the version. Merge the Stamp Antora site version PDF as soon as possible. @@ -182,7 +182,7 @@ Versions are updated by using the Version-bot action in GitHub. After you run th ---- -=== Ratification ready +== Ratification ready When your spec development is complete and ratified, the RISC-V team creates a ratified version and publishes the document in the https://docs.riscv.org/[Ratified Specifications library]. @@ -204,7 +204,7 @@ When your spec development is complete and ratified, the RISC-V team creates a r // make stamp-antora VERSION=vX.Y.Z # then commit antora.yml // ---- -=== See also +== See also * `ANTORA.md` -- how the dual build works and why, plus the section-numbering rule and site-registration details. diff --git a/modules/ROOT/pages/authoring.adoc b/modules/ROOT/pages/authoring.adoc index 872e6d6..c76c92e 100644 --- a/modules/ROOT/pages/authoring.adoc +++ b/modules/ROOT/pages/authoring.adoc @@ -1,4 +1,4 @@ -== AsciiDoc authoring for RISC-V contributors += AsciiDoc authoring for RISC-V contributors AsciiDoc is the markup language and Asciidoctor is a set of toolchains that support publishing from AsciiDoc. @@ -8,7 +8,7 @@ Asciidoctor toolchains: * https://gitlab.com/antora/antora[antora], which is newer and written in javascript. * Python-based, which is legacy and in maintenance mode. -=== RISC-V AsciiDoc authoring assets +== RISC-V AsciiDoc authoring assets Please view the https://github.com/riscv/docs-spec-template[readme] in the docs-spec-template repo for information about the automated build processes. @@ -30,7 +30,7 @@ Or more simply, using the Makefile: make ---- -=== Writing +== Writing To begin writing in AsciiDoc, select a text editor. Here's <>. @@ -45,7 +45,7 @@ Here are a few additional, useful links: * https://docs.asciidoctor.org/asciidoc/latest/macros/link-macro-ref/[links] [[editors]] -==== Text editors with AsciiDoc support +=== Text editors with AsciiDoc support There isn't a true WYSIWYG editor for AsciiDoc. However, there are live preview options that are listed in the https://docs.asciidoctor.org/asciidoctor/latest/tooling/[Asciidoctor documentation] that can help you see what the output looks like. You can also use your favorite text editor, or perhaps switch to one that has good AsciiDoc linting. diff --git a/modules/ROOT/pages/bibliography.adoc b/modules/ROOT/pages/bibliography.adoc index 17be9b9..0516b94 100644 --- a/modules/ROOT/pages/bibliography.adoc +++ b/modules/ROOT/pages/bibliography.adoc @@ -1,5 +1,4 @@ -[bibliography] -== Bibliography += Bibliography bibliography::[] diff --git a/modules/ROOT/pages/build-infrastructure.adoc b/modules/ROOT/pages/build-infrastructure.adoc index 8aa233f..4e7986d 100644 --- a/modules/ROOT/pages/build-infrastructure.adoc +++ b/modules/ROOT/pages/build-infrastructure.adoc @@ -1,10 +1,10 @@ -== Build Infrastructure += Build Infrastructure Most RISC-V AsciiDoc documents use a `Makefile` to simplify the build process. For many documents, building the PDF and HTML flavors of the documents is as simple as going into the root directory of the document repository and typing `make`. If Docker is already installed, the `Makefile` will invoke `docker` for the build process. Otherwise, it will build natively. -=== Source directory +== 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`. @@ -77,7 +77,7 @@ 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 +== 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. @@ -88,7 +88,7 @@ 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 +== 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]. @@ -104,11 +104,11 @@ The specification has completed public review. Only critical bug fixes are permi 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 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 +=== 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. @@ -127,6 +127,6 @@ To publish a release at a new state: 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 +=== 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. diff --git a/modules/ROOT/pages/contributors.adoc b/modules/ROOT/pages/contributors.adoc index 6f1040b..fa75b6c 100644 --- a/modules/ROOT/pages/contributors.adoc +++ b/modules/ROOT/pages/contributors.adoc @@ -1,4 +1,4 @@ -== Contributors += Contributors This guide has been contributed to directly or indirectly by: diff --git a/modules/ROOT/pages/copyright.adoc b/modules/ROOT/pages/copyright.adoc index 4f30a57..96069af 100644 --- a/modules/ROOT/pages/copyright.adoc +++ b/modules/ROOT/pages/copyright.adoc @@ -1,5 +1,4 @@ -[preface] -== Copyright and license information += Copyright and license information This documentation is licensed under the Creative Commons Attribution 4.0 International License (CC-BY 4.0). The full diff --git a/modules/ROOT/pages/graphics.adoc b/modules/ROOT/pages/graphics.adoc index 6f77a1c..c986ed7 100644 --- a/modules/ROOT/pages/graphics.adoc +++ b/modules/ROOT/pages/graphics.adoc @@ -1,5 +1,5 @@ [[graphics]] -== Graphics += Graphics Graphics help people learn, break up text, and can overall improve your document content. @@ -15,7 +15,7 @@ The https://docs.asciidoctor.org/diagram-extension/latest/[asciidoctor-diagram e You can certainly use one of the other supported types, but know that they might cause issues with the build. Please contact the RISC-V docs team before using them. [[GBP]] -=== Graphics best practices +== Graphics best practices Follow these guidelines for graphics. @@ -27,7 +27,7 @@ Follow these guidelines for graphics. * Images should support your text. Do not put important information in only an image. [[wavedrom]] -=== Wavedrom diagrams in specifications +== Wavedrom diagrams in specifications Wavedrom diagrams are used mainly for registers. To specify a wavedrom file, create a `json` file and then call it from your text. For more information, see https://wavedrom.com/[WaveDrom sequence diagrams]. @@ -76,7 +76,7 @@ image::image_placeholder.png[] . "Invisible" placeholder needed for figure caption to display consistently and correctly. -=== Explanation +== Explanation For the previous example to build into a diagram that includes a figure title, and a figure title and a macro the specifies the diagram type before the code block. You can add a `target` filename and, in addition, specify the image output format to be `svg`. @@ -147,7 +147,7 @@ include::../partials/wavedrom/filename.adoc ==== [[graphviz]] -=== Graphviz +== Graphviz The Unpriv appendices contain Graphviz diagrams with associated keys that are arranged in tables. While in the LaTeX version, the diagrams and tables are arranged side-by-side, for the AsciiDoc version; @@ -278,7 +278,7 @@ eiid4 -> eiid0 [label=<rf>, color="red", fontsize=11, p .... [[ditaa]] -=== Ditaa diagrams +== Ditaa diagrams Following is source for simple ditaa diagram: @@ -364,7 +364,7 @@ DiagramBlock <|-- PlantUmlBlock NOTE: Asciidoctor supports additional diagram types. For information on additional diagram types, see the https://docs.asciidoctor.org/diagram-extension/latest/[Asciidoctor-diagram documentation]. [[bytefield]] -=== Bytefield diagrams +== Bytefield diagrams Bytefield diagrams are used for register graphics that cannot be rendered in wavedrom. For more information, see https://bytefield-svg.deepsymmetry.org/bytefield-svg/1.8.0/intro.html[Bytefield diagrams]. @@ -402,11 +402,11 @@ After the build, it looks like this example: include::../partials/bytefield/examplebyte.adoc[] -=== Editing Wavedrom diagrams for Unpriv +== Editing Wavedrom diagrams for Unpriv -==== Relevant contextual information +=== Relevant contextual information Wavedrom is a utility that is available at https://wavedrom.com/. @@ -414,7 +414,7 @@ Wavedrom is a utility that is available at https://wavedrom.com/. -==== Example Wavedrom code, before and after +=== Example Wavedrom code, before and after Following is an example Wavedrom file that is typical of one the needs just a few edits, minus the `[]` brackets that indicate a macro (because using the macro even within a code block activates a process in the Asciidoctor build): @@ -552,7 +552,7 @@ Now the diagram should contain all of the content that exists within the LaTeX v . Generate a PR to the convert2adoc branch and indicate whether you or a member of the team has tested your changes in a local build. . As always, thanks for your participation in the success of RISC-V. -==== Caveats for editing wavedrom diagrams +=== Caveats for editing wavedrom diagrams At the time of this writing, we have noticed the following unexpected results during diagram builds using the asciidoctor-pdf toolchain, as follows: diff --git a/modules/ROOT/pages/index_bib.adoc b/modules/ROOT/pages/index_bib.adoc index 335094c..cd94bf6 100644 --- a/modules/ROOT/pages/index_bib.adoc +++ b/modules/ROOT/pages/index_bib.adoc @@ -1,8 +1,8 @@ -== Index and bibliography += Index and bibliography An index and bibliography are included in the main priv and unpriv docs. You can develop your own index and bibliography for your stand alone document, but if it is to be merged into the main docs, you must merge the index and bibliography as well. -=== Index markers +== Index markers There are two types of index terms in AsciiDoc: @@ -68,7 +68,7 @@ I, King Arthur. I, King Arthur. (((knight, "Arthur, King"))) -=== Bibliography and references +== Bibliography and references There are two ways of handling bibliographies: @@ -79,7 +79,7 @@ There are two ways of handling bibliographies: You can add bibliographic entries to the last appendix that you create in a book document. [[auto-bib]] -==== Creating an automated bibliography with asciidoctor-bibtex +=== Creating an automated bibliography with asciidoctor-bibtex Asciidoctor-bibtex enables options that allow for establishing a single source of bibliographic entries that we can use for RISC-V specifications. As an added benefit we can make use of existing bibtex files. @@ -174,7 +174,7 @@ The following examples are json-formatted bibliographic entries: } ---- -==== Manual bibliography procedures (deprecated) +=== Manual bibliography procedures (deprecated) While the automated procedure and use of the RISC-V bibtex file is preferred, it is also possible to manually create and reference a bibliography. diff --git a/modules/ROOT/pages/intro.adoc b/modules/ROOT/pages/intro.adoc index ebcd357..9220d22 100644 --- a/modules/ROOT/pages/intro.adoc +++ b/modules/ROOT/pages/intro.adoc @@ -1,5 +1,5 @@ [[doc_intro]] -== Contributing to the RISC-V documentation += Contributing to the RISC-V documentation Welcome to the RISC-V documentation guidelines. This document is maintained by the https://github.com/riscv-admin/docs-sig/blob/main/CHARTER.adoc[RISC-V Doc Sig]. @@ -13,13 +13,13 @@ RISC-V documentation contributors: - Translate the documentation (coming soon!) -=== How to join RISC-V documentation +== How to join RISC-V documentation - 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 +== Getting help If you have questions about authoring, the build toolchain, or the Antora documentation site, the following resources are available: diff --git a/modules/ROOT/pages/linting.adoc b/modules/ROOT/pages/linting.adoc index 167229f..a07a888 100644 --- a/modules/ROOT/pages/linting.adoc +++ b/modules/ROOT/pages/linting.adoc @@ -1,8 +1,8 @@ -== Linting += Linting The linting of code/documentation can be categorized as dealing with formatting, syntax, or semantics. Once the rules for a given project are defined, many of these rules can be checked automatically with tooling. -=== Tooling +== Tooling https://pre-commit.com/[pre-commit tool] is a very useful, open source, well maintained, and popular tool/framework to help automate linting checks in general. It provides some of the following key features: diff --git a/modules/ROOT/pages/style-guidelines.adoc b/modules/ROOT/pages/style-guidelines.adoc index f720b4f..d416f53 100644 --- a/modules/ROOT/pages/style-guidelines.adoc +++ b/modules/ROOT/pages/style-guidelines.adoc @@ -1,10 +1,10 @@ [[style-guidelines]] -== RISC-V Style guidelines += RISC-V Style guidelines Whether you are creating a new extention or even a stand alone doc for RISC-V, follow these style guidelines to improve readability. [[basic-rules]] -=== Basic formatting +== Basic formatting Follow these basic formatting guidelines. @@ -30,7 +30,7 @@ Do not use any special formatting for base 10. * All of these names are in monospace. [[csr-rules]] -=== CSR formatting +== CSR formatting Use the following guidelines when you document a CSR: @@ -45,7 +45,7 @@ Use the following guidelines when you document a CSR: * Fields for registers are formatted in this style: `register`.FIELD. For example, `sstatus`.SPP. [[table-rules]] -=== Table formatting +== Table formatting Follow these formatting rules when you create a table. @@ -56,7 +56,7 @@ Follow these formatting rules when you create a table. * Use table captions to describe your table contents. Captions appear after the table and are controlled by the theme. * If you use footnotes in your table, make sure they appear immediately after the table. -==== Column header formatting +=== Column header formatting Follow these column header rules. @@ -65,7 +65,7 @@ Follow these column header rules. * Don't end with punctuation, including a period, an ellipsis, or a colon. * Use table headings for the first column and the first row only. -==== Punctuation in tables +=== Punctuation in tables Follow these punctuation rules for tables. diff --git a/modules/ROOT/pages/vale.adoc b/modules/ROOT/pages/vale.adoc index c4be49d..80b7b75 100644 --- a/modules/ROOT/pages/vale.adoc +++ b/modules/ROOT/pages/vale.adoc @@ -1,5 +1,5 @@ [[vale-at-riscv]] -== Vale at RISC-V += Vale at RISC-V Vale is an open source linting tool for prose. You can find more about Vale from the https://vale.sh/[Vale website]. diff --git a/modules/ROOT/pages/word-usage.adoc b/modules/ROOT/pages/word-usage.adoc index 2010a8d..a822466 100644 --- a/modules/ROOT/pages/word-usage.adoc +++ b/modules/ROOT/pages/word-usage.adoc @@ -1,4 +1,4 @@ -== Word usage += Word usage Above:: Avoid using directional words. Above and below do not translate well to screen readers. Instead, use "previous" or "following". diff --git a/modules/ROOT/pages/writing.adoc b/modules/ROOT/pages/writing.adoc index bd26232..c0da388 100644 --- a/modules/ROOT/pages/writing.adoc +++ b/modules/ROOT/pages/writing.adoc @@ -1,9 +1,9 @@ [[writing-simple]] -== Best practices += Best practices This section contains suggested best practices for clear, concise, and consistent content. -=== Use present tense +== Use present tense [cols="1,1"] |=== @@ -17,7 +17,7 @@ This section contains suggested best practices for clear, concise, and consisten Exception: Use future or past tense if it is required to convey the correct meaning. -=== Use active voice +== Use active voice [cols="1,1"] |=== @@ -33,7 +33,7 @@ meaning. Exception: Use passive voice if active voice leads to an awkward construction. -=== Use simple and direct language +== Use simple and direct language Use simple and direct language. Avoid using unnecessary phrases, such as saying "please." Direct language is easier to translate. @@ -52,7 +52,7 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying |With this next command, we'll view the register. |=== -=== Address the reader as "you" +== Address the reader as "you" Using "we" in a sentence can be confusing, because the reader might not know whether they're part of the "we" that you're describing. Does it mean the RISC-V team, the RISC-V members, open source people, hardware people, or even everyone? @@ -70,7 +70,7 @@ Using "we" in a sentence can be confusing, because the reader might not know whe An exception to this rule is the rationale sections. -=== Avoid Latin phrases +== Avoid Latin phrases Prefer English terms over Latin abbreviations. Latin terms can be difficult for translation because it adds an additional language to translate. @@ -86,7 +86,7 @@ Prefer English terms over Latin abbreviations. Latin terms can be difficult for |i.e., |=== -=== Avoid jargon and idioms +== Avoid jargon and idioms Some readers speak English as a second language. Avoid jargon and idioms to help them understand better. @@ -102,7 +102,7 @@ Some readers speak English as a second language. Avoid jargon and idioms to help |Chutar o pau-da-barraca (which translates to "kicking away the tent pole") |=== -=== Avoid statements about the future +== Avoid statements about the future Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha @@ -110,7 +110,7 @@ information. An exception to this rule is documentation about announced deprecations targeting removal in future versions. -=== Avoid statements that will soon be out of date +== Avoid statements that will soon be out of date Avoid words like "currently" and "new." A feature that is new today might not be considered new in a few months. @@ -127,7 +127,7 @@ considered new in a few months. |The new pointer masking extension provides |=== -=== Avoid words that assume a specific level of understanding +== Avoid words that assume a specific level of understanding Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value and can actually make a user feel not up to the task. @@ -155,7 +155,7 @@ These guidelines were adapted from the https://kubernetes.io/docs/contribute/sty ==== [[other-style-guidelines]] -=== Other style guidelines +== Other style guidelines Other style guidelines for reference: diff --git a/src/docs-dev-guide.adoc b/src/docs-dev-guide.adoc index ab8cec1..49b52b0 100755 --- a/src/docs-dev-guide.adoc +++ b/src/docs-dev-guide.adoc @@ -78,36 +78,37 @@ list-of::table[hide_empty_section=true, enhanced_rendering=true] == List of listings list-of::listing[hide_empty_section=true, enhanced_rendering=true] -include::../modules/ROOT/pages/copyright.adoc[] +[preface] +include::../modules/ROOT/pages/copyright.adoc[leveloffset=+1] [preface] -include::../modules/ROOT/pages/contributors.adoc[] +include::../modules/ROOT/pages/contributors.adoc[leveloffset=+1] -include::../modules/ROOT/pages/intro.adoc[] +include::../modules/ROOT/pages/intro.adoc[leveloffset=+1] -include::../modules/ROOT/pages/author-quickstart.adoc[] +include::../modules/ROOT/pages/author-quickstart.adoc[leveloffset=+1] -include::../modules/ROOT/pages/authoring.adoc[] +include::../modules/ROOT/pages/authoring.adoc[leveloffset=+1] -include::../modules/ROOT/pages/antora-structure.adoc[] +include::../modules/ROOT/pages/antora-structure.adoc[leveloffset=+1] -include::../modules/ROOT/pages/a_few_basics.adoc[] +include::../modules/ROOT/pages/a_few_basics.adoc[leveloffset=+1] -include::../modules/ROOT/pages/index_bib.adoc[] +include::../modules/ROOT/pages/index_bib.adoc[leveloffset=+1] -include::../modules/ROOT/pages/graphics.adoc[] +include::../modules/ROOT/pages/graphics.adoc[leveloffset=+1] -include::../modules/ROOT/pages/vale.adoc[] +include::../modules/ROOT/pages/vale.adoc[leveloffset=+1] -include::../modules/ROOT/pages/style-guidelines.adoc[] +include::../modules/ROOT/pages/style-guidelines.adoc[leveloffset=+1] -include::../modules/ROOT/pages/writing.adoc[] +include::../modules/ROOT/pages/writing.adoc[leveloffset=+1] -include::../modules/ROOT/pages/word-usage.adoc[] +include::../modules/ROOT/pages/word-usage.adoc[leveloffset=+1] -include::../modules/ROOT/pages/linting.adoc[] +include::../modules/ROOT/pages/linting.adoc[leveloffset=+1] -include::../modules/ROOT/pages/build-infrastructure.adoc[] +include::../modules/ROOT/pages/build-infrastructure.adoc[leveloffset=+1] // The index must precede the bibliography. The index macro is PDF-only (Antora // does not generate a back-of-book index), so it lives here in the assembler @@ -115,4 +116,5 @@ include::../modules/ROOT/pages/build-infrastructure.adoc[] [index] == Index -include::../modules/ROOT/pages/bibliography.adoc[] +[bibliography] +include::../modules/ROOT/pages/bibliography.adoc[leveloffset=+1]