Merge pull request #141 from riscv/140-add-optional-note-keyword-for-normative-rules

Added note keyword and added to unit test

Author: james-ball-qualcomm

schemas/common-schema.json

@@ -6,6 +6,9 @@
   "summaryDesc": {
     "description": "Short summary of the normative rule (just a few words)"
   },
+  "noteDesc": {
+    "description": "A note about the normative rule"
+  },
   "descriptionDesc": {
     "description": "Comprehensive description of the normative rule (sentence, paragraph, or longer)"
   },

schemas/defs-schema.json

@@ -28,6 +28,10 @@
             "type": "string",
             "$ref": "common-schema.json#/summaryDesc"
           },
+          "note": {
+            "type": "string",
+            "$ref": "common-schema.json#/noteDesc"
+          },
           "description": {
             "type": "string",
             "$ref": "common-schema.json#/descriptionDesc"

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

@@ -12,8 +12,9 @@
 | [Zicsr, ABC] | Rule Instances
 | inside inline a| link:test.html#norm:inline[norm:inline]
 
-.1+| no_tag
+.2+| no_tag
 | Normative rule without tag/tags | Rule's 'summary' property
+| This normative rule has no references to the standard. This should only be used in extraordinary circumstances. | Rule's 'note' property
 
 .1+| inline-with-hash
 | includes a hash # symbol. a| link:test.html#norm:inline-with-hash[norm:inline-with-hash]

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

@@ -130,10 +130,14 @@ <h3>my-chapter_name</h3>
               <td><a href="test.html#norm:inline">norm:inline</a></td>
             </tr>
             <tr>
-              <td rowspan=1 id="no_tag">no_tag</td>
+              <td rowspan=2 id="no_tag">no_tag</td>
               <td>Normative rule without tag/tags</td>
               <td>Rule's "summary" property</td>
             </tr>
+            <tr>
+              <td>This normative rule has no references to the standard. This should only be used in extraordinary circumstances.</td>
+              <td>Rule's "note" property</td>
+            </tr>
             <tr>
               <td rowspan=1 id="inline-with-hash">inline-with-hash</td>
               <td>includes a hash # symbol.</td>

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

@@ -24,6 +24,7 @@
       "def_filename": "tests/norm-rule/test.yaml",
       "chapter_name": "my-chapter_name",
       "summary": "Normative rule without tag/tags",
+      "note": "This normative rule has no references to the standard. This should only be used in extraordinary circumstances.",
       "tags": []
     },
     {

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

@@ -15,6 +15,7 @@ normative_rule_definitions:
     tag: "norm:inline"
   - name: no_tag
     summary: Normative rule without tag/tags
+    note: This normative rule has no references to the standard. This should only be used in extraordinary circumstances.
   - name: inline-with-hash
     tag: "norm:inline-with-hash"
 

tests/norm-rule/test.yaml

@@ -147,6 +147,7 @@ class NormativeRuleDef
   attr_reader :def_filename           # String (mandatory)
   attr_reader :chapter_name           # String (mandatory)
   attr_reader :summary                # String (optional - a few words)
+  attr_reader :note                   # String (optional - as long as needed)
   attr_reader :description            # String (optional - sentence, paragraph, or more)
   attr_reader :kind                   # String (optional, can be nil)
   attr_reader :instances              # Array<String> (optional - can be empty)
@@ -167,6 +168,11 @@ def initialize(name, def_filename, chapter_name, data)
       fatal("Provided #{@summary.class} class for summary in normative rule #{name} but need a String") unless @summary.is_a?(String)
     end
 
+    @note = data["note"]
+    unless @note.nil?
+      fatal("Provided #{@note.class} class for note in normative rule #{name} but need a String") unless @note.is_a?(String)
+    end
+
     @description = data["description"]
     unless @description.nil?
       fatal("Provided #{@description.class} class for description in normative rule #{name} but need a String") unless @description.is_a?(String)
@@ -428,6 +434,7 @@ def create_normative_rules_hash(defs, tags, tag_fname2url)
     hash["kind"] = d.kind unless d.kind.nil?
     hash["instances"] = d.instances unless d.instances.empty?
     hash["summary"] = d.summary unless d.summary.nil?
+    hash["note"] = d.note unless d.note.nil?
     hash["description"] = d.description unless d.description.nil?
 
     unless d.tag_refs.nil?
@@ -720,6 +727,11 @@ def output_xlsx(filename, defs, tags)
       rule_def_sources.append("Rule Summary")
     end
 
+    unless d.note.nil?
+      rule_defs.append(d.note.chomp)
+      rule_def_sources.append("Rule Note")
+    end
+
     unless d.description.nil?
       rule_defs.append(d.description.chomp)
       rule_def_sources.append("Rule Description")
@@ -784,13 +796,19 @@ def output_adoc(filename, defs, tags, tag_fname2url)
       f.puts("| Rule Name | Rule Description | Origin of Description")
 
       nr_defs.each do |nr|
-        info_rows = (nr.summary.nil? ? 0 : 1) + (nr.description.nil? ? 0 : 1) +
-          (nr.kind.nil? ? 0 : 1) + (nr.instances.empty? ? 0 : 1) + nr.tag_refs.length
+        info_rows =
+          (nr.summary.nil? ? 0 : 1) +
+          (nr.note.nil? ? 0 : 1) +
+          (nr.description.nil? ? 0 : 1) +
+          (nr.kind.nil? ? 0 : 1) +
+          (nr.instances.empty? ? 0 : 1) +
+          nr.tag_refs.length
         row_span = (info_rows > 0) ? ".#{info_rows}+" : ""
 
         f.puts("")
         f.puts("#{row_span}| #{nr.name}")
         f.puts("| #{nr.summary} | Rule's 'summary' property") unless nr.summary.nil?
+        f.puts("| #{nr.note} | Rule's 'note' property") unless nr.note.nil?
         f.puts("| #{nr.description} | Rule's 'description' property") unless nr.description.nil?
         f.puts("| #{nr.kind} | Rule's 'kind' property") unless nr.kind.nil?
         f.puts('| [' + nr.instances.join(', ') + '] | Rule Instances') unless nr.instances.empty?
@@ -1001,8 +1019,13 @@ def html_chapter_table(f, table_num, chapter_name, nr_defs, tags, tag_fname2url)
   f.puts(%Q{          <tbody>})
 
   nr_defs.each do |nr|
-    name_row_span = (nr.summary.nil? ? 0 : 1) + (nr.description.nil? ? 0 : 1) +
-      (nr.kind.nil? ? 0 : 1) + (nr.instances.empty? ? 0 : 1) + nr.tag_refs.length
+    name_row_span =
+      (nr.summary.nil? ? 0 : 1) +
+      (nr.note.nil? ? 0 : 1) +
+      (nr.description.nil? ? 0 : 1) +
+      (nr.kind.nil? ? 0 : 1) +
+      (nr.instances.empty? ? 0 : 1) +
+      nr.tag_refs.length
 
     row_started = true
     f.puts(%Q{            <tr>})
@@ -1016,6 +1039,14 @@ def html_chapter_table(f, table_num, chapter_name, nr_defs, tags, tag_fname2url)
       row_started = false
     end
 
+    unless nr.note.nil?
+      f.puts(%Q{            <tr>}) unless row_started
+      f.puts(%Q{              <td>#{nr.note}</td>})
+      f.puts(%Q{              <td>Rule's "note" property</td>})
+      f.puts(%Q{            </tr>})
+      row_started = false
+    end
+
     unless nr.description.nil?
       f.puts(%Q{            <tr>}) unless row_started
       f.puts(%Q{              <td>#{convert_newlines_to_html(nr.description)}</td>})