Merge pull request #119 from riscv/118-display-kind-and-instances

Cleaning up norm rule schema to remove unused features and add more flexibility

Author: james-ball-qualcomm

schemas/common-schema.json

@@ -10,10 +10,13 @@
     "description": "Comprehensive description of the normative rule (sentence, paragraph, or longer)"
   },
   "kindRuleDesc": {
-    "description": "The kind of ISA object associated with this normative rule"
+    "description": "The kind of standards object associated with this normative rule"
+  },
+  "instanceRuleDesc": {
+    "description": "The name of a standards object of the specified kind associated with this normative rule"
   },
   "instancesRuleDesc": {
-    "description": "The names of ISA object instances of the specified kind associated with this normative rule"
+    "description": "The names of standards objects of the specified kind associated with this normative rule"
   },
   "stringArray": {
     "type": "array",
@@ -25,7 +28,7 @@
   "tagNamePattern" : {
     "pattern": "^[a-zA-z][:a-zA-z0-9_-]+$"
   },
-  "isaObjectKind":  {
+  "stdsObjectKind":  {
     "type": "string",
     "enum": ["extension", "instruction", "csr", "csr_field", "parameter"]
   },
@@ -44,29 +47,11 @@
     "type": "string",
     "$ref": "#/tagNamePattern"
   },
-  "tagObject": {
-    "type": "object",
-    "properties": {
-      "name": { "$ref": "#/tagName" },
-      "kind": {
-        "$ref": "#/isaObjectKind",
-        "description": "The kind of ISA object associated with this tag"
-      },
-      "instances": {
-        "$ref": "#/stringArray",
-        "description": "The names of ISA object instances of the specified kind associated with this tag"
-      }
-    },
-    "required": ["name"],
-    "additionalProperties": false
-  },
-  "tagArray": {
+  "tagNameArray": {
     "type": "array",
     "items": {
-      "anyOf": [
-        { "$ref": "#/tagName" },
-        { "$ref": "#/tagObject" }
-      ]
+      "type": "string",
+      "$ref": "#/tagNamePattern"
     }
   }
 }

schemas/defs-schema.json

@@ -9,7 +9,7 @@
     },
     "chapter_name": {
       "type": "string",
-      "description": "Name of chapter in standards doc associated with these normative rules definitions"
+      "description": "Name of chapter (keep it short) in standards document associated with normative rules definitions"
     },
     "normative_rule_definitions": {
       "type": "array",
@@ -34,32 +34,46 @@
           },
           "kind": {
             "allOf": [
-              { "$ref": "common-schema.json#/isaObjectKind" },
+              { "$ref": "common-schema.json#/stdsObjectKind" },
               { "$ref": "common-schema.json#/kindRuleDesc" }
             ]
           },
+          "instance": {
+            "type": "string",
+            "$ref": "common-schema.json#/instanceRuleDesc"
+          },
           "instances": {
             "allOf": [
               { "$ref": "common-schema.json#/stringArray" },
               { "$ref": "common-schema.json#/instancesRuleDesc" }
             ]
           },
-          "tags": {
-            "$ref": "common-schema.json#/tagArray",
-            "description": "List of normative rule tags that have normative text from adoc files"
+          "tag": {
+            "$ref": "common-schema.json#/tagName",
+            "description": "Name of tag containing normative text"
           },
-          "tags_without_text": {
-            "$ref": "common-schema.json#/tagArray",
-            "description": "List of normative rule tags that don't have normative text (just an anchor) from adoc files"
+          "tags": {
+            "$ref": "common-schema.json#/tagNameArray",
+            "description": "List of tag names containing normative text"
           }
         },
-        "oneOf": [
-          { "required": ["name"] },
-          { "required": ["names"] }
-        ],
-        "anyOf": [
-          { "required": ["tags"] },
-          { "required": ["tags_without_text"] }
+        "allOf": [
+          {
+            "oneOf": [
+              { "required": ["name"] },
+              { "required": ["names"] }
+            ]
+          },
+          {
+            "not": {
+              "required": ["tag", "tags"]
+            }
+          },
+          {
+            "not": {
+              "required": ["instance", "instances"]
+            }
+          }
         ],
         "additionalProperties": false
       }

schemas/norm-rules-schema.json

@@ -31,7 +31,7 @@
           },
           "kind": {
             "allOf": [
-              { "$ref": "common-schema.json#/isaObjectKind" },
+              { "$ref": "common-schema.json#/stdsObjectKind" },
               { "$ref": "common-schema.json#/kindRuleDesc" }
             ]
           },

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

