Initial pre commit setup

.github/workflows/build-pdf.yml

@@ -1,3 +1,4 @@
+---
 # This workflow installs dependencies for PDF generation, generates the PDF,
 # and uploads the PDF as an artifact.
 
@@ -13,69 +14,69 @@ on:
   workflow_dispatch:
     inputs:
       create_release:
-        description: 'Create a new Docs Dev Guide release if set to true'
+        description: Create a new Docs Dev Guide release if set to true
         required: false
         default: 'false'
       target_branch:
-        description: 'Target Branch'
+        description: Target Branch
         required: true
-        default: 'main'
+        default: main
       release_notes:
-        description: 'Release Notes'
+        description: Release Notes
         required: false
 
 jobs:
   build:
     runs-on: ubuntu-latest
 
     steps:
-    - name: Checkout repository
-      uses: actions/checkout@v3
-
-    # Set the short SHA for use in artifact names
-    - name: Set short SHA
-      run: echo "SHORT_SHA=$(echo ${GITHUB_SHA::7})" >> $GITHUB_ENV
-
-    # Get the current date
-    - name: Get current date
-      run: echo "CURRENT_DATE=$(date +'%Y-%m-%d')" >> $GITHUB_ENV
+      - name: Checkout repository
+        uses: actions/checkout@v3
 
-    # Pull the latest RISC-V Docs container image
-    # https://github.com/riscv/riscv-docs-base-container-image
-    # https://hub.docker.com/r/riscvintl/riscv-docs-base-container-image
-    - name: Pull Container
-      id: pull_container_image
-      run: |
-        docker pull riscvintl/riscv-docs-base-container-image:latest
+      # Set the short SHA for use in artifact names
+      - name: Set short SHA
+        run: echo "SHORT_SHA=$(echo ${GITHUB_SHA::7})" >> $GITHUB_ENV
 
-    # Build PDF  files using the container
-    - name: Build Files
-      id: build_files
-      if: steps.pull_container_image.outcome == 'success'
-      run: |
-        docker run --rm -v ${{ github.workspace }}:/build riscvintl/riscv-docs-base-container-image:latest \
-        /bin/sh -c make
+      # Get the current date
+      - name: Get current date
+        run: echo "CURRENT_DATE=$(date +'%Y-%m-%d')" >> $GITHUB_ENV
 
-    # Upload the priv-isa-asciidoc PDF file
-    - name: Upload docs-dev-guide.pdf
-      if: steps.build_files.outcome == 'success'
-      uses: actions/upload-artifact@v3
-      with:
-        name: docs-dev-guide-${{ env.SHORT_SHA }}.pdf
-        path: ${{ github.workspace }}/docs-dev-guide.pdf
-        retention-days: 7
-
-    - name: Create Release
-      if: steps.build_files.outcome == 'success' && github.event_name == 'workflow_dispatch' && github.event.inputs.create_release == 'true'
-      uses: softprops/action-gh-release@v1
-      with:
-        draft: false
-        tag_name: docs-dev-guide-${{ env.SHORT_SHA }}-${{ env.CURRENT_DATE }}
-        name: ${{ env.CURRENT_DATE }}
-        body: |
-          This release was created by: ${{ github.event.sender.login }}
-          Release Notes: ${{ github.event.inputs.release_notes }}
-        files: |
-          ${{ github.workspace }}/docs-dev-guide.pdf
-      env:
-        GITHUB_TOKEN: ${{ secrets.GHTOKEN }}
+      # Pull the latest RISC-V Docs container image
+      # https://github.com/riscv/riscv-docs-base-container-image
+      # https://hub.docker.com/r/riscvintl/riscv-docs-base-container-image
+      - name: Pull Container
+        id: pull_container_image
+        run: |
+          docker pull riscvintl/riscv-docs-base-container-image:latest
+
+      # Build PDF  files using the container
+      - name: Build Files
+        id: build_files
+        if: steps.pull_container_image.outcome == 'success'
+        run: |
+          docker run --rm -v ${{ github.workspace }}:/build riscvintl/riscv-docs-base-container-image:latest \
+          /bin/sh -c make
+
+      # Upload the priv-isa-asciidoc PDF file
+      - name: Upload docs-dev-guide.pdf
+        if: steps.build_files.outcome == 'success'
+        uses: actions/upload-artifact@v3
+        with:
+          name: docs-dev-guide-${{ env.SHORT_SHA }}.pdf
+          path: ${{ github.workspace }}/docs-dev-guide.pdf
+          retention-days: 7
+
+      - name: Create Release
+        if: steps.build_files.outcome == 'success' && github.event_name == 'workflow_dispatch' && github.event.inputs.create_release == 'true'
+        uses: softprops/action-gh-release@v1
+        with:
+          draft: false
+          tag_name: docs-dev-guide-${{ env.SHORT_SHA }}-${{ env.CURRENT_DATE }}
+          name: ${{ env.CURRENT_DATE }}
+          body: |
+            This release was created by: ${{ github.event.sender.login }}
+            Release Notes: ${{ github.event.inputs.release_notes }}
+          files: |
+            ${{ github.workspace }}/docs-dev-guide.pdf
+        env:
+          GITHUB_TOKEN: ${{ secrets.GHTOKEN }}

