Merge pull request #50 from riscv/reorg

bit of a reorg

src/docs-dev-guide.adoc

@@ -58,7 +58,7 @@ This document is released under a Creative Commons Attribution 4.0 International
 //the colophon allows for a section after the preamble that is part of the frontmatter and therefore not assigned a page number.
 include::colophon.adoc[]
 
-//While some documents need several levels of introductory material, other documents only need a brief introduction. You can choose to have either colophon or an overview, or to have both.
+//While some documents need several levels of introductory material, other documents need only a brief introduction. You can choose to have either colophon or an overview, or to have both.
 include::intro.adoc[]
 
 include::authoring.adoc[]
@@ -73,13 +73,13 @@ include::index_bib.adoc[]
 
 include::graphics.adoc[]
 
-include::writing.adoc[]
-
 include::style-guidelines.adoc[]
 
+include::writing.adoc[]
+
 include::linting.adoc[]
 
-//please note that the index must precede the bibliography for both to work within the same book.
+//Note that the index must precede the bibliography for both to work within the same book.
 include::index.adoc[]
 
 include::bibliography.adoc[]

src/style-guidelines.adoc

@@ -1,208 +1,71 @@
 == RISC-V Style guidelines
 [style-guidelines]
 
+Whether you are creating a new extention or even a stand alone doc for RISC-V, follow these style guidelines to improve readability.
+
+[[basic-rules]]
+=== Basic formatting
+
 Follow these basic formatting guidelines.
 
 * Use _italic_ for new terms.
 * Use `monospace` for filenames, directories, and paths.
-* Put punctuation outside of quotes, unless you are quoting someone directly.
 * Use `monospace` for inline code and commands.
 * 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.
+* Put punctuation outside of quotes, unless you are quoting someone directly.
+=======
 
-See the next section for rules about referring to a CSR.
+.Formatting guidelines for names
+* Instructions are lowercase (`ld`, `c`.`lw`)
+* Extensions are Capitialized (`A`, `C`, `Zicsr`)
+* CSR short names are lowercase (`misa`).
+* All of these names are in monospace.
 
 [[csr-rules]]
-=== Referring to CSRs or registers
+=== CSR formatting
 
 Use the following guidelines when you document a CSR:
 
-* CSR must always be capitalized.
+* The acronym 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…”
+* The word `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.
-* 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.”
+* Avoid starting a sentence with a CSR name. 
+* 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 monospace. So "Supervisor Status (`sstatus`) Register”. The rest of the references to that register can be "the `sstatus` CSR".
+* The short name is always lower case and monospace: `sstatus`.
+* 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 similar to this one:  “`misa` also helps distinguish different variants of a design.”  And instead use this one: “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.
 
-[[bp-gen]]
-=== General best practices
-
-
-This section contains suggested best practices for clear, concise, and consistent content.
-
-[[bp-present]]
-==== Use present tense
-
-
-[cols="1,1"]
-|===
-|Yes
-|No
-
-|Cache-management operation instructions perform operations on copies of data in the memory hierarchy.
-|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.
-
-[[bp-active]]
-==== Use active voice
-
-[cols="1,1"]
-|===
-|Yes
-|No
-
-|You can use the RVWMO memory model...
-|The RVWMO memory model can be used...
-
-|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."
-
-[cols="1,1"]
-|===
-|Yes
-|No
-
-|To build a chip, ...
-|In order to build a chip, ...
-
-|See the Hypervisor extension.
-|Please see the Hypervisor extension.
-
-|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 ...
-|We'll use the `misa` CSR  ...
-
-|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.
-
-[cols="1,1"]
-|===
-|Yes
-|No
-
-|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.
-
-[cols="1,1"]
-|===
-|Yes
-|No
-
-|Version 1.4 includes ...
-|In version 1.4, we have added ...
-
-|RISC-V provides a new feature for ...
-|We provide a new feature ...
-
-|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.
-
-[cols="1,1"]
-|===
-|Yes
-|No
-
-|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.
-
-An exception to this rule is documentation about announced deprecations targeting removal in future versions.
-
-[[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.
-
-[cols="1,1"]
-|===
-|Do
-|Don't
+[[table-rules]]
+=== Table formatting
 
-|In version 1.4, ...
-|In the current version, ...
+Follow these formatting rules when you create a table.
 
-|The pointer masking extension provides ...
-|The new pointer masking extension provides ...
-|===
+* 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. 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.
+* 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.
 
-[[bp-assume]]
-==== Avoid words that assume a specific level of understanding
+==== Column header formatting
 
-Avoid words such as "just", "simply", "easy", "easily", or "simple". These words do not add value and can actually make a user feel stupid.
+Follow these column header rules.
 
-[cols="1,1"]
-|===
-|Do
-|Don't
+* Use sentence case.
+* Write concise headings and omit articles (a, an, the).
+* 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.
 
-|Include one command in ...
-|Include just one command in ...
+==== Punctuation in tables
 
-|Run the command ...
-|Simply run the command ...
+Follow these punctuation rules for tables.
 
-|You can remove ...
-|You can easily remove ...
+* 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.
 
-|These steps ...
-|These simple steps ...
-|===

src/tables_symbols_math.adoc

@@ -14,39 +14,6 @@ Follow these general rules when you create a table.
 * 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.
-
-* 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. 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.
-* 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.
-
-
-[[tables-column-format]]
-==== Column header formatting
-
-Follow these column header rules.
-
-* Use sentence case.
-* Write concise headings and omit articles (a, an, the).
-* 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.
-
 [WARNING]
 ====
 *Never* use automated wrapping for table titles, figure captions, and example captions. Asciidoctor reads a hard return as an indicator to start a new "Normal" paragraph.