Merge pull request #47 from riscv/fixing-linter

fixing up pre-commit checks

src/a_few_basics.adoc

@@ -113,7 +113,7 @@ To create an ordered (numbered) list, place a `.` and a space before an item. Pu
 
 ==== Nested list
 
-To create a nested unordered list, use `** ` before the nested item. 
+To create a nested unordered list, use `** ` before the nested item.
 
 ----
 * Priv
@@ -185,4 +185,3 @@ This example renders as:
 <<Index markers>> describes how index markers work.
 
 For more information about options, see https://docs.asciidoctor.org/asciidoc/latest/macros/xref/#internal-cross-references[Cross References].
-

src/authoring.adoc

@@ -54,4 +54,3 @@ The following list contains links to resources for text editors/IDEs support of
 ** https://plugins.jetbrains.com/plugin/7391-asciidoc[jetbrain asciidoc plugin]
 * https://www.sublimetext.com/[Sublime Text] (NOTE: Sublime is not free)
 ** https://packagecontrol.io/packages/AsciiDoc[asciidoc package for Sublime Text2]
-

src/blocks_notes_markers.adoc

@@ -335,4 +335,3 @@ The hail-and-rainbow protocol can be initiated at three levels:
 A bold statement!footnote:disclaimer[Opinions are my own.]
 
 Another outrageous statement.footnote:disclaimer[]
-

src/graphics.adoc

@@ -1,7 +1,7 @@
 [[graphics]]
 == Graphics
 
-Graphics help people learn, break up text, and can overall improve your document content. 
+Graphics help people learn, break up text, and can overall improve your document content.
 
 While AsciiDoc can render graphics in all popular formats, by far the highest quality graphics rendering is from `.svg` format. This format is the preferred graphic type to use in RISC-V documents.
 
@@ -19,7 +19,7 @@ You can certainly use one of the other supported types, but know that they might
 
 Follow these guidelines for graphics.
 
-* Store your graphics in a subfolder. For the RISC-V main ISA doc, this folder is the https://github.com/riscv/riscv-isa-manual/tree/main/src/images[`images` folder]. Place your graphic in the subfolder that correspondes to its type. 
+* Store your graphics in a subfolder. For the RISC-V main ISA doc, this folder is the https://github.com/riscv/riscv-isa-manual/tree/main/src/images[`images` folder]. Place your graphic in the subfolder that correspondes to its type.
 * The build process creates the final image object. Do *not* create any generated image files into GitHub.
 * Introduce your graphic with a lead-in sentence. "The following image shows ..."
 * Use "following" and "preceding" to locate your image. Avoid using "above" or "below" (Doesn't make sense for people that use screen readers.)
@@ -559,5 +559,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 <<useful-unicode>> ) 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 &#8800; in Wavedrom diagrams and discovering the above rather confusing results, we decided to use `!=` as a workaround. With the fact that both Asciidoctor 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.
-
-

src/images/bytefield/examplebyte.adoc

@@ -15,4 +15,4 @@
 (draw-box (text "(WARL)" {:font-weight "bold"}) {:font-size 18 :span 15 :text-anchor "start" :borders {:top :border-unrelated :bottom :border-unrelated :right :border-unrelated}})
 
 (draw-box "MXLEN" {:font-size 24 :span 32 :borders {}})
-----
+----

src/index_bib.adoc

@@ -1,7 +1,7 @@
 [[index_bib]]
 == Index and bibliography
 
-An index and bibliography are included in the main priv and unpriv docs. You can develop your own index and bibliography for your stand alone document, but if it is to be merged into the main docs, you must merge the index and bibliography as well. 
+An index and bibliography are included in the main priv and unpriv docs. You can develop your own index and bibliography for your stand alone document, but if it is to be merged into the main docs, you must merge the index and bibliography as well.
 
 === Index markers
 

src/style-guidelines.adoc

@@ -10,7 +10,7 @@ Follow these basic formatting guidelines.
 * Use *`monospace bold`* for hex numbers. Hex numbers start with `0x`.
 * Use *`monospace bold`* for binary numbers. Binary numbers start with `0b`.
 * Use *`monospace bold`* for any literals.
-* Any number range, use regular font
+* Any number range, use regular font.
 
 See the next section for rules about referring to a CSR.
 
@@ -19,20 +19,22 @@ See the next section for rules about referring to a CSR.
 
 Use the following guidelines when you document a CSR:
 
-* CSR must always be capitalized. 
+* CSR must always be capitalized.
 * When plural, lowercase the `s`. CSRs.
-* Register is capitalized in title, but lowercase in text. "Supervisor Status (`sstatus`) Register”. But “The `sstatus` register…” 
+* Register is capitalized in title, but lowercase in text. "Supervisor Status (`sstatus`) Register”. But “The `sstatus` register…”
 * When in doubt, use "CSR" to indicate the type of register. You can then intermingle CSR and register in the text. So "The `misa` CSR is used to...." And then later in the paragraph, you can use "register". As in, "This register also does this other thing."
 * In a title, the format is “Long name (`short name`) Register. All other references in that section can use the short name, but it must be in tics. So "Supervisor Status (`sstatus`) Register”. The rest of the references to that register can be "the `sstatus` CSR".
