Improve test cases and doc for norm rules

Signed-off-by: James Ball <jameball@qti.qualcomm.com>

Author: james-ball-qualcomm

normative-rules.md

@@ -51,8 +51,8 @@ AsciiDoc supports several styles of anchors:
 Naming restrictions:
 * Start anchor names with a letter and use `:` to separate fields in the anchor name. No spaces allowed in name.
 * Use underscores to separate lists of items between colons (e.g., `:insts:add_sub`) since RISC-V
-uses `-` in some names (e.g., `R-type`).
-* Replace `.` in items with `-` (e.g., `fence.tso` becomes `fence-tso`) so all anchors types used
+uses hyphens in some names (e.g., `R-type`).
+* Replace `.` in items with a hyphen (e.g., `fence.tso` becomes `fence-tso`) so all anchors types used
 work properly (see https://docs.asciidoctor.org/asciidoc/latest/attributes/id/#block-assignment for details).
 
 If you'd like to get more detailed AsciiDoc information on anchors, please read:
@@ -89,6 +89,12 @@ If you'd like to see detailed AsciiDoc examples of tagging cases, see https://gi
     >> `Bananas::`<br>
     >> `Typically yellow`<br>
     >> Tagged text: Entire description list
+    >
+    > Limitations:
+    > * Only one paragraph tag per paragraph. Only the last tag is detected so you can't do:
+    >>> `[norm:abc]`<br>
+    >>> `[xyz]`<br>
+    >>> `Here's my paragraph with 2 tags but we only get an anchor for xyz. However since it doesn't start with norm: we won't see any tag for this paragraph.`
 
 2. Tagging part of a paragraph, table cells, unordered list items (AKA bullet list), or ordered list items (AKA numbered list)
 
@@ -111,10 +117,12 @@ If you'd like to see detailed AsciiDoc examples of tagging cases, see https://gi
     >> Tagged text: `mango` and `apple`<br>
     >
     > Limitations:
-    > * Can't anchor text across multiple paragraphs.
+    > * Can't anchor text across multiple AsciiDoc blocks (any text separated by blank line) such as paragraphs.
+        This also includes text followed by a list (ordered, unordered, description) since there has to be
+        a blank line between the text the list.
     > * 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 #4 below for solution).
-    > * Can't have `.` in anchor-name (replace with `-`)
+    > * Can't have `.` in anchor-name (replace with hyphen)
 
 3. Tagging description lists
   * For description list terms (e.g., `Apples`, `Oranges`), put the anchor immediately after the term on its own line as follows:

tests/norm-rule/expected/test-norm-rules.xlsx

@@ -5,6 +5,7 @@
     "norm:paragraph:inline-anchors:inline-anchor": "inline anchor",
     "norm:paragraph:inline-anchors:entire": "Paragraph with inline anchor and something.",
     "norm:paragraph:tag_with_newlines": "Here’s the first line. Here’s the second line.",
+    "norm:def": "This paragraph has two tags but we only ever get a tag for norm:def.",
     "norm:table:no-anchors-in-cells:entire-table": "Header 1|Header 2\n===\nCell in column 1, row 1|Cell in column 2, row 1\nCell in column 1, row 2|Cell in column 2, row 2\n===",
     "norm:table:anchors-in-cells:cell": "cell with anchor",
     "norm:table:anchors-in-cells:entire-table": "===\ncell with anchor\ncell without anchor\n===",
@@ -53,7 +54,8 @@
               "norm:paragraph:no-inline-anchors",
               "norm:paragraph:inline-anchors:inline-anchor",
               "norm:paragraph:inline-anchors:entire",
-              "norm:paragraph:tag_with_newlines"
+              "norm:paragraph:tag_with_newlines",
+              "norm:def"
             ]
           },
           {

tests/norm-rule/expected/test-norm-tags.json

@@ -8,10 +8,21 @@
 // PASSES
 Before inline [#norm:inline]#inside inline# outside inline.
 
-// SHOULD ALWAYS FAIL
-Before bad inline [#norm:bad-inline]#
+// SHOULD ALWAYS FAIL - Can't put inline tag at end of line.
+Before bad inline [#norm:bad-inline-1]#
 inside bad inline# outside bad inline.
 
+// SHOULD ALWAYS FAIL - Can't span blocks (paragraphs in this case)
+Before bad inline [#norm:bad-inline-2]#inside bad inline.
+
+Next paragraph# outside.
+
+// SHOULD ALWAYS FAIL - Can't span blocks (list in this case)
+Before bad inline [#norm:bad-inline-3]#inside bad inline:
+
+* Unordered list line 1#
+* Unordered list line 2
+
 === Chapter 1.2 - Paragraph Tagging
 
 // PASSES
@@ -31,6 +42,15 @@ Next paragraph 2
 Here's the first line.
 Here's the second line.
 
+// FAILS - Can't have multiple paragraph tags (only last works)
+[[norm:abc]]
+[[norm:def]]
+This paragraph has two tags but we only ever get a tag for norm:def.
+
+[[norm:abc]]
+[[def]]
+This paragraph has two tags but we'll never see either since the 1st isn't picked up by the tags backend as a tag and the second doesn't start with norm:
+
 === Chapter 2 - Table Tagging
 
 // FAILS - Tag includes entire table but has adoc === prefixes/suffixes.