Updates!

src/a_few_basics.adoc

@@ -26,16 +26,18 @@ Send questions to help@riscv.org.
 
 In AsciiDoc, normal paragraphs do not require markup.
 
+To create a new paragraph, put a space after the previous line of text and continue.
+
 ==== Basics of blocks and indents
 
-  If you simply add an indent, your indented text becomes a block like this.
+  If you add an indent, your indented text becomes a block like this.
 
 * You can add indented, explanatory paragraphs to lists.
 +
 Add a `+` directly above the line of text that you want to be indented within the list.
 * Another point.
 +
-Using the `+` to create an indented paragraph only works within the context of a numbered or bulleted list.
+Using the `+` to create an indented paragraph works only within the context of a numbered or bulleted list.
 
 AsciiDoc/Asciidoctor supports code blocks with syntax highlighting for many languages. You can use either periods or dashes to indicate code blocks, and use macros to indicate that the block contains code in the specified language, as in the following example:
 
@@ -91,24 +93,30 @@ NOTE: Settings in the header file (`book_header.adoc` in the docs-templates repo
 
 === Lists
 
-Unordered list
+Unordered lists are created with the `*` before the list item. Ordered lists require a `.` Add a space between any supporting text at the beginning of a list.
+
+==== Unordered list
+
 * Priv
 * Unpriv
 * Debug
 
-Ordered list
+==== Ordered list
+
 . Priv
 . Unpriv
 . Debug
 
-Nested list
+==== Nested list
+
 * Priv
 ** Intro
 *** Definitions
 ** CSRs
 * Unpriv
 
-Add a title to a list
+==== Add a title to a list
+
 .Ordered list
 . Priv
 . Unpriv
@@ -118,8 +126,8 @@ Add a title to a list
 
 Asciidoctor automates some linking as follows:
 
-* Asciidoctor recognizes hyperlinks to Web pages and shortens them for readability.
-* Asciidoctor automatically creates an anchor for every section and discrete heading.
+* Recognizes hyperlinks to Web pages and shortens them for readability.
+* Automatically creates an anchor for every section and discrete heading.
 
 ==== Hyperlinks
 
@@ -146,6 +154,8 @@ 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].
+
 
 The `book_header.adoc` file in the docs-templates repo sets the `full` cross-reference attribute to enable captions to display from targets in the anchors. This ability allows you to set captions for tables, blocks, and illustrations. If you do not provide a caption, Asciidoctor defaults to the _basic_ cross reference style.
 

src/tables_symbols_math.adoc

@@ -1,10 +1,17 @@
 [[tables_symbols_math]]
 == Tables, symbols, and math
 
-Asciidoc makes standard tables easy and also supports the creation of complex tables. As a general rule, do not present new information in tables
+Asciidoc makes standard tables easy and also supports the creation of complex tables. 
 
 === Table rules
 
+- 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. 
+- 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".
+
 ==== Table formatting
 
 - Align tables to center with the options `float="center"` and `align="center"`.
@@ -16,13 +23,21 @@ Asciidoc makes standard tables easy and also supports the creation of complex ta
 - 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
+==== Column header formatting
 
 - 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.
 
+
+==== Punctuation in 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.
@@ -98,6 +113,10 @@ Either table renders with table headers.
 |Cell in col 3, row 2
 |===
 
+=== Table captions
+
+
+
 
 === Asciidoc tables from CSV data.