Skip to content

Commit

Permalink
fix pre-commit failures
Browse files Browse the repository at this point in the history
just ran `pre-commit run --all-files`
related to #36
  • Loading branch information
kbroch-rivosinc committed May 17, 2024
1 parent eeeb4bd commit fc57ff4
Show file tree
Hide file tree
Showing 5 changed files with 27 additions and 39 deletions.
2 changes: 0 additions & 2 deletions src/a_few_basics.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -157,5 +157,3 @@ kind of trap.
|Software is oblivious |No |No |Yes |Yeslatexmath:[$^{2}$]
|Handled by environment |No |Yes |Yes |Yes
|===


4 changes: 0 additions & 4 deletions src/graphics.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 <<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.
19 changes: 8 additions & 11 deletions src/style-guidelines.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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 ...
|===

Expand All @@ -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 ..
|===



24 changes: 11 additions & 13 deletions src/tables_symbols_math.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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
|===

Expand All @@ -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
Expand All @@ -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
Expand All @@ -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

Expand Down Expand Up @@ -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.


17 changes: 8 additions & 9 deletions src/word-usage.adoc
Original file line number Diff line number Diff line change
@@ -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."
Expand All @@ -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".

Expand All @@ -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.

Expand All @@ -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".

0 comments on commit fc57ff4

Please sign in to comment.