From fc57ff4c02dcd94ac4dd281efe2835718fd8dc5f Mon Sep 17 00:00:00 2001 From: Kevin Broch Date: Fri, 17 May 2024 08:51:18 -0700 Subject: [PATCH] fix pre-commit failures just ran `pre-commit run --all-files` related to #36 --- src/a_few_basics.adoc | 2 -- src/graphics.adoc | 4 ---- src/style-guidelines.adoc | 19 ++++++++----------- src/tables_symbols_math.adoc | 24 +++++++++++------------- src/word-usage.adoc | 17 ++++++++--------- 5 files changed, 27 insertions(+), 39 deletions(-) diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc index 391d8f1..7774495 100644 --- a/src/a_few_basics.adoc +++ b/src/a_few_basics.adoc @@ -157,5 +157,3 @@ kind of trap. |Software is oblivious |No |No |Yes |Yeslatexmath:[$^{2}$] |Handled by environment |No |Yes |Yes |Yes |=== - - diff --git a/src/graphics.adoc b/src/graphics.adoc index 6d86c75..c92414f 100644 --- a/src/graphics.adoc +++ b/src/graphics.adoc @@ -541,7 +541,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 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. - - - - diff --git a/src/style-guidelines.adoc b/src/style-guidelines.adoc index 8d4e4c0..c023f2f 100644 --- a/src/style-guidelines.adoc +++ b/src/style-guidelines.adoc @@ -9,13 +9,13 @@ Avoid words like "currently" and "new." A feature that is new today might not be [cols="1,1"] |=== -|Do +|Do |Don't -|In version 1.4, ... +|In version 1.4, ... |In the current version, ... -|The Federation feature provides ... +|The Federation feature provides ... |The new Federation feature provides ... |=== @@ -27,21 +27,18 @@ Avoid words such as "just", "simply", "easy", "easily", or "simple". These words [cols="1,1"] |=== -|Do +|Do |Don't -|Include one command in ... +|Include one command in ... |Include just one command in ... -|Run the container ... +|Run the container ... |Simply run the container ... -|You can remove ... +|You can remove ... |You can easily remove ... -|These steps ... +|These steps ... |These simple steps .. |=== - - - diff --git a/src/tables_symbols_math.adoc b/src/tables_symbols_math.adoc index 5b57a04..a3553c2 100644 --- a/src/tables_symbols_math.adoc +++ b/src/tables_symbols_math.adoc @@ -10,10 +10,10 @@ Asciidoc makes standard tables easy and also supports the creation of complex ta - Align tables to center with the options `float="center"` and `align="center"`. - Use table header coding to indicate a header. Don't use a different font, color, or any background indication. - Sort rows in either a logical order or by alphabetizing the rows and columns. -- If your table is long or complicated, consider creating multiple tables. If you do choose to create a complicated table, make sure that +- If your table is long or complicated, consider creating multiple tables. If you do choose to create a complicated table, make sure that - Use table captions to describe your table contents. Captions appear after the table and are controlled by the theme. - If you use footnotes in your table, make sure they appear immediately after the table. -- Remember that tables can be hard for screen readers to parse. If your table is complex, be sure that the contents are described in the text. +- Remember that tables can be hard for screen readers to parse. If your table is complex, be sure that the contents are described in the text. === Column header formating @@ -34,24 +34,24 @@ The following example shows a simple table with 2 rows and 2 columns. To indicat [source] ---- -[cols="1,1"] +[cols="1,1"] |=== -|Cell in column 1, row 1 +|Cell in column 1, row 1 |Cell in column 2, row 1 -|Cell in column 1, row 2 +|Cell in column 1, row 2 |Cell in column 2, row 2 |=== ---- Results in the following table. -[cols="1,1"] +[cols="1,1"] |=== -|Cell in column 1, row 1 +|Cell in column 1, row 1 |Cell in column 2, row 1 -|Cell in column 1, row 2 +|Cell in column 1, row 2 |Cell in column 2, row 2 |=== @@ -62,7 +62,7 @@ Headers can add additional information to your table, making them easier to unde You can add a header row by adding the first row of cells directly in a line. ---- -[cols="1,1,1"] +[cols="1,1,1"] |=== |Col 1, header row|Col 2, header row|Col 3, header row @@ -75,7 +75,7 @@ You can add a header row by adding the first row of cells directly in a line. Or you can use the `header` option. ---- -[%header,cols="1,1,1"] +[%header,cols="1,1,1"] |=== |Col 1, header row |Col 2, header row @@ -89,7 +89,7 @@ Or you can use the `header` option. Either table renders with table headers. -[cols="1,1,1"] +[cols="1,1,1"] |=== |Col 1, header row|Col 2, header row|Col 3, header row @@ -329,5 +329,3 @@ sqrt(4) = 2 In some cases, you might want to make use of unicode characters. Keep in mind that asciidoctor-pdf supports only decimal character references. See https://github.com/asciidoctor/asciidoctor-pdf/issues/486 For updates to asciidoctor-pdf, see https://github.com/asciidoctor/asciidoctor-pdf. - - diff --git a/src/word-usage.adoc b/src/word-usage.adoc index bf0a5de..1bf09c0 100644 --- a/src/word-usage.adoc +++ b/src/word-usage.adoc @@ -1,18 +1,18 @@ == Word usage -Above:: Avoid using directional words. Above and below do not translate well to screen readers. Instead, use "previous" or "following". +Above:: Avoid using directional words. Above and below do not translate well to screen readers. Instead, use "previous" or "following". Acronyms:: Acronyms and other shortened forms of words must spell out the acronym at first use in a section. Also, please add them to the [https://github.com/riscv/riscv-glossary/blob/main/src/glossary.adoc]glossary for a handy reference. After (once):: Use "after" to indicate a sequence of events. Use "once" to indicate "one time". -Also:: use to mean additionally rather than alternatively. +Also:: use to mean additionally rather than alternatively. As:: Don't use "as" to mean "because". Don't say "Use the correct version as the wrong version can cause issues." Instead, "Use the correct version because the wrong version can cause issues." -Can (might, must, may, should, shall, will):: -- Use "can" to indicate capability: "This option can cause your system to fail." +Can (might, must, may, should, shall, will):: +- Use "can" to indicate capability: "This option can cause your system to fail." - Use "might" to indicate possibility: "This option might affect your system performance." - Don't use "may," which is ambiguous because it could mean either capability or permission. - Use "should" to indicate a recommended, but optional action. Consider using an alternative phrase instead, such as "we recommend." Do not use "should" to indicate something that might happen. "After you push the power button, the system should turn on." Instead, be bold! "After you push the power button, the system turns on." @@ -28,7 +28,7 @@ Use whether to indicate choice or alternative. Event a happens, whether event b Latin phrases:: Avoid abbreviations such as etc., e.g., i.e. They do not translate well. Instead use "and so on" and "for example,". -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". +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". Left (and right):: Avoid using these words if at all possible. If you do use them, use "left" and "right" and not "lefthand" or "righthand". @@ -39,8 +39,8 @@ Numbers:: Use Arabic for numbers greater than 10. Use words for numbers 1 throug - If there is a mix of numbers less and greater than 10, use Arabic. - Use the word if the number begins a sentence. So if the number is a value, rewrite the sentence so that the number doesn't begin the sentence. -Prior (versus "before," "previous," or "preceding"):: -- If possible, replace "prior to" with "before" as "before" is a little less formal. +Prior (versus "before," "previous," or "preceding"):: +- If possible, replace "prior to" with "before" as "before" is a little less formal. - Use "previous" to indicate something that occurred at an unspecified time earlier. - Use "preceding" to indicate something that occurred immediately before. @@ -58,5 +58,4 @@ This, those, these:: Provide a noun after words such as this, those, and these. Time frame:: Write as 2 words, no hyphen. -Using:: Try not to use "using" by itself. Replace with "by using" or "with". "Using" can be either a noun or a participle, which can causing translation issues. You can use "Using" at the beginning of a sentence such as "Using RISC-V standards to design your chip". - +Using:: Try not to use "using" by itself. Replace with "by using" or "with". "Using" can be either a noun or a participle, which can causing translation issues. You can use "Using" at the beginning of a sentence such as "Using RISC-V standards to design your chip".