.gitignore

@@ -1,2 +1 @@
 *.pdf
-

.pre-commit-config.yaml

@@ -0,0 +1,28 @@
+---
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v4.5.0
+    hooks:
+      - id: check-json
+      - id: check-symlinks
+      - id: check-yaml
+      - id: end-of-file-fixer
+        exclude: \.svg$
+      - id: trailing-whitespace
+        args: [--markdown-linebreak-ext=md]
+        exclude: \.svg$
+
+  - repo: local
+    hooks:
+      - id: forbidden-file-extensions
+        name: forbidden-file-extensions
+        entry: disallow these file extensions
+        language: fail
+        # Disallow other asciidoc extensions except .adoc
+        files: .*\.(asciidoc|asc)$
+
+  - repo: https://github.com/jumanjihouse/pre-commit-hook-yamlfmt
+    rev: 0.2.3
+    hooks:
+      - id: yamlfmt
+        args: [--mapping, '2', --sequence, '4', --offset, '2']

LICENSE

@@ -49,7 +49,7 @@ exhaustive, and do not form part of our licenses.
      such as asking that all changes be marked or described.
      Although not required by our licenses, you are encouraged to
      respect those requests where reasonable. More_considerations
-     for the public: 
+     for the public:
 	wiki.creativecommons.org/Considerations_for_licensees
 
 =======================================================================
@@ -393,4 +393,3 @@ the avoidance of doubt, this paragraph does not form part of the
 public licenses.
 
 Creative Commons may be contacted at creativecommons.org.
-

a_few_basics.adoc

@@ -183,5 +183,3 @@ In some cases, you might want to make use of unicode characters. Keep in mind th
 Hexadecimal unicode looks like it has problems in the pdf. This is gnarley.
 
 Updates to asciidoctor-pdf: https://github.com/asciidoctor/asciidoctor-pdf
-
-

authoring.adoc

