From 819f075edb3ee9ef9285e5c25102c14a93464d67 Mon Sep 17 00:00:00 2001 From: Kevin Broch Date: Sat, 20 Jan 2024 16:43:55 -0800 Subject: [PATCH] initial add pre-commit hooks and autofixes from them Signed-off-by: Kevin Broch --- .github/workflows/build-pdf.yml | 103 +++++++-------- .gitignore | 1 - .pre-commit-config.yaml | 28 ++++ LICENSE | 3 +- a_few_basics.adoc | 2 - authoring.adoc | 3 +- bibliography.adoc | 1 - blocks_notes_markers.adoc | 2 - book_header.adoc | 1 - colophon.adoc | 1 - dependencies/README.md | 1 - images/wavedrom/instruction_formats.adoc | 1 - images/wavedrom/test4wvdrm.adoc | 1 - local_build.md | 31 +++-- presentation/install-tools.adoc | 4 - presentation/readme.adoc | 1 - readme.adoc | 2 - resources/fonts/OFL-M.txt | 2 +- resources/fonts/OFL-P.txt | 2 +- resources/fonts/OFL1.txt | 2 +- resources/riscv-spec.bib | 156 +++++++++++------------ resources/themes/riscv-pdf.yml | 82 ++++++------ tables_graphics.adoc | 4 - wavedrom_edit.adoc | 2 - writing.adoc | 10 +- 25 files changed, 222 insertions(+), 224 deletions(-) create mode 100644 .pre-commit-config.yaml diff --git a/.github/workflows/build-pdf.yml b/.github/workflows/build-pdf.yml index f2bb5db..591438d 100644 --- a/.github/workflows/build-pdf.yml +++ b/.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,15 +14,15 @@ 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: @@ -29,53 +30,53 @@ jobs: 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 }} \ No newline at end of file + # 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 }} diff --git a/.gitignore b/.gitignore index bd98a73..a136337 100644 --- a/.gitignore +++ b/.gitignore @@ -1,2 +1 @@ *.pdf - diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml new file mode 100644 index 0000000..a5b74b9 --- /dev/null +++ b/.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'] diff --git a/LICENSE b/LICENSE index 53883b1..2f244ac 100644 --- a/LICENSE +++ b/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. - diff --git a/a_few_basics.adoc b/a_few_basics.adoc index 5b34a32..1ad8ee0 100644 --- a/a_few_basics.adoc +++ b/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 - - diff --git a/authoring.adoc b/authoring.adoc index 0e6d322..1851313 100644 --- a/authoring.adoc +++ b/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. - diff --git a/bibliography.adoc b/bibliography.adoc index d833f78..17be9b9 100644 --- a/bibliography.adoc +++ b/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. - diff --git a/blocks_notes_markers.adoc b/blocks_notes_markers.adoc index e6b0906..f605ad4 100644 --- a/blocks_notes_markers.adoc +++ b/blocks_notes_markers.adoc @@ -551,5 +551,3 @@ Text that links to bibliography: _The Pragmatic Programmer_ <> should be required reading for all developers. To learn all about design patterns, refer to the book by the "`Gang of Four`" <>. ---- - - diff --git a/book_header.adoc b/book_header.adoc index e857dc3..8d8da81 100644 --- a/book_header.adoc +++ b/book_header.adoc @@ -77,4 +77,3 @@ include::linting.adoc[] include::index.adoc[] include::bibliography.adoc[] - diff --git a/colophon.adoc b/colophon.adoc index 4ab6332..9e4dc92 100644 --- a/colophon.adoc +++ b/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. ==== - diff --git a/dependencies/README.md b/dependencies/README.md index 0841ce8..f64a366 100644 --- a/dependencies/README.md +++ b/dependencies/README.md @@ -1,3 +1,2 @@ Dependencies for the build environment for various package managers. Used in `.github/workflows/`. - diff --git a/images/wavedrom/instruction_formats.adoc b/images/wavedrom/instruction_formats.adoc index 6c82898..04ea186 100644 --- a/images/wavedrom/instruction_formats.adoc +++ b/images/wavedrom/instruction_formats.adoc @@ -45,4 +45,3 @@ {bits: 20, name: 'imm[31:12]', type: 3} ], config: {label: {right: 'U-Type'}}} .... - diff --git a/images/wavedrom/test4wvdrm.adoc b/images/wavedrom/test4wvdrm.adoc index 3a30580..52080dc 100644 --- a/images/wavedrom/test4wvdrm.adoc +++ b/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}} .... - diff --git a/local_build.md b/local_build.md index 25099ac..896df65 100644 --- a/local_build.md +++ b/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,7 +142,7 @@ 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 @@ -150,7 +150,7 @@ 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 - diff --git a/presentation/install-tools.adoc b/presentation/install-tools.adoc index eeb3036..873eef8 100644 --- a/presentation/install-tools.adoc +++ b/presentation/install-tools.adoc @@ -171,7 +171,3 @@ http://asciidoctor.org/docs/asciidoc-syntax-quick-reference/ ---- http://asciidoctor.org/docs/user-manual/ ---- - - - - diff --git a/presentation/readme.adoc b/presentation/readme.adoc index c17987a..f145fff 100644 --- a/presentation/readme.adoc +++ b/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/ - diff --git a/readme.adoc b/readme.adoc index e117b29..30d6833 100644 --- a/readme.adoc +++ b/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. - - diff --git a/resources/fonts/OFL-M.txt b/resources/fonts/OFL-M.txt index 7881887..11146a2 100755 --- a/resources/fonts/OFL-M.txt +++ b/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 diff --git a/resources/fonts/OFL-P.txt b/resources/fonts/OFL-P.txt index 79320bd..22dcd1c 100755 --- a/resources/fonts/OFL-P.txt +++ b/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 diff --git a/resources/fonts/OFL1.txt b/resources/fonts/OFL1.txt index 06c608d..2f244ac 100644 --- a/resources/fonts/OFL1.txt +++ b/resources/fonts/OFL1.txt @@ -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 ======================================================================= diff --git a/resources/riscv-spec.bib b/resources/riscv-spec.bib index 3d7157f..54d1dfb 100644 --- a/resources/riscv-spec.bib +++ b/resources/riscv-spec.bib @@ -34,7 +34,7 @@ @article{Katevenis:1984 pages = {138--152}, publisher = {Computer Science Press, Inc.}, address = {New York, NY, USA}, -} +} @inproceedings{Ungar:1984, author = {David Ungar and Ricki Blau and Peter Foley and Dain Samples @@ -44,7 +44,7 @@ @inproceedings{Ungar:1984 address = {Ann Arbor, MI}, year = {1984}, pages = {188--197} -} +} @Article{spur-jsscc1989, author = {David D. Lee and Shing I. Kong and Mark D. Hill and @@ -140,52 +140,52 @@ @Misc{openriscarch month = {December}, year = 2012} -@ARTICLE{tremblay-vis-ieeemicro1996, -author={Tremblay, M. and O'Connor, J.M. and Narayanan, V. and Liang He}, -journal={IEEE Micro}, -title={{VIS} speeds new media processing}, -year={1996}, -month=AUG, -volume={16}, -number={4}, -pages={10 -20}, -keywords={3D graphics environments;RISC-style instructions;UltraSparc;VIS;Visual Instruction Set;media processing;media-processing algorithms;computer graphics;instruction sets;reduced instruction set computing;}, +@ARTICLE{tremblay-vis-ieeemicro1996, +author={Tremblay, M. and O'Connor, J.M. and Narayanan, V. and Liang He}, +journal={IEEE Micro}, +title={{VIS} speeds new media processing}, +year={1996}, +month=AUG, +volume={16}, +number={4}, +pages={10 -20}, +keywords={3D graphics environments;RISC-style instructions;UltraSparc;VIS;Visual Instruction Set;media processing;media-processing algorithms;computer graphics;instruction sets;reduced instruction set computing;}, ISSN={0272-1732},} -@ARTICLE{lee-max-ieeemicro1996, -author={Lee, R.B.}, -journal={IEEE Micro}, -title={Subword parallelism with {MAX-2}}, -year={1996}, -month=AUG, -volume={16}, -number={4}, -pages={51 -59}, -keywords={MAX-2;instruction extensions;media processing;parallel computation;subword parallelism;word-oriented general-purpose processor;instruction sets;multimedia computing;parallel processing;}, +@ARTICLE{lee-max-ieeemicro1996, +author={Lee, R.B.}, +journal={IEEE Micro}, +title={Subword parallelism with {MAX-2}}, +year={1996}, +month=AUG, +volume={16}, +number={4}, +pages={51 -59}, +keywords={MAX-2;instruction extensions;media processing;parallel computation;subword parallelism;word-oriented general-purpose processor;instruction sets;multimedia computing;parallel processing;}, ISSN={0272-1732},} -@ARTICLE{peleg-mmx-ieeemicro1996, -author={Peleg, A. and Weiser, U.}, -journal={IEEE Micro}, -title={{MMX} technology extension to the {Intel} architecture}, -year={1996}, -month=AUG, -volume={16}, -number={4}, -pages={42 -50}, +@ARTICLE{peleg-mmx-ieeemicro1996, +author={Peleg, A. and Weiser, U.}, +journal={IEEE Micro}, +title={{MMX} technology extension to the {Intel} architecture}, +year={1996}, +month=AUG, +volume={16}, +number={4}, +pages={42 -50}, keywords={Intel architecture;MMX;SIMD;communications;compatibility;multimedia;operating systems;microprocessor chips;parallel architectures;}, ISSN={0272-1732},} -@ARTICLE{raman-sse-ieeemicro2000, -author={Raman, S.K. and Pentkovski, V. and Keshava, J.}, -journal={IEEE Micro}, -title={Implementing streaming {SIMD} extensions on the {Pentium}-{III} processor }, -year={2000}, +@ARTICLE{raman-sse-ieeemicro2000, +author={Raman, S.K. and Pentkovski, V. and Keshava, J.}, +journal={IEEE Micro}, +title={Implementing streaming {SIMD} extensions on the {Pentium}-{III} processor }, +year={2000}, month=JUL/AUG, -volume={20}, -number={4}, -pages={47 -57}, -keywords={Internet;Pentium III developers;demanding multimedia;die size constraints;streaming SIMD extensions;instruction sets;microprocessor chips;}, +volume={20}, +number={4}, +pages={47 -57}, +keywords={Internet;Pentium III developers;demanding multimedia;die size constraints;streaming SIMD extensions;instruction sets;microprocessor chips;}, ISSN={0272-1732},} @misc{lomont-avx-irm2011, @@ -195,28 +195,28 @@ @misc{lomont-avx-irm2011 year = {2011}, } -@ARTICLE{goodacre-armisa-computer2005, -author={Goodacre, J. and Sloss, A.N.}, -journal={Computer}, -title={Parallelism and the {ARM} instruction set architecture}, -year={2005}, +@ARTICLE{goodacre-armisa-computer2005, +author={Goodacre, J. and Sloss, A.N.}, +journal={Computer}, +title={Parallelism and the {ARM} instruction set architecture}, +year={2005}, month=JULY, -volume={38}, -number={7}, -pages={ 42 - 50}, -keywords={ ARM RISC processor; ARM chip design; ARM instruction set architecture; digital signal processor-like operations; exception handling; multiprocessing; reduced-instruction-set computing; subword parallelism; thread-level parallelism; variable execution time; instruction sets; microprocessor chips; parallel architectures; parallel programming; reduced instruction set computing;}, +volume={38}, +number={7}, +pages={ 42 - 50}, +keywords={ ARM RISC processor; ARM chip design; ARM instruction set architecture; digital signal processor-like operations; exception handling; multiprocessing; reduced-instruction-set computing; subword parallelism; thread-level parallelism; variable execution time; instruction sets; microprocessor chips; parallel architectures; parallel programming; reduced instruction set computing;}, ISSN={0018-9162},} -@ARTICLE{diefendorff-altivec-ieeemicro2000, -author={Diefendorff, K. and Dubey, P.K. and Hochsprung, R. and Scale, H.}, +@ARTICLE{diefendorff-altivec-ieeemicro2000, +author={Diefendorff, K. and Dubey, P.K. and Hochsprung, R. and Scale, H.}, journal={IEEE Micro}, -title={{AltiVec} extension to {PowerPC} accelerates media processing}, -year={2000}, +title={{AltiVec} extension to {PowerPC} accelerates media processing}, +year={2000}, month=MAR/APR, -volume={20}, -number={2}, -pages={85 -95}, -keywords={2D image processing;3D graphics;AltiVec extension;Apple G4;Hewlett-Packard added MAX;MDMX;MIPS architecture;MMX;Motorola's MPC 7400;PA-RISC architecture;PowerPC;PowerPC's AltiVec;SSE;Silicon Graphics;Sun enhanced Sparc;alias KNI;handwriting recognition;media mining;media processing;multimedia technologies;narrow/broadband signal processing;personal computing;digital signal processing chips;handwriting recognition;multimedia systems;parallel architectures;}, +volume={20}, +number={2}, +pages={85 -95}, +keywords={2D image processing;3D graphics;AltiVec extension;Apple G4;Hewlett-Packard added MAX;MDMX;MIPS architecture;MMX;Motorola's MPC 7400;PA-RISC architecture;PowerPC;PowerPC's AltiVec;SSE;Silicon Graphics;Sun enhanced Sparc;alias KNI;handwriting recognition;media mining;media processing;multimedia technologies;narrow/broadband signal processing;personal computing;digital signal processing chips;handwriting recognition;multimedia systems;parallel architectures;}, ISSN={0272-1732},} @misc{gwennap-mdmx-mpr1996, @@ -237,7 +237,7 @@ @article{majc pages = {12--25}, publisher = {IEEE Computer Society Press}, address = {Los Alamitos, CA, USA}, -} +} @InProceedings{tx2, author = {John M. Frankovich and H. Philip Peterson}, @@ -263,7 +263,7 @@ @inproceedings{Klauser-1998 series = {PACT '98}, year = {1998}, address = {Washington, DC, USA}, -} +} @inproceedings{Kim-micro2005, author = {Kim, Hyesoon and Mutlu, Onur and Stark, Jared and Patt, Yale N.}, @@ -273,16 +273,16 @@ @inproceedings{Kim-micro2005 year = {2005}, location = {Barcelona, Spain}, pages = {43--54}, -} +} @INPROCEEDINGS{Gharachorloo90memoryconsistency, author = {Kourosh Gharachorloo and Daniel Lenoski and James Laudon and Phillip Gibbons and Anoop Gupta and John - Hennessy}, + Hennessy}, title = {Memory Consistency and Event Ordering in Scalable - Shared-Memory Multiprocessors}, + Shared-Memory Multiprocessors}, booktitle = {In Proceedings of the 17th Annual International - Symposium on Computer Architecture}, + Symposium on Computer Architecture}, year = {1990}, pages = {15--26} } @@ -297,7 +297,7 @@ @inproceedings{Rajwar:2001:SLE location = {Austin, Texas}, pages = {294--305}, publisher = {IEEE Computer Society}, -} +} @Misc{sparcieee1994, title = {{IEEE} Standard for a 32-bit microprocessor}, @@ -342,16 +342,16 @@ @article{virtio numpages = {9}, publisher = {ACM}, address = {New York, NY, USA}, -} +} @ARTICLE{goldbergvm, -author={Goldberg, Robert P.}, -journal={Computer}, -title={Survey of virtual machine research}, -year={1974}, -month={June}, -volume={7}, -number={6}, +author={Goldberg, Robert P.}, +journal={Computer}, +title={Survey of virtual machine research}, +year={1974}, +month={June}, +volume={7}, +number={6}, pages={34-45} } @@ -381,7 +381,7 @@ @article{transparent-superpages acmid = {844138}, publisher = {ACM}, address = {New York, NY, USA}, -} +} @Book{stretch, editor = {Werner Buchholz}, @@ -406,7 +406,7 @@ @inproceedings{cdc6600 year = {1965}, location = {San Francisco, California}, pages = {33--40} -} +} @InProceedings{jtseng:sbbci, author = {J. Tseng and K. Asanovi\'c}, @@ -477,22 +477,22 @@ @misc{riscv-asm-manual howpublished = {\url{https://github.com/riscv/riscv-asm-manual}} } -@inproceedings{lithe-pan-hotpar09, +@inproceedings{lithe-pan-hotpar09, author = {Heidi Pan and Benjamin Hindman and Krste Asanovi\'c}, title = {{Lithe}: Enabling Efficient Composition of Parallel Libraries}, booktitle = {Proceedings of the 1st USENIX Workshop on Hot Topics in Parallelism (HotPar~'09)}, month = {March}, year = {2009}, -address = {Berkeley, CA}} +address = {Berkeley, CA}} -@inproceedings{lithe-pan-pldi10, +@inproceedings{lithe-pan-pldi10, author = {Heidi Pan and Benjamin Hindman and Krste Asanovi\'c}, title = {Composing Parallel Software Efficiently with {Lithe}}, booktitle = {31st Conference on Programming Language Design and Implementation}, month = {June}, year = {2010}, -address = {Toronto, Canada}} +address = {Toronto, Canada}} @article{roux:hal-01091186, TITLE = {{Innocuous Double Rounding of Basic Arithmetic Operations}}, diff --git a/resources/themes/riscv-pdf.yml b/resources/themes/riscv-pdf.yml index 144c287..bc6a0f3 100644 --- a/resources/themes/riscv-pdf.yml +++ b/resources/themes/riscv-pdf.yml @@ -1,6 +1,7 @@ +--- font: catalog: - merge: false + merge: false #Petrona body: normal: Petrona-Light.ttf @@ -61,47 +62,47 @@ base: vertical_rhythm: $base_line_height_length horizontal_rhythm: $base_line_height_length # QUESTION should vertical_spacing be block_spacing instead? -vertical_spacing: $vertical_rhythm +vertical_spacing: $vertical_rhythm link: - font_color: 428bca + font_color: 428bca # literal is currently used for inline monospaced in prose and table cells codespan: - font_color: b12146 - font_family: code -menu_caret_content: " \u203a " + font_color: b12146 + font_family: code +menu_caret_content: ' › ' heading: - align: left + align: left + font_color: 3e058e + font_family: headings + font_style: light + h1_font_size: floor($base_font_size * 2.8) + # h2 is used for chapter titles (book doctype only) + h2_font_size: floor($base_font_size * 2.15) + h3_font_size: round($base_font_size * 1.7) + h4_font_size: $base_font_size_large + h5_font_size: $base_font_size + h6_font_size: $base_font_size_small +title_page: + align: right + logo: + top: 10% + title: + font_family: headings + font_style: light + font_size: floor($base_font_size * 2.8) + top: 55% font_color: 3e058e + subtitle: font_family: headings font_style: light - h1_font_size: floor($base_font_size * 2.8) - # h2 is used for chapter titles (book doctype only) - h2_font_size: floor($base_font_size * 2.15) - h3_font_size: round($base_font_size * 1.7) - h4_font_size: $base_font_size_large - h5_font_size: $base_font_size - h6_font_size: $base_font_size_small -title_page: - align: right - logo: - top: 10% - title: - font_family: headings - font_style: light - font_size: floor($base_font_size * 2.8) - top: 55% - font_color: 3e058e - subtitle: - font_family: headings - font_style: light - font_size: floor($base_font_size * 1.2) - authors: - font_family: headings - font_color: 3e058e - font_style: light - font_size: floor($base_font_size * .8) - revision: - margin_top: $base_font_size * 1.25 + font_size: floor($base_font_size * 1.2) + authors: + font_family: headings + font_color: 3e058e + font_style: light + font_size: floor($base_font_size * .8) + revision: + margin_top: $base_font_size * 1.25 block: margin_top: 0 margin_bottom: $vertical_rhythm @@ -130,7 +131,7 @@ abstract: font_style: $heading_font_style sidebar: font-style: italic - background-color: f5f5fc + background-color: f5f5fc border-color: 8d81b8 border-radius: 3 border-width: 0.2 @@ -146,7 +147,7 @@ admonition: column_rule_width: $base_border_width padding: [0, $horizontal_rhythm, 0, $horizontal_rhythm] icon: - note: + note: name: pencil-square-o stroke_color: 6489b3 tip: @@ -158,7 +159,7 @@ admonition: stroke_color: 5f8c8b warning: stroke_color: 9c4d4b - caution: + caution: stroke_color: c99a2c label: text_transform: uppercase @@ -256,7 +257,7 @@ header: # * {section-title} # * {section-or-chapter-title} recto: - right: + right: content: '{section-or-chapter-title} | Page {page-number}' verso: left: @@ -276,7 +277,7 @@ footer: # content: '{company}' # * {page-count} # * {page-number} - #center: + #center: #content: '{document-title}' # * {document-subtitle} # * {chapter-title} @@ -296,4 +297,3 @@ footer: content: $footer_recto_right_content #center: '{page-number}' #content: '{page-number}' - diff --git a/tables_graphics.adoc b/tables_graphics.adoc index 4d4f6c9..73311c7 100644 --- a/tables_graphics.adoc +++ b/tables_graphics.adoc @@ -586,7 +586,3 @@ 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 mathemtical symbols are rendered within the build process. For this reason, please avoid using single character latexmath expresions inline and prefentially make use of unicode or superscripts and subscripts when possible. ==== - - - - diff --git a/wavedrom_edit.adoc b/wavedrom_edit.adoc index 929ebc8..defbfae 100644 --- a/wavedrom_edit.adoc +++ b/wavedrom_edit.adoc @@ -166,5 +166,3 @@ At the time of this writing, we have noticed the following unexpected results du * Some, but not all, unicode that works in AsciiDoc (see <> ) actually breaks the Wavedrom diagram build, and other unicode does not break the Wavedrom diagram build but still doesn't render properly. * Latexmath appears to not work at all in Wavedrom diagrams. * After struggling to understand why various options that we explored for an acceptable ≠ in Wavedrom diagrams and discovering the above rather confusing results, we decided to use `!=` as a workaround. With the fact that both Ascoddoctor and Wavedrom are evolving, and also the fact that bytefield is being considered as an alternative diagrams rendering solution, it seems possible that this workaround will be temporary. - - diff --git a/writing.adoc b/writing.adoc index 8996a23..f3630e3 100644 --- a/writing.adoc +++ b/writing.adoc @@ -2,7 +2,7 @@ All professional technical writers eventually learn to keep their writing as simple as possible. -bad text added here, it uses master and slave as bad words. +bad text added here, it uses master and slave as bad words. === Writing is rewriting @@ -26,9 +26,9 @@ Here are some writing guidelines: While we develop style guidelines, this chapter serves for collecting style guidelines specific to RISC-V. At this point December 2021) there is almost no content. -Please feel free to suggest ideas and content for the RISC-V style guidelines, and please don’t think that you need to add polished content. +Please feel free to suggest ideas and content for the RISC-V style guidelines, and please don’t think that you need to add polished content. -Small organizations like RISC-V usually identify existing style guides and then document the "deltas," including cases where it makes sense to deviate from what's in the existing style guides and also what needs to be added. +Small organizations like RISC-V usually identify existing style guides and then document the "deltas," including cases where it makes sense to deviate from what's in the existing style guides and also what needs to be added. I have a list of existing guides that we can use as a starting point. These are likely the most pertinent existing style guidelines that were created for addressing the needs of highly technical audiences as opposed to consumer end user audiences: @@ -70,7 +70,3 @@ This section is here to contain results of style discussions that have emerged f RE: A request for table captions to be placed below tables. Discussion: A simple Google search on the topic of table caption placement resulted in all but one online discussion stating that table captions should appear above tables. The single result that did not make this statement mentioned that while normal placement is above the table, there are occasional instances where organizations decide to place table captions below. - - - -