@@ -4,12 +4,17 @@
 
 [cols="20%,20%,60%"]
 |===
-| Rule Name | Link to Standard | Text from Standard
+| Rule Name | Info Source | Info Text
 
-.2+| inline
+.4+| inline
 | Summary | A few words
+| Kind | extension
+[Zicsr, ABC]
 a| link:test.html#norm:inline[norm:inline] | inside inline
 
+.1+| no_tag
+| Summary | Normative rule without tag/tags
+
 .2+| paragraph-with-a-really-wide-rule-name
 | Description | Here's a description.
 It's got 2 lines.
@@ -148,8 +153,10 @@ Paragraph 3
 a| link:test.html#norm:admonition:only-anchors-in-notes:note1[norm:admonition:only-anchors-in-notes:note1] | Paragraph X
 a| link:test.html#norm:admonition:only-anchors-in-notes:note3[norm:admonition:only-anchors-in-notes:note3] | Paragraph Z
 
-.3+| admon5
+.5+| admon5
 | Description | One line description
+| Kind | parameter
+[MY_PARAMETER]
 a| link:test.html#norm:admonition:anchors-in-notes:note1[norm:admonition:anchors-in-notes:note1] | Paragraph 1
 a| link:test.html#norm:admonition:anchors-in-notes:note3[norm:admonition:anchors-in-notes:note3] | Paragraph 3
 |===

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

@@ -106,18 +106,31 @@ <h3>my-chapter_name</h3>
             <col class="col-text">
           </colgroup>
           <thead>
-            <tr><th>Rule Name</th><th>Link to Standard</th><th>Text from Standard</th></tr>
+            <tr><th>Rule Name</th><th>Info Source</th><th>Info Text</th></tr>
           </thead>
           <tbody>
             <tr>
-              <td rowspan=2>inline</td>
+              <td rowspan=4>inline</td>
               <td>Summary</td>
               <td>A few words</td>
             </tr>
+            <tr>
+              <td>Kind</td>
+              <td>extension</td>
+            </tr>
+            <tr>
+              <td>Instances</td>
+              <td>[Zicsr, ABC]</td
+            </tr>
             <tr>
               <td><a href="test.html#norm:inline">norm:inline</a></td>
               <td>inside inline</td></tr>
             </tr>
+            <tr>
+              <td rowspan=1>no_tag</td>
+              <td>Summary</td>
+              <td>Normative rule without tag/tags</td>
+            </tr>
             <tr>
               <td rowspan=2>paragraph-with-a-really-wide-rule-name</td>
               <td>Description</td>
@@ -275,10 +288,18 @@ <h3>my-chapter_name</h3>
               <td>Paragraph Z</td></tr>
             </tr>
             <tr>
-              <td rowspan=3>admon5</td>
+              <td rowspan=5>admon5</td>
               <td>Description</td>
               <td>One line description</td>
             </tr>
+            <tr>
+              <td>Kind</td>
+              <td>parameter</td>
+            </tr>
+            <tr>
+              <td>Instances</td>
+              <td>[MY_PARAMETER]</td
+            </tr>
             <tr>
               <td><a href="test.html#norm:admonition:anchors-in-notes:note1">norm:admonition:anchors-in-notes:note1</a></td>
               <td>Paragraph 1</td></tr>

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

@@ -18,6 +18,13 @@
         }
       ]
     },
