65 rename normative rule curation to normative rule creation easier to explain

normative-rules.md

@@ -46,9 +46,28 @@ AsciiDoc supports several styles of anchors:
     >
     > `This isn't part of the anchor since it is the next paragraph.`
 
-* You can also use the _paragraph anchor_ for table cells and list items if placed before the text such as:
-
-    > `| [[foo]] Here is the table cell contents | next cell`
+* You must use the _paragraph anchor_ for table cells, list items, or description list terms
+  * For table cells and list items, put the anchor before its associated text as follows:
+    * Table cell<br>
+    > `| [[foo]] Here are the table cell contents | next cell`
+    * List item<br>
+    > `* [[foo]] Here is the list item`
+  * For description list terms (e.g., `Apples`, `Oranges`), put the anchor immediately after the term on its own line as follows:
+    > `Apples::`<br>
+    > `[[apple-colors]]`<br>
+    > `Typically be red, yellow, or green.`<br>
+    > <br>
+    > `Oranges:: Generally orange in color`<br>
+    > <br>
+    > `Bananas::`<br>
+    > `[[banana-color]]`<br>
+    > `Generally yellow in color`
+    * These won't work
+    > * `Bananas:: [[banana-color]] Generally yellow in color`<br>
+    > * `[[banana-color]] Bananas:: Generally yellow in color`
+    > * `[[banana-color]]`<br>
+    > `Bananas::`<br>
+    > `Generally yellow in color`
 
 Naming restrictions:
 * Start anchor names with a letter and use `:` to separate fields in the anchor name. No spaces allowed in name.
@@ -67,27 +86,32 @@ If you'd like to get more detailed AsciiDoc information on anchors, please read:
     > Syntax:      `[#<anchor-name>]# ... #`<br>
     > Example:     `Here is an example of [#foo]#anchoring part# of a paragraph
     >              and can have [#bar]#multiple anchors# if needed.`<br>
-    > Tagged text: `anchoring part` and `multiple anchors`
-
-2. Limitations:
-* Can't anchor text across multiple paragraphs.
-* Must have text next to the 2nd hash symbol (i.e., can't have newline after `[#<anchor-name]#`).
-* Can't put inside admonitions such as [NOTE] (see #5 below for solution).
-* Can't have `.` in anchor-name (replace with `-`)
+    > Tagged text: `anchoring part` and `multiple anchors`<br>
+    >
+    > Limitations:
+    > * Can't anchor text across multiple paragraphs.
+    > * Can't use in table cells, list items, or description list items (see #3 below for work-around).
+    > * Must have text next to the 2nd hash symbol (i.e., can't have newline after `[#<anchor-name]#`).
+    > * Can't put inside admonitions such as [NOTE] (see #5 below for solution).
+    > * Can't have `.` in anchor-name (replace with `-`)
 
-3. Anchor to entire paragraph
+2. Anchor to entire paragraph
 
     > Syntax:     `[[<anchor-name]]`<br>
     > Example:    `[[zort]]`<br>
     >             `Here is an example of anchoring a whole paragraph.`<br>
     > Tagged text: Entire paragraph<br>
 
-4. Anchor to entire table cell or a list entry
+3. Anchor to entire table cell, list entry, or description list entry
 
     > Example:    `| Alan Turing | [[Alan_Turing_Birthday]] June 23, 1912 | London`<br>
     > Tagged text: None (just creates hyperlink to anchor in table/list so not so useful)
+    >
+    > Limitations:
+    >  * Anchor must be to entire contents of cell/item.
+    >  * Only one anchor per cell/item.
 
-5. Anchor inside admonition (e.g. `[NOTE]`):
+4. Anchor inside admonition (e.g. `[NOTE]`):
 * Must use `[[<anchor-name]]` before each paragraph (with unique anchor names of course) being tagged
 * Can't use `[#<anchor-name]#Here's some note text.#` since it just shows up in HTML as normal text
 * Don't put `[[<<anchor-name]]` before the entire admonition (e.g., before `[NOTE]`) to apply to entire admonition