From 3289a25f8f47d9943794b285cca426bf486707ca Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Tue, 30 Jul 2024 10:48:19 -0500 Subject: [PATCH 1/6] fixing up pre-commit checks --- src/a_few_basics.adoc | 2 +- src/graphics.adoc | 4 +- src/index_bib.adoc | 2 +- src/style-guidelines.adoc | 75 +++++++++++++++++++----------------- src/tables_symbols_math.adoc | 15 +++++--- src/word-usage.adoc | 2 +- 6 files changed, 55 insertions(+), 45 deletions(-) diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc index ad47985..ce18769 100644 --- a/src/a_few_basics.adoc +++ b/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 diff --git a/src/graphics.adoc b/src/graphics.adoc index ded9618..cf435aa 100644 --- a/src/graphics.adoc +++ b/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.) diff --git a/src/index_bib.adoc b/src/index_bib.adoc index 265fe17..c1c7fe0 100644 --- a/src/index_bib.adoc +++ b/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 diff --git a/src/style-guidelines.adoc b/src/style-guidelines.adoc index 8e88b55..ea40edb 100644 --- a/src/style-guidelines.adoc +++ b/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,16 +76,17 @@ 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"] @@ -90,13 +94,14 @@ Use simple and direct language. Avoid using unnecessary phrases, such as saying |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. @@ -113,32 +118,32 @@ Prefer English terms over Latin abbreviations. |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,57 @@ 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 ... |=== diff --git a/src/tables_symbols_math.adoc b/src/tables_symbols_math.adoc index 91ce134..014ab28 100644 --- a/src/tables_symbols_math.adoc +++ b/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] ==== diff --git a/src/word-usage.adoc b/src/word-usage.adoc index bd27d9d..e6f3766 100644 --- a/src/word-usage.adoc +++ b/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". From 154105db7fd369f4ad3b2d4ee9c1da3198750b68 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Tue, 30 Jul 2024 10:55:56 -0500 Subject: [PATCH 2/6] fixing --- src/style-guidelines.adoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/style-guidelines.adoc b/src/style-guidelines.adoc index ea40edb..6e0dab5 100644 --- a/src/style-guidelines.adoc +++ b/src/style-guidelines.adoc @@ -111,7 +111,7 @@ Prefer English terms over Latin abbreviations. |Yes |No -|For example, ... +|For example, ... |e.g., ... |That is, ... From 4923da730f53b3e16466b6669d583232edd8e890 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Tue, 30 Jul 2024 11:48:48 -0500 Subject: [PATCH 3/6] last change --- src/images/bytefield/examplebyte.adoc | 2 +- src/style-guidelines.adoc | 1 - 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/src/images/bytefield/examplebyte.adoc b/src/images/bytefield/examplebyte.adoc index f54092c..ced2c21 100644 --- a/src/images/bytefield/examplebyte.adoc +++ b/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 {}}) ----- \ No newline at end of file +---- diff --git a/src/style-guidelines.adoc b/src/style-guidelines.adoc index 6e0dab5..4132b5b 100644 --- a/src/style-guidelines.adoc +++ b/src/style-guidelines.adoc @@ -206,4 +206,3 @@ Avoid words such as "just", "simply", "easy", "easily", or "simple". These words |These steps ... |These simple steps ... |=== - From 5f7dff44b5964afd8b346841e4ab40a32dc794d0 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Tue, 30 Jul 2024 11:52:31 -0500 Subject: [PATCH 4/6] spaces --- src/blocks_notes_markers.adoc | 1 - src/graphics.adoc | 2 -- 2 files changed, 3 deletions(-) diff --git a/src/blocks_notes_markers.adoc b/src/blocks_notes_markers.adoc index b0c2581..3c61721 100644 --- a/src/blocks_notes_markers.adoc +++ b/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[] - diff --git a/src/graphics.adoc b/src/graphics.adoc index cf435aa..60e2d8d 100644 --- a/src/graphics.adoc +++ b/src/graphics.adoc @@ -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 <> ) 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. - - From 903c79a12a4b94ca73b71ea2d1c7c532c0a8c907 Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Tue, 30 Jul 2024 11:55:16 -0500 Subject: [PATCH 5/6] more space --- src/authoring.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/src/authoring.adoc b/src/authoring.adoc index 0eea7cb..1c21b21 100644 --- a/src/authoring.adoc +++ b/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] - From ef98956d3a1190073738a71019299558a309585a Mon Sep 17 00:00:00 2001 From: Kersten Richter Date: Tue, 30 Jul 2024 11:56:52 -0500 Subject: [PATCH 6/6] yet another --- src/a_few_basics.adoc | 1 - 1 file changed, 1 deletion(-) diff --git a/src/a_few_basics.adoc b/src/a_few_basics.adoc index ce18769..26f72f9 100644 --- a/src/a_few_basics.adoc +++ b/src/a_few_basics.adoc @@ -185,4 +185,3 @@ This example renders as: <> describes how index markers work. For more information about options, see https://docs.asciidoctor.org/asciidoc/latest/macros/xref/#internal-cross-references[Cross References]. -