-* Avoid starting a sentence with a CSR name. 
+* Avoid starting a sentence with a CSR name.
 * As a general rule, whenever you use a term in tics, it should be followed by what the thing is to help with translation. So avoid statements like this:  “`misa` also helps distinguish different variants of a design.”  And instead use this: “The `misa` CSR also helps distinguish different variants of a design.”
-* Fields for registers are formatted in this style: `register`.FIELD. For example, `sstatus`.SPP
+* Fields for registers are formatted in this style: `register`.FIELD. For example, `sstatus`.SPP.
 
+[[bp-gen]]
 === General best practices
 
 
 This section contains suggested best practices for clear, concise, and consistent content.
 
+[[bp-present]]
 ==== Use present tense
 
 
@@ -45,9 +47,9 @@ This section contains suggested best practices for clear, concise, and consisten
 |Cache-management operation instructions will perform operations on copies of data in the memory hierarchy.
 |===
 
-Exception: Use future or past tense if it is required to convey the correct
-meaning.
+Exception: Use future or past tense if it is required to convey the correct meaning.
 
+[[bp-active]]
 ==== Use active voice
 
 [cols="1,1"]
@@ -58,12 +60,13 @@ meaning.
 |You can use the RVWMO memory model...
 |The RVWMO memory model can be used...
 
-|The RVWMO memory model enables architects 
+|The RVWMO memory model enables architects.
 |Architects are enabled by the RVWMO memory model.
 |===
 
 Exception: Use passive voice if active voice leads to an awkward construction.
 
+[[bp-simple]]
 ==== Use simple and direct language
 
 Use simple and direct language. Avoid using unnecessary phrases, such as saying "please."
@@ -73,30 +76,32 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying
 |Yes
 |No
 
-|To build a chip, ... 
+|To build a chip, ...
 |In order to build a chip, ...
 
-|See the Hypervisor extension. 
+|See the Hypervisor extension.
 |Please see the Hypervisor extension.
 
-|View the register. 
+|View the register.
 |With this next command, we'll view the register.
 |===
 
+[[bp-you]]
 ==== Address the reader as "you"
 
 [cols="1,1"]
 |===
 |Yes
 |No
 
-|You can use the `misa` CSR ... 
+|You can use the `misa` CSR ...
 |We'll use the `misa` CSR  ...
 
-|In the preceding output, you can see... 
+|In the preceding output, you can see...
 |In the preceding output, we can see ...
 |===
 
+[[bp-latin]]
 ==== Avoid Latin phrases
 
 Prefer English terms over Latin abbreviations.
@@ -106,39 +111,39 @@ Prefer English terms over Latin abbreviations.
 |Yes
 |No
 
-|For example, ... 
+|For example, ...
 |e.g., ...
 
 |That is, ...
 |i.e., ...
 |===
 
-
+[[bp-patterns]]
 === Patterns to avoid
 
+[[bp-we]]
 ==== Avoid using "we"
 
-Using "we" in a sentence can be confusing, because the reader might not know
-whether they're part of the "we" you're describing.
+Using "we" in a sentence can be confusing, because the reader might not know whether they're part of the "we" you're describing.
 
 [cols="1,1"]
 |===
 |Yes
 |No
 
-|Version 1.4 includes ... 
+|Version 1.4 includes ...
 |In version 1.4, we have added ...
 
-|RISC-V provides a new feature for ... 
+|RISC-V provides a new feature for ...
 |We provide a new feature ...
 
-|This page teaches you how to create CSRs. 
+|This page teaches you how to create CSRs.
 |In this page, we are going to learn about CSRs.
 |===
 
 An exception for using "we" is the rationale sections.
 
-
+[[bp-jargon]]
 ==== Avoid jargon and idioms
 
 Some readers speak English as a second language. Avoid jargon and idioms to help them understand better.
@@ -148,57 +153,56 @@ Some readers speak English as a second language. Avoid jargon and idioms to help
 |Yes
 |No
 
-|Internally, ... 
+|Internally, ...
 |Under the hood, ...
 
 |Stop trying.
 |Chutar o pau-da-barraca (which translates to "kicking away the tent pole")
 |===
 
+[[bp-future]]
 ==== Avoid statements about the future
 
-Avoid making promises or giving hints about the future. If you need to talk about
-an alpha feature, put the text under a heading that identifies it as alpha
-information.
+Avoid making promises or giving hints about the future. If you need to talk about an alpha feature, put the text under a heading that identifies it as alpha information.
 
-An exception to this rule is documentation about announced deprecations targeting removal in future versions. 
+An exception to this rule is documentation about announced deprecations targeting removal in future versions.
 
-==== Avoid statements that will soon be out of date
+[[bp-out-of-date]]
+==== Avoid statements that will soon be out-of-date
 