@@ -9,7 +9,7 @@ In either case, please feel free to examine the AsciiDoc source files for this `
 
 === About Asciidoctor
 
-AsiiDoc is the markup language and Asciidoctor is a set of toolchains that support publishing from AsciiDoc. 
+AsiiDoc is the markup language and Asciidoctor is a set of toolchains that support publishing from AsciiDoc.
 
 There are three major Asciidoctor toolchains:
 
@@ -79,4 +79,3 @@ The best linter for asciidoc is available for Sublime Text, and linters are avai
 As soon as you have installed asciidoctor on your computer, you have the ability to check that each individual file builds in html by simply running `asciidoctor filename.adoc` on any file. You can also check that the book or report on which you are working builds in html by running `asciidoctor bookname.adoc` or `asciidoctor reportname.adoc` on the book or report header. The strings `filename`, `bookname`, and `reportname` all should be replaced with the actual names you are using.
 
 Asciidoctor has fairly good error messages and usually lets you know the file and row number where the build first breaks.
-

bibliography.adoc

@@ -9,4 +9,3 @@ bibliography::[]
 //From Journeyman to Master. Addison-Wesley. 1999.
 //* [[[gof,gang]]] Erich Gamma, Richard Helm, Ralph Johnson & John Vlissides.
 //Design Patterns: Elements of Reusable Object-Oriented Software. Addison-Wesley. 1994.
-

blocks_notes_markers.adoc

@@ -551,5 +551,3 @@ Text that links to bibliography:
 _The Pragmatic Programmer_ <<pp>> should be required reading for all developers.
 To learn all about design patterns, refer to the book by the "`Gang of Four`" <<gof>>.
 ----
-
-

book_header.adoc

@@ -56,15 +56,24 @@ This document is released under a Creative Commons Attribution 4.0 International
 
 //the colophon allows for a section after the preamble that is part of the frontmatter and therefore not assigned a page number.
 include::colophon.adoc[]
+
 //While some documents need several levels of introductory material, other documents only need a breif introduction. You can choose to have either colophon or an overview, or to have both.
 //include::overview.adoc[]
 include::authoring.adoc[]
+
 include::a_few_basics.adoc[]
+
 include::tables_graphics.adoc[]
+
 include::blocks_notes_markers.adoc[]
+
 include::wavedrom_edit.adoc[]
+
 include::writing.adoc[]
+
+include::linting.adoc[]
+
 //please note that the index must precede the bibliography for both to work within the same book.
 include::index.adoc[]
-include::bibliography.adoc[]
 
+include::bibliography.adoc[]

colophon.adoc

@@ -20,4 +20,3 @@ If you'd like to add to the documentation build toolchain, please join the RISC-
 ====
 This section is technically called a colophon and is useful as a preface. Its contents should be replaced with your preface contents.
 ====
-

dependencies/README.md

@@ -1,3 +1,2 @@
 Dependencies for the build environment for various package managers.  Used in
 `.github/workflows/`.
-

images/wavedrom/instruction_formats.adoc

@@ -45,4 +45,3 @@
   {bits: 20,  name: 'imm[31:12]', type: 3}
 ], config: {label: {right: 'U-Type'}}}
 ....
-

images/wavedrom/test4wvdrm.adoc

@@ -12,4 +12,3 @@
   {bits: 6, name: 'funct5',     type: 8, attr: ['5','AMOSWAP.W/D', 'AMOADD.W/D', 'AMOAND.W/D', 'AMOOR.W/D', 'AMOXOR.W/D', 'AMOMAX[U].W/D','AMOMIN[U].W/D']},
 ], config: {bits: 32}}
 ....
-

linting.adoc

@@ -0,0 +1,14 @@
+== 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
+
+link: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:
+
+* link:https://pre-commit.com/hooks.html[a great number of support hooks for linting]
+** including direct support by many of the maintainers of best in class linters (ex: link:https://github.com/psf/black[python linter black])
+** link:https://pre-commit.com/index.html#plugins[hook plugins] allow adding these and versioning to control updates
+* support for link:https://pre-commit.com/index.html#new-hooks[creating new custom hooks easily]
+* can be run before `git commit` (i.e. "pre-commit") so authors can detect and fix problems sooner in the workflow
+* can also be run in link:https://pre-commit.com/index.html#github-actions-example[continuous integration (CI)] to enforce checks are run for every pull request

local_build.md

@@ -20,7 +20,7 @@ We are using the Ruby toolchain because it supports building the customizable, f
 
 To support building WaveDrom diagrams directly from scripts contained in blocks in the AsciiDoc source files, we use NPM to install the wavedrom-cli, even though we are using the Ruby toolchain.
 
-NOTE: Even though NPM is required for the Wavedrom diagrams to work properly, we are *not* using the Asciidoctor NPM toolchain. 
+NOTE: Even though NPM is required for the Wavedrom diagrams to work properly, we are *not* using the Asciidoctor NPM toolchain.
 
 ## Install Ruby on MacOS
 
@@ -67,11 +67,11 @@ rvm use system
 rvm use 2.5.9
 ```
 
-ALERT: Ensure that you are using the same Ruby version for all Ruby gems that you install for the Asciidoctor toolchain. 
+ALERT: Ensure that you are using the same Ruby version for all Ruby gems that you install for the Asciidoctor toolchain.
 
 ## Windows—install Ruby with RVM
 
-NOTE: Users of Windows 10 are reporting problems with RVM. We plan to test the use of Cygwin as a workaround. Please note that if you don't need asciidoctor-mathematical for rendering of mathematical expressions, you can make use of Ruby 2.7.2. 
+NOTE: Users of Windows 10 are reporting problems with RVM. We plan to test the use of Cygwin as a workaround. Please note that if you don't need asciidoctor-mathematical for rendering of mathematical expressions, you can make use of Ruby 2.7.2.
 
 - For Windows, use: http://rubyinstaller.org/
 
@@ -81,7 +81,7 @@ NOTE: During the Windows install, click in the installer to:
 - add paths
 - add tdtk
 