+    {
+      "name": "no_tag",
+      "def_filename": "tests/norm-rule/test.yaml",
+      "chapter_name": "my-chapter_name",
+      "summary": "Normative rule without tag/tags",
+      "tags": []
+    },
     {
       "name": "paragraph-with-a-really-wide-rule-name",
       "def_filename": "tests/norm-rule/test.yaml",

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

@@ -12,78 +12,80 @@ normative_rule_definitions:
     summary: A few words
     kind: extension
     instances: [Zicsr, ABC]
-    tags: ["norm:inline"]
+    tag: "norm:inline"
+  - name: no_tag
+    summary: Normative rule without tag/tags
 
   # Paragraph
   - name: paragraph-with-a-really-wide-rule-name
     description: |
       Here's a description.
       It's got 2 lines.
-    tags: ["norm:paragraph:no-inline-anchors"]
+    tag: "norm:paragraph:no-inline-anchors"
   - name: inline-anchors-in-paragraph-entire
-    tags: ["norm:paragraph:inline-anchors:entire"]
+    tag: "norm:paragraph:inline-anchors:entire"
   - name: inline-anchors-in-paragraph-inline-anchor
-    tags: ["norm:paragraph:inline-anchors:inline-anchor"]
+    tag: "norm:paragraph:inline-anchors:inline-anchor"
   - name: formulae
-    tags: ["norm:formulae"]
+    tag: "norm:formulae"
   - name: rule_with_newlines
-    tags: ["norm:paragraph:tag_with_newlines"]
+    tag: "norm:paragraph:tag_with_newlines"
   - name: double_tags
-    tags: ["norm:def"]
+    tag: "norm:def"
 
   # Table
   - name: table1
-    tags: ["norm:table:anchors-in-cells:entire-table"]
+    tag: "norm:table:anchors-in-cells:entire-table"
   - name: table2
-    tags: ["norm:table:no-anchors-in-cells:entire-table"]
+    tag: "norm:table:no-anchors-in-cells:entire-table"
   - name: table3
-    tags: ["norm:table:anchors-in-cells:entire-table-tagged:cell"]
+    tag: "norm:table:anchors-in-cells:entire-table-tagged:cell"
   - name: table4
-    tags: ["norm:table:anchors-in-cells:entire-table-not-tagged:cell"]
+    tag: "norm:table:anchors-in-cells:entire-table-not-tagged:cell"
   - name: table5
-    tags: ["norm:table:many-rows"]
+    tag: "norm:table:many-rows"
 
   # Unordered lists
   - name: unordered1
-    tags: ["norm:unordered-list:no-anchors-in-items:entire-list"]
+    tag: "norm:unordered-list:no-anchors-in-items:entire-list"
   - name: unordered2
-    tags: ["norm:unordered-list:anchors-in-items:entire-list"]
+    tag: "norm:unordered-list:anchors-in-items:entire-list"
   - name: unordered3
-    tags: ["norm:unordered-list:anchors-in-items:item1"]
+    tag: "norm:unordered-list:anchors-in-items:item1"
   - name: unordered4
-    tags: ["norm:unordered-list:anchors-in-items:item2"]
+    tag: "norm:unordered-list:anchors-in-items:item2"
   - name: unordered5
-    tags: ["norm:unordered-list:multiple-levels"]
+    tag: "norm:unordered-list:multiple-levels"
 
   # Ordered lists
   - name: ordered1
-    tags: ["norm:ordered-list:no-anchors-in-items:entire-list"]
+    tag: "norm:ordered-list:no-anchors-in-items:entire-list"
   - name: ordered2
-    tags: ["norm:ordered-list:anchors-in-items:entire-list"]
+    tag: "norm:ordered-list:anchors-in-items:entire-list"
   - name: ordered3
-    tags: ["norm:ordered-list:anchors-in-items:item1"]
+    tag: "norm:ordered-list:anchors-in-items:item1"
   - name: ordered4
-    tags: ["norm:ordered-list:anchors-in-items:item2"]
+    tag: "norm:ordered-list:anchors-in-items:item2"
 
   # Description lists
   - name: desc1
-    tags: ["norm:description-list:no-anchors-in-items:entire-list"]
+    tag: "norm:description-list:no-anchors-in-items:entire-list"
   - name: desc2
-    tags: ["norm:description-list:anchors-in-items:entire-list"]
+    tag: "norm:description-list:anchors-in-items:entire-list"
   - names: [desc3, desc4]
     tags: ["norm:description-list:anchors-in-items:item1", "norm:description-list:anchors-in-items:item3"]
 
   # Admonitions
   - name: admon1
-    tags: ["norm:admonition:single-paragraph-note"]
+    tag: "norm:admonition:single-paragraph-note"
   - name: admon2
-    tags: ["norm:admonition:no-anchors-in-notes:entire-note"]
+    tag: "norm:admonition:no-anchors-in-notes:entire-note"
   - name: admon3
-    tags: ["norm:admonition:anchors-in-notes:entire-note"]
+    tag: "norm:admonition:anchors-in-notes:entire-note"
   - name: admon4
     tags: ["norm:admonition:only-anchors-in-notes:note1", "norm:admonition:only-anchors-in-notes:note3"]
   - name: admon5
     description: One line description
     kind: parameter
-    instances: [MY_PARAMETER]
+    instance: MY_PARAMETER
     tags: ["norm:admonition:anchors-in-notes:note1", "norm:admonition:anchors-in-notes:note3"]