Merge pull request #24 from kbroch-rivosinc/initial-pre-commit-setup

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

@@ -77,4 +77,3 @@ include::linting.adoc[]
 include::index.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}}
 ....
-

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
-

presentation/install-tools.adoc

@@ -171,7 +171,3 @@ http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/
 ----
 http://asciidoctor.org/docs/user-manual/
 ----
-
-
-
-

presentation/readme.adoc

@@ -16,4 +16,3 @@ https://docs.asciidoctor.org/reveal.js-converter/latest/converter/features/#basi
 ----
 
 For information on the build process for reveal.js presentations, see https://docs.asciidoctor.org/reveal.js-converter/latest/
-

readme.adoc

@@ -56,5 +56,3 @@ The reason is that the look and feel of PDF output from the toolchain in use is
 While best practice is _usually_ to maintain the same relative locations for files and directories so that other contributors can easily find everything, you have the option of changing things for your group and editing the github actions for your repo--as long as the pdf output keeps the established look and feel.
 
 We use the modifier _usually_ because AsciiDoc is intentionally used because of its usefulness in automated environments.
-
-

resources/fonts/OFL-M.txt

@@ -18,7 +18,7 @@ with others.
 
 The OFL allows the licensed fonts to be used, studied, modified and
 redistributed freely as long as they are not sold by themselves. The
-fonts, including any derivative works, can be bundled, embedded, 
+fonts, including any derivative works, can be bundled, embedded,
 redistributed and/or sold with any software provided that any reserved
 names are not used by derivative works. The fonts and derivatives,
 however, cannot be released under any other type of license. The

resources/fonts/OFL-P.txt

@@ -18,7 +18,7 @@ with others.
 
 The OFL allows the licensed fonts to be used, studied, modified and
 redistributed freely as long as they are not sold by themselves. The
-fonts, including any derivative works, can be bundled, embedded, 
+fonts, including any derivative works, can be bundled, embedded,
 redistributed and/or sold with any software provided that any reserved
 names are not used by derivative works. The fonts and derivatives,
 however, cannot be released under any other type of license. The