-ALERT: Ensure that you are using the same Ruby version for all gems that you install for the Asciidoctor toolchain. 
+ALERT: Ensure that you are using the same Ruby version for all gems that you install for the Asciidoctor toolchain.
 
 ## MacOS--install Asciidoctor
 
@@ -127,7 +127,7 @@ Install the following:
 * asciidoctor-bibtex gem, which is needed for auto-creation of a bibliography from citations.
 
 ```cmd
-gem install asciidoctor-pdf 
+gem install asciidoctor-pdf
 gem install asciidoctor-bibtex
 ```
 
@@ -142,15 +142,15 @@ Install syntax highlighting gems as follows (for Windows, append the string `--s
 gem install coderay
 gem install rouge
 gem install pygments.rb
-``` 
+```
 
 ## Add NVM, node 15, and `wavedrom-cli` for WaveDrom diagrams
 
 For MacOS, use brew to install nvm and create an nvm directory:
 
 ```cmd
 brew install nvm
-mkdir ~/.nvm 
+mkdir ~/.nvm
 ```
 
 open either ~/.bash_profile or ~/.zshrc (for macOS Catalina or later):
@@ -213,7 +213,7 @@ WARNING: For the MacOS, if you upgrade from a prior version to Big Sur, you must
 
 ## Graphviz is used for diagrams in some appendices
 
-To support graphviz on the Mac, use brew 
+To support graphviz on the Mac, use brew
 
 ```cmd
 brew install graphviz
@@ -252,14 +252,14 @@ gem install csl-styles
 gem install asciidoctor-bibtex
 ```
 
-You can then add a bibliography to your appendices and use bibtex conventions to add citations into your AsciiDoc text files. 
+You can then add a bibliography to your appendices and use bibtex conventions to add citations into your AsciiDoc text files.
 
 Details of how to work with bibtex and the RISC-V bibliogrpahy are in the example.pdf file.
 
 
 ## AsciiDoc book headers 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 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.
 
 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.
 
@@ -278,7 +278,7 @@ NOTE: Blank lines are not allowed in between the `include::file_name.adoc` files
 
 ## HTML build
 
-Building in HTML is a good way to check that your content under development builds properly. 
+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:
 
@@ -293,7 +293,7 @@ For pdf output, cd into this cloned directory and use this command:
 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/
 ```
 
-This generates a file named `book_header.pdf` that makes use of the graphics, styles, and fonts that is identical to example.pdf. 
+This generates a file named `book_header.pdf` that makes use of the graphics, styles, and fonts that is identical to example.pdf.
 
 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.
 
@@ -327,7 +327,7 @@ While Pandoc does a reasonably good job, there are always documentation nits tha
 
 ## If you want to make use of change bars
 
-The current procedure for changebars is, admittedly, a bit fiddly, but the convenience value of changebars that show up in a pdf can make them worth the effort. 
+The current procedure for changebars is, admittedly, a bit fiddly, but the convenience value of changebars that show up in a pdf can make them worth the effort.
 
 To support changebars, the following has been added to the YAML stylesheet:
 
@@ -360,13 +360,13 @@ if (border_width = data[:border_changebar])
         prev_line_width = pdf.line_width
         pdf.stroke_color border_color
         pdf.line_width border_width
-        pdf.stroke_vertical_line fragment.top + border_offset, fragment.top-height, :at => 50 - pdf.bounds.absolute_left 
+        pdf.stroke_vertical_line fragment.top + border_offset, fragment.top-height, :at => 50 - pdf.bounds.absolute_left
         pdf.stroke_color prev_stroke_color
         pdf.line_width prev_line_width
       elsif (border_width = data[:border_width])
 ```
 
-At this point changebars require manual entry and removal. You can find documentation for how to use markup for changebars in the example.pdf. 
+At this point changebars require manual entry and removal. You can find documentation for how to use markup for changebars in the example.pdf.
 
 Technical staff is exploring further automated processing and CI/CD.
 
@@ -378,4 +378,3 @@ https://docs.google.com/document/d/1fUWEM3b-lbHQRruvAw3BUOA_ND_cJD0bsijV5bESklA/
 ### Link to JDK
 
 You can find information on installing the JDK on a MacOS here: https://docs.oracle.com/en/java/javase/15/install/installation-jdk-macos.html#GUID-F575EB4A-70D3-4AB4-A20E-DBE95171AB5F
-