-Avoid words like "currently" and "new." A feature that is new today might not be
-considered new in a few months.
+Avoid words like "currently" and "new." A feature that is new today might not be considered new in a few months.
 
 [cols="1,1"]
 |===
 |Do
 |Don't
 
-|In version 1.4, ... 
+|In version 1.4, ...
 |In the current version, ...
 
-|The pointer masking extension provides ... 
+|The pointer masking extension provides ...
 |The new pointer masking extension provides ...
 |===
 
+[[bp-assume]]
 ==== Avoid words that assume a specific level of understanding
 
-Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value and can actually make a user feel
+Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value and can actually make a user feel stupid.
 
 [cols="1,1"]
 |===
 |Do
 |Don't
 
-|Include one command in ... 
+|Include one command in ...
 |Include just one command in ...
 
-|Run the command ... 
+|Run the command ...
 |Simply run the command ...
 
-|You can remove ... 
+|You can remove ...
 |You can easily remove ...
 
-|These steps ... 
+|These steps ...
 |These simple steps ...
 |===
-

src/tables_symbols_math.adoc

@@ -1,15 +1,20 @@
 [[tables_symbols_math]]
 === Tables
 
+By using tables, you can group information into logical units, which can make the infromation presented easier to understand.
+
+[[tables-gen]]
+==== General rules for tables
 Follow these general rules when you create a table.
 
 * Avoid tables in the middle of lists.
 * Do not use tables to lay out a page. For example, if you have a long list of items, do not use a 2 column table to save space. The information should make sense side by side.
-* Do not create a table that has a single row or a single column, unless you are following a previous layout. For example, if each section in a chapter includes a table of options, then use a table even if one of the sections has only a single option. 
+* Do not create a table that has a single row or a single column, unless you are following a previous layout. For example, if each section in a chapter includes a table of options, then use a table even if one of the sections has only a single option.
 * Always use table headers and captions to make your tables more accessible.
 * Use introductory sentences for your table. For example, "The following table contains the options for the CSR." You can use either a period or a colon for your introductory sentence.
 * Do not refer to the "table above" or the "below table". Use words such as "The following table" or "The preceeding table".
 
+[[tables-format]]
 ==== Table formatting
 
 Follow these formatting rules when you create a table.
@@ -22,7 +27,7 @@ Follow these formatting rules when you create a table.
 * If you use footnotes in your table, make sure they appear immediately after the table.
 
 
-
+[[tables-column-format]]
 ==== Column header formatting
 
 Follow these column header rules.
@@ -32,15 +37,15 @@ Follow these column header rules.
 * Don't end with punctuation, including a period, an ellipsis, or a colon.
 * Use table headings for the first column and the first row only.
 
-
+[[tables-punctuation]]
 ==== Punctuation in tables
 
 Follow these punctuation rules for tables.
 
 * If all cells in a table column are complete sentences, then end each cell with a period.
 * If all cells in a table column are sentence fragments, then do not use a period to end each cell.
-* If cells in a table column contain a mixture of complete and fragmented sentences, then first try to make them all parallel - either all complete sentences or all sentence fragments. However, if this approach is impractical, then punctuate each cell independently, and punctuate appropriate for that individual cell. 
-- Do not end column headers with punctuation, including a period, an ellipsis, or a colon.
+* If cells in a table column contain a mixture of complete and fragmented sentences, then first try to make them all parallel - either all complete sentences or all sentence fragments. However, if this approach is impractical, then punctuate each cell independently, and punctuate appropriate for that individual cell.
+* Do not end column headers with punctuation, including a period, an ellipsis, or a colon.
 
 [WARNING]
 ====

src/word-usage.adoc

@@ -26,7 +26,7 @@ Following:: Don't use "following" by itself. Don't say "See the following". Inst
 If (whether):: Use if as a condition, such as logic. If a, then b.
 Use whether to indicate choice or alternative. Event a happens, whether event b does or not.
 
-Latin phrases:: Avoid abbreviations such as etc., e.g., i.e. They do not translate well. Instead use "and so on" and "for example,". If you do use e.g. or i.e., then know that e.g. means "for example" and i.e means "in other words". With e.g., it is understood that there are more examples than just the ones listed; "The colors of the rainbow, e.g. red, yellow and green". With i.e., however, it is intended as a replacement for the previous text. "The primary colors, i.e. red, blue, and yellow". 
+Latin phrases:: Avoid abbreviations such as etc., e.g., i.e. They do not translate well. Instead use "and so on" and "for example,". If you do use e.g. or i.e., then know that e.g. means "for example" and i.e means "in other words". With e.g., it is understood that there are more examples than just the ones listed; "The colors of the rainbow, e.g. red, yellow, and green". With i.e., however, it is intended as a replacement for the previous text. "The primary colors, i.e. red, blue, and yellow".
 
 Legal:: Use only to indicate that something is allowed because of a law. "RISC-V processors are legally available." Avoid using when something is allowed. Instead, use "valid".