Merge branch 'main' of github.com:riscv/docs-dev-guide

.github/workflows/build-pdf.yml

@@ -1,74 +1,84 @@
----
-name: Create Specification Document
+# Makefile for RISC-V Doc Template
+#
+# This work is licensed under the Creative Commons Attribution-ShareAlike 4.0
+# International License. To view a copy of this license, visit
+# http://creativecommons.org/licenses/by-sa/4.0/ or send a letter to
+# Creative Commons, PO Box 1866, Mountain View, CA 94042, USA.
+#
+# SPDX-License-Identifier: CC-BY-SA-4.0
+#
+# Description:
+#
+# This Makefile is designed to automate the process of building and packaging
+# the Doc Template for RISC-V Extensions.
 
-# The workflow is triggered by pull request, push to main, and manual dispatch.
-on:
-  workflow_dispatch:
-    inputs:
-      version:
-        description: 'Release version, e.g. X.Y.Z:'
-        required: true
-        type: string
-      revision_mark:
-        description: 'Set revision mark as Draft, Release or Stable:'
-        required: true
-        type: string
-        default: Draft
-      prerelease:
-        description: Tag as a pre-release?
-        required: false
-        type: boolean
-        default: true
-      draft:
-        description: Create release as a draft?
-        required: false
-        type: boolean
-        default: false
-  pull_request:
-  push:
-    branches:
-      - main
+DOCS := \docs-dev-guide.adoc
 
-jobs:
-  build:
-    runs-on: ubuntu-latest
+DATE ?= $(shell date +%Y-%m-%d)
+VERSION ?= v0.0.0
+REVMARK ?= Draft
+ifneq ($(SKIP_DOCKER),true)
+	DOCKER_CMD := docker run --rm -v ${PWD}:/build -w /build \
+	riscvintl/riscv-docs-base-container-image:latest \
+	/bin/sh -c
+	DOCKER_QUOTE := "
+endif
 
-    steps:
-      # Step 1: Checkout the repository
-      - name: Checkout repository
-        uses: actions/checkout@v3
-        with:
-          submodules: recursive
+SRC_DIR := src
+BUILD_DIR := build
 
-      # Step 2: Pull the latest RISC-V Docs container image
-      - name: Pull Container
-        run: docker pull riscvintl/riscv-docs-base-container-image:latest
+DOCS_PDF := $(DOCS:%.adoc=%.pdf)
+DOCS_HTML := $(DOCS:%.adoc=%.html)
 
-      # Step 3: Build Files
-      - name: Build Files
-        run: make
-        env:
-          VERSION: v${{ github.event.inputs.version }}
-          REVMARK: ${{ github.event.inputs.revision_mark }}
+XTRA_ADOC_OPTS :=
+ASCIIDOCTOR_PDF := asciidoctor-pdf
+ASCIIDOCTOR_HTML := asciidoctor
+OPTIONS := --trace \
+           -a compress \
+           -a mathematical-format=svg \
+           -a pdf-fontsdir=docs-resources/fonts \
+           -a pdf-theme=docs-resources/themes/riscv-pdf.yml \
+           $(XTRA_ADOC_OPTS) \
+		       -D build \
+           --failure-level=ERROR
+REQUIRES := --require=asciidoctor-diagram \
+            --require=asciidoctor-mathematical
 
-      # Step 4: Upload the built PDF files as a single artifact
-      - name: Upload Build Artifacts
-        uses: actions/upload-artifact@v3
-        with:
-          name: Build Artifacts
-          path: ${{ github.workspace }}/build/*.pdf
-          retention-days: 30
+.PHONY: all build clean build-container build-no-container
 
-      # Create Release
-      - name: Create Release
-        uses: softprops/action-gh-release@v1
-        with:
-          files: ${{ github.workspace }}/build/*.pdf
-          tag_name: v${{ github.event.inputs.version }}
-          name: Release ${{ github.event.inputs.version }}
-          draft: ${{ github.event.inputs.draft }}
-          prerelease: ${{ github.event.inputs.prerelease }}
-        env:
-          GITHUB_TOKEN: ${{ secrets.GHTOKEN }}
-        if: github.event_name == 'workflow_dispatch'
-        # This condition ensures this step only runs for workflow_dispatch events.
+all: build
+
+build-docs: $(DOCS_PDF) $(DOCS_HTML)
+
+vpath %.adoc $(SRC_DIR)
+
+%.pdf: %.adoc
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_PDF) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
+
+%.html: %.adoc
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) $(OPTIONS) $(REQUIRES) $< $(DOCKER_QUOTE)
+
+build:
+	@echo "Checking if Docker is available..."
+	@if command -v docker >/dev/null 2>&1 ; then \
+		echo "Docker is available, building inside Docker container..."; \
+		$(MAKE) build-container; \
+	else \
+		echo "Docker is not available, building without Docker..."; \
+		$(MAKE) build-no-container; \
+	fi
+
+build-container:
+	@echo "Starting build inside Docker container..."
+	$(MAKE) build-docs
+	@echo "Build completed successfully inside Docker container."
+
+build-no-container:
+	@echo "Starting build..."
+	$(MAKE) SKIP_DOCKER=true build-docs
+	@echo "Build completed successfully."
+
+clean:
+	@echo "Cleaning up generated files..."
+	rm -rf $(BUILD_DIR)
+	@echo "Cleanup completed."

src/a_few_basics.adoc

@@ -9,14 +9,10 @@ For details and additional options, see:
  * AsciiDoc http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/[quick reference].
  * Asciidoctor http://asciidoctor.org/docs/user-manual/[user manual].
 
-In addition, you can ask questions in the https://discuss.asciidoctor.org/[Asciidoctor discussion list].
-
-As is true of any complex process, AsciiDoc/Asciidoctor has some quirks. Please be certain to use the templates, as the templates provide you with files that result in fully featured PDF output.
+In addition, you can ask questions in <https://asciidoctor.zulipchat.com/>
 
 Best practice is to test the PDF build frequently to ensure that you have not accidentally introduced something that breaks the build.
 
-WARNING: PDF generation requires the use of Ruby 2.7.2.
-
 [NOTE]
 ====
 Send questions to [email protected].

src/authoring.adoc

@@ -12,7 +12,7 @@ Asciidoctor toolchains:
 
 Please view the https://github.com/riscv/docs-templates[readme] in the docs-templates 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-templates/commit/5c18cc9761eb3f6516975ee0c109729a4ce66b93[document] that takes you through a local install process that supports all of the required features for a local build.
+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.
 
 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:
 

src/blocks_notes_markers.adoc

@@ -1,42 +1,41 @@
 [[blocks_notes_markers]]
 === Admonition blocks
 
-Five kinds of standard admonition blocks are available in AsciiDoc and these can be mapped to either default or custom icons.
+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.
 
-[source,adoc]
-----
-[NOTE]
-====
-This is an example of an admonition block.
+NOTE: The admonition type is not displayed, only the icon.
 
-Unlike an admonition paragraph, it may contain any AsciiDoc content.
-The style can be any one of the admonition labels:
+Note:: Highlight extra information that should stand out from the rest of the text. A "by the way, you should know this" statement.
 
-* NOTE
-* TIP
-* WARNING
-* CAUTION
-* IMPORTANT
-====
-----
+NOTE: example of note type
 
-This renders as:
+Caution:: Cautions users about a condition or action that can lead to bad outcomes such as personal injury or damage equipment. A "we don’t recommend" statement.
 
-[NOTE]
-====
-This is an example of an admonition block.
+CAUTION: example of caution type
 
-Unlike an admonition paragraph, it may contain any AsciiDoc content.
-The style can be any one of the admonition labels:
+Warning:: Warns users about a situation that is undesirable. A "Do not do this!" or "You must do this" statement.
 
-* NOTE
-* TIP
-* WARNING
-* CAUTION
-* IMPORTANT
-====
+WARNING: example of warning type
+
+Important:: Information that a user must have. For example, "After you set your password, you cannot change it."
 
-For a single paragraph admonition, simply use a double colon:
+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: 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.
+* 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.
+
+==== Single paragraph admonition
+
+For a single paragraph admonition, use a double colon:
 
 [source,adoc]
 ----
@@ -47,52 +46,61 @@ which renders as:
 
 NOTE: Note content.
 
-Alternate octicons:
-
-* alert-24
-* comment-discussion-24
-* flame-24
-* info-24
-* pencil-24
-* question-24
-* sheild-24
-* squirrel-24
-* zap-24
+==== Admonition blocks
 
-
-Another example of an admonition block:
+An admonition block can contain any AsciiDoc content.
 
 [source,adoc]
 ----
 [IMPORTANT]
-.Feeding the Werewolves
 ====
-While werewolves are hardy community members, keep in mind the following dietary concerns:
+As a general rule, follow these guidelines for admonitions:
 
-. They are allergic to cinnamon.
-. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
-. Celery makes them sad.
+* 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.
+* 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.
 ====
 ----
 
-Rendered:
+which renders as:
 
 [IMPORTANT]
-.Feeding the Werewolves
 ====
-While werewolves are hardy community members, keep in mind the following dietary concerns:
+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.
+* 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.
+====
+
+==== Admonition with a title
+
+You can add a title to your admonition block.
 
-. They are allergic to cinnamon.
-. More than two glasses of orange juice in 24 hours makes them howl in harmony with alarms and sirens.
-. Celery makes them sad.
+[source,adoc]
+----
+[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*.
+====
+----
 
+Rendered:
 
-https://github.com/asciidoctor/asciidoctor-pdf/blob/master/docs/theming-guide.adoc#key-prefix-admonition-icon
+[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*.
+====
 
-The default admonition icons don't look right for RISC-V specification, and alternate icons and colors have been set in risc-v_spec-pdf.yml.  and will be considered.
+==== RISC-V admonition icon colors
 
-Current icons, edited to tone down color:
+The admonition icons are set in `risc-v_spec-pdf.yml`. RISC-V uses custom colors, as indicated in the <<custom-color-icons>>.
 
 NOTE: note
 

src/colophon.adoc

@@ -1,20 +1,14 @@
 [colophon]
 = Preface
 
-This document demonstrates the use of AsciiDoc for RISC-V specifications, with the goal of capturing information that will result in effective and efficient collaboration throughout the community.
+This document demonstrates the use of AsciiDoc for RISC-V specifications, with the goal of capturing information that will result in effective and efficient communication of the specs.
 
-AsciiDoc is currently the most feature-rich of the popular lightweight markup languages based on markdown. An Open Source effort, it is gaining wider adoption and there is an AsciiDoc working group. RISC-V also supports some documentation associated with testing that is written in another popular lightweight markup language, Restructured Text.
+AsciiDoc is currently the most feature-rich of the popular lightweight markup languages. As an Open Source effort, it is gaining wider adoption and there is an link:https://asciidoc-wg.eclipse.org/[AsciiDoc working group] to standardize the AsciiDoc specification as well as other ways to get involved.
 
-It’s helpful to think of AsciiDoc as https://docs.asciidoctor.org/asciidoc/latest/asciidoc-vs-markdown/[Markdown grown up]. People in tech often have impulses to re-invent markdown with a brand new lightweight markup language of their own. As appealing as that idea can be, it is inherently flawed. Publishing, like music, can have simple forms, but when fully featured is quite complex. Everyone who has attempted to build upon Markdown to create a simple and feature-rich publishing solution faces the same reality--as we add features, the process necessarily becomes complex.
+RISC-V specifications require the use of AsciiDoc markup and the Asciidoctor toolchain with advanced publishing features that are provided by several add-ons. The <https://github.com/riscv/docs-spec-template> repo allows you to jump into writing a spec.
 
-RISC-V specifications require the use of AsciiDoc markup and the Asciidoctor toolchain with advanced publishing features that are provided by several add-ons. The templates in this repo allow you to jump in with a hands-on approach and build a PDF using the example files.
 
-[TIP]
-====
-Because AsciiDoc is gaining in popularity, there are opportunities contributors to the AsciiDoc specification while it is still being developed. You might want to view what Dan Allen and Sarah White are doing. Along with a growing open source community, they support both AsciiDoc and the Asciidoctor toolchain. Feel free to find out about the working group, the specification under development, the toolchain and its various plugins, and other projects that make use of AsciiDoc.
-====
-
-If you'd like to add to the documentation build toolchain, please join the RISC-V group devoted to supporting the RISC-V publishing templates. As members of an Open Source community, we like to support other open source efforts, and for that reason we enourage coordination in adding features so that everyone benefits.
+If you'd like to discuss the documentation build toolchain, please join the RISC-V group link:https://lists.riscv.org/g/sig-documentation[sig-documentation] devoted to supporting the RISC-V spec documentation. As members of an Open Source community, we like to support other open source efforts, and for that reason we encourage coordination in adding features so that everyone benefits.
 
 [NOTE]
 ====

src/docs-dev-guide.adoc

@@ -2,8 +2,6 @@
 = Authoring and Editing RISC-V Specifications
 :description: A working template for documenting RISC-V architecture in asciidoc
 :company: RISC-V.org
-:revdate: 12/2021
-:revnumber: 0.
 :revremark: Pre-release version
 //development: assume everything can change
 //stable: assume everything could change

src/style-guidelines.adoc

@@ -8,16 +8,16 @@ Whether you are creating a new extention or even a stand alone doc for RISC-V, f
 
 Follow these basic formatting guidelines.
 
-* Use _italic_ for new terms.
+* Use _italic_ for new terms. The _Atomic Layer Deposition_ is a layer-by-layer process that results in the deposition of thin films one atomic layer at a time in a highly controlled manner.
 * Use `monospace` for the following items:
-** Filenames
-** Directories
-** Paths
-** Inline code
-** Commands
+** Filenames: `a-st-ext.adoc`
+** Directories: The `src` directory.
+** Paths: `https://github.com/riscv/riscv-isa-manual/blob/main/src/a-st-ext.adoc`
+** Inline code: The `push()` method adds elements to an array.
+** Commands: The `make` command.
 * Use *`monospace bold`* for the following items:
-** Hex numbers. Hex numbers start with `0x`.
-** Binary numbers. Binary numbers start with `0b`.
+** Hex numbers. Hex numbers start with *`0x`*.
+** Binary numbers. Binary numbers start with *`0b`*.
 ** Non-base 10 literals
 ** Non-base 10 number ranges