Merge pull request #123 from riscv/122-add-path-to-isa-manual-files

122 add path to URL of stds doc to norm-rule JSON output

Author: james-ball-qualcomm

Makefile

@@ -76,8 +76,8 @@ NORM_TAG_FILE_ARGS := $(foreach relative_pname,$(BUILT_NORM_TAGS_MAIN),-t /$(rel
 GOOD_NORM_RULE_DEF_ARGS := $(foreach relative_pname,$(GOOD_NORM_RULE_DEF_FILES),-d $(relative_pname))
 BAD_NORM_RULE_DEF_ARGS := $(foreach relative_pname,$(BAD_NORM_RULE_DEF_FILES),-d $(relative_pname))
 
-# Provide mapping from an standard's norm tags JSON file to its corresponding HTML file. Used to create links into standard's HTML files.
-NORM_RULE_DOC2HTML_ARGS := $(foreach doc_name,$(DOCS),-tag2html /$(BUILD_DIR)/$(doc_name)$(DOC_NORM_TAG_SUFFIX) $(doc_name).html)
+# Provide mapping from a stds doc norm tags JSON file to a URL that one can link to. Used to create links into stds doc.
+NORM_RULE_DOC2URL_ARGS := $(foreach doc_name,$(DOCS),-tag2url /$(BUILD_DIR)/$(doc_name)$(DOC_NORM_TAG_SUFFIX) $(doc_name).html)
 
 # Docker stuff
 DOCKER_BIN ?= docker
@@ -212,29 +212,29 @@ $(BUILT_NORM_RULES_JSON): $(BUILT_NORM_TAGS_MAIN) $(GOOD_NORM_RULE_DEF_FILES)
 	$(WORKDIR_SETUP)
 	cp -f $(BUILT_NORM_TAGS_MAIN) $@.workdir
 	mkdir -p $@.workdir/build
-	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -j $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $@ $(DOCKER_QUOTE)
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -j $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $(NORM_RULE_DOC2URL_ARGS) $@ $(DOCKER_QUOTE)
 	$(WORKDIR_TEARDOWN)
 
 # Build normative rules with XLSX output format
 $(BUILT_NORM_RULES_XLSX): $(BUILT_NORM_TAGS_MAIN) $(GOOD_NORM_RULE_DEF_FILES)
 	$(WORKDIR_SETUP)
 	cp -f $(BUILT_NORM_TAGS_MAIN) $@.workdir
 	mkdir -p $@.workdir/build
-	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -x $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $@ $(DOCKER_QUOTE)
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -x $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $(NORM_RULE_DOC2URL_ARGS) $@ $(DOCKER_QUOTE)
 	$(WORKDIR_TEARDOWN)
 
 $(BUILT_NORM_RULES_ADOC): $(BUILT_NORM_TAGS_MAIN) $(GOOD_NORM_RULE_DEF_FILES)
 	$(WORKDIR_SETUP)
 	cp -f $(BUILT_NORM_TAGS_MAIN) $@.workdir
 	mkdir -p $@.workdir/build
-	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -a $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $(NORM_RULE_DOC2HTML_ARGS) $@ $(DOCKER_QUOTE)
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -a $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $(NORM_RULE_DOC2URL_ARGS) $@ $(DOCKER_QUOTE)
 	$(WORKDIR_TEARDOWN)
 
 $(BUILT_NORM_RULES_HTML): $(BUILT_MAIN_TEST_HTML) $(GOOD_NORM_RULE_DEF_FILES)
 	$(WORKDIR_SETUP)
 	cp -f $(BUILT_NORM_TAGS_MAIN) $@.workdir
 	mkdir -p $@.workdir/build
-	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -h $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $(NORM_RULE_DOC2HTML_ARGS) $@ $(DOCKER_QUOTE)
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -h $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $(NORM_RULE_DOC2URL_ARGS) $@ $(DOCKER_QUOTE)
 	$(WORKDIR_TEARDOWN)
 
 # This is the HTML file that represents the standards doc. THe norm rule HTML links into this HTML.
@@ -250,7 +250,7 @@ $(BUILT_NORM_RULES_TAGS_NO_RULES): $(BUILT_NORM_TAGS_MAIN) $(BAD_NORM_RULE_DEF_F
 	$(WORKDIR_SETUP)
 	cp -f $(BUILT_NORM_TAGS_MAIN) $@.workdir
 	mkdir -p $@.workdir/build
-	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) $(NORM_TAG_FILE_ARGS) $(BAD_NORM_RULE_DEF_ARGS) $(BUILD_DIR)/bogus || touch $(BUILT_NORM_RULES_TAGS_NO_RULES) $(DOCKER_QUOTE)
+	$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) $(NORM_TAG_FILE_ARGS) $(BAD_NORM_RULE_DEF_ARGS) $(NORM_RULE_DOC2URL_ARGS) $(BUILD_DIR)/bogus || touch $(BUILT_NORM_RULES_TAGS_NO_RULES) $(DOCKER_QUOTE)
 	$(WORKDIR_TEARDOWN)
 
 # Update docker image to latest

normative-rules.md

@@ -38,7 +38,10 @@ AsciiDoc provides facilities to create invisible anchors associated with an enti
 
 AsciiDoc supports several styles of anchors:
 * _inline anchor_ such as:<br>
-    `We must [#goal]#free the world#.`
+    `We must [#goal]#free the world#.`<br>
+    OR<br>
+    `This text [#fix]+contains a # symbox+ so use plus to mark beginning & end of anchored text`
+
 * _paragraph anchor_ such as:
 
     > `[[foo]]`<br>
@@ -102,6 +105,7 @@ If you'd like to see detailed AsciiDoc examples of tagging cases, see https://gi
 2. Tagging part of a paragraph, table cells, unordered list items (AKA bullet list), or ordered list items (AKA numbered list)
 
     > Syntax:      `[#<anchor-name>]# ... #`<br>
+    > Alternate:   `[#<anchor-name>]+ ... +` if tagged text contains a # symbol.<br>
     >
     > Example:
     >> `Here is an example of [#norm:foo]#anchoring part# of a paragraph

schemas/norm-rules-schema.json

@@ -58,13 +58,20 @@
                 "tag_filename": {
                   "type": "string",
                   "description": "Tag file that maps tag names to tag text"
+                },
+                "stds_doc_url": {
+                  "type": "string",
+                  "description": "URL to standards doc associated with tag_filename"
                 }
               },
               "required": ["name"]
             }
           }
         },
         "required": ["name", "def_filename"],
+        "dependencies": {
+          "tag_filename": ["stds_doc_url"]
+        },
         "additionalProperties": false
       }
     }

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

@@ -2,60 +2,64 @@
 
 == my-chapter_name
 
-[cols="20%,20%,60%"]
+[cols="20%,60%,20%"]
 |===
-| Rule Name | Text Source | Normative Text
+| Rule Name | Rule Description | Description Location
 
 .4+| inline
-| Summary | A few words
-| Kind | extension
-[Zicsr, ABC]
-a| link:test.html#norm:inline[norm:inline] | inside inline
+| A few words | Rule Summary
+| extension | Rule Kind
+| [Zicsr, ABC] | Rule Instances
+| inside inline a| link:test.html#norm:inline[norm:inline]
 
 .1+| no_tag
-| Summary | Normative rule without tag/tags
+| Normative rule without tag/tags | Rule Summary
+
+.1+| inline-with-hash
+| includes a hash # symbol. a| link:test.html#norm:inline-with-hash[norm:inline-with-hash]
 
 .2+| paragraph-with-a-really-wide-rule-name
-| Description | Here's a description.
+| Here's a description.
 It's got 2 lines.
-a| link:test.html#norm:paragraph:no-inline-anchors[norm:paragraph:no-inline-anchors] | Paragraph without inline anchors
+ | Rule Description
+| Paragraph without inline anchors a| link:test.html#norm:paragraph:no-inline-anchors[norm:paragraph:no-inline-anchors]
 
 .1+| inline-anchors-in-paragraph-entire
-a| link:test.html#norm:paragraph:inline-anchors:entire[norm:paragraph:inline-anchors:entire] | Paragraph with inline anchor and something.
+| Paragraph with inline anchor and something. a| link:test.html#norm:paragraph:inline-anchors:entire[norm:paragraph:inline-anchors:entire]
 
 .1+| inline-anchors-in-paragraph-inline-anchor
-a| link:test.html#norm:paragraph:inline-anchors:inline-anchor[norm:paragraph:inline-anchors:inline-anchor] | inline anchor
+| inline anchor a| link:test.html#norm:paragraph:inline-anchors:inline-anchor[norm:paragraph:inline-anchors:inline-anchor]
 
 .1+| formulae
-a| link:test.html#norm:formulae[norm:formulae] | This paragraph looks like a formulae to Excel because it has this < sign in it. Make sure this gets written as a string, not a formulae in the XLSX or else it will create an error in Excel.
+| This paragraph looks like a formulae to Excel because it has this < sign in it. Make sure this gets written as a string, not a formulae in the XLSX or else it will create an error in Excel. a| link:test.html#norm:formulae[norm:formulae]
 
 .1+| rule_with_newlines
-a| link:test.html#norm:paragraph:tag_with_newlines[norm:paragraph:tag_with_newlines] | Here’s the first line. Here’s the second line.
+| Here’s the first line. Here’s the second line. a| link:test.html#norm:paragraph:tag_with_newlines[norm:paragraph:tag_with_newlines]
 
 .1+| double_tags
-a| link:test.html#norm:def[norm:def] | This paragraph has two tags but we only ever get a tag for norm:def.
+| This paragraph has two tags but we only ever get a tag for norm:def. a| link:test.html#norm:def[norm:def]
 
 .1+| table1
-a| link:test.html#norm:table:anchors-in-cells:entire-table[norm:table:anchors-in-cells:entire-table] | ===
+| ===
 WITH anchor
 WITHOUT anchor
-===
+=== a| link:test.html#norm:table:anchors-in-cells:entire-table[norm:table:anchors-in-cells:entire-table]
 
 .1+| table2
-a| link:test.html#norm:table:no-anchors-in-cells:entire-table[norm:table:no-anchors-in-cells:entire-table] | Header 1|Header 2
+| Header 1|Header 2
 ===
 Cell in column 1, row 1|Cell in column 2, row 1
 Cell in column 1, row 2|Cell in column 2, row 2
-===
+=== a| link:test.html#norm:table:no-anchors-in-cells:entire-table[norm:table:no-anchors-in-cells:entire-table]
 
 .1+| table3
-a| link:test.html#norm:table:anchors-in-cells:entire-table-tagged:cell[norm:table:anchors-in-cells:entire-table-tagged:cell] | WITH anchor
+| WITH anchor a| link:test.html#norm:table:anchors-in-cells:entire-table-tagged:cell[norm:table:anchors-in-cells:entire-table-tagged:cell]
 
 .1+| table4
-a| link:test.html#norm:table:anchors-in-cells:entire-table-not-tagged:cell[norm:table:anchors-in-cells:entire-table-not-tagged:cell] | ABC DEF
+| ABC DEF a| link:test.html#norm:table:anchors-in-cells:entire-table-not-tagged:cell[norm:table:anchors-in-cells:entire-table-not-tagged:cell]
 
 .1+| table5
-a| link:test.html#norm:table:many-rows[norm:table:many-rows] | Name|Color
+| Name|Color
 ===
 Roses|Red
 Violets|Blue
@@ -68,95 +72,95 @@ Name6|Color6
 Name7|Color8
 Name9|Color9
 Name10|Color10
-...
+... a| link:test.html#norm:table:many-rows[norm:table:many-rows]
 
 .1+| unordered1
-a| link:test.html#norm:unordered-list:no-anchors-in-items:entire-list[norm:unordered-list:no-anchors-in-items:entire-list] | Item A
+| Item A
 Item B
-Item C
+Item C a| link:test.html#norm:unordered-list:no-anchors-in-items:entire-list[norm:unordered-list:no-anchors-in-items:entire-list]
 
 .1+| unordered2
-a| link:test.html#norm:unordered-list:anchors-in-items:entire-list[norm:unordered-list:anchors-in-items:entire-list] | Item 1
+| Item 1
 Item 2
-Item 3
+Item 3 a| link:test.html#norm:unordered-list:anchors-in-items:entire-list[norm:unordered-list:anchors-in-items:entire-list]
 
 .1+| unordered3
-a| link:test.html#norm:unordered-list:anchors-in-items:item1[norm:unordered-list:anchors-in-items:item1] | Item 1
+| Item 1 a| link:test.html#norm:unordered-list:anchors-in-items:item1[norm:unordered-list:anchors-in-items:item1]
 
 .1+| unordered4
-a| link:test.html#norm:unordered-list:anchors-in-items:item2[norm:unordered-list:anchors-in-items:item2] | Item 2
+| Item 2 a| link:test.html#norm:unordered-list:anchors-in-items:item2[norm:unordered-list:anchors-in-items:item2]
 
 .1+| unordered5
-a| link:test.html#norm:unordered-list:multiple-levels[norm:unordered-list:multiple-levels] | Zca and not F
+| Zca and not F
 Zca, Zcf and F (but not D) is specified (RV32 only)
 Zca, Zcf and Zcd if D is specified (RV32 only)
 
 this configuration excludes Zcmp, Zcmt
 Zca, Zcd if D is specified (RV64 only)
 
-this configuration excludes Zcmp, Zcmt
+this configuration excludes Zcmp, Zcmt a| link:test.html#norm:unordered-list:multiple-levels[norm:unordered-list:multiple-levels]
 
 .1+| ordered1
-a| link:test.html#norm:ordered-list:no-anchors-in-items:entire-list[norm:ordered-list:no-anchors-in-items:entire-list] | Item A
+| Item A
 Item B
-Item C
+Item C a| link:test.html#norm:ordered-list:no-anchors-in-items:entire-list[norm:ordered-list:no-anchors-in-items:entire-list]
 
 .1+| ordered2
-a| link:test.html#norm:ordered-list:anchors-in-items:entire-list[norm:ordered-list:anchors-in-items:entire-list] | Item 1
+| Item 1
 Item 2
-Item 3
+Item 3 a| link:test.html#norm:ordered-list:anchors-in-items:entire-list[norm:ordered-list:anchors-in-items:entire-list]
 
 .1+| ordered3
-a| link:test.html#norm:ordered-list:anchors-in-items:item1[norm:ordered-list:anchors-in-items:item1] | Item 1
+| Item 1 a| link:test.html#norm:ordered-list:anchors-in-items:item1[norm:ordered-list:anchors-in-items:item1]
 
 .1+| ordered4
-a| link:test.html#norm:ordered-list:anchors-in-items:item2[norm:ordered-list:anchors-in-items:item2] | Item 2
+| Item 2 a| link:test.html#norm:ordered-list:anchors-in-items:item2[norm:ordered-list:anchors-in-items:item2]
 
 .1+| desc1
-a| link:test.html#norm:description-list:no-anchors-in-items:entire-list[norm:description-list:no-anchors-in-items:entire-list] | Description-A
+| Description-A
 Item A
 Description-B
 Item B
 Description-C
-Item C
+Item C a| link:test.html#norm:description-list:no-anchors-in-items:entire-list[norm:description-list:no-anchors-in-items:entire-list]
 
 .1+| desc2
-a| link:test.html#norm:description-list:anchors-in-items:entire-list[norm:description-list:anchors-in-items:entire-list] | Description-1
+| Description-1 a| link:test.html#norm:description-list:anchors-in-items:entire-list[norm:description-list:anchors-in-items:entire-list]
 
 .2+| desc3
-a| link:test.html#norm:description-list:anchors-in-items:item1[norm:description-list:anchors-in-items:item1] | Item 1
-a| link:test.html#norm:description-list:anchors-in-items:item3[norm:description-list:anchors-in-items:item3] | Item 3
+| Item 1 a| link:test.html#norm:description-list:anchors-in-items:item1[norm:description-list:anchors-in-items:item1]
+| Item 3 a| link:test.html#norm:description-list:anchors-in-items:item3[norm:description-list:anchors-in-items:item3]
 
 .2+| desc4
-a| link:test.html#norm:description-list:anchors-in-items:item1[norm:description-list:anchors-in-items:item1] | Item 1
-a| link:test.html#norm:description-list:anchors-in-items:item3[norm:description-list:anchors-in-items:item3] | Item 3
+| Item 1 a| link:test.html#norm:description-list:anchors-in-items:item1[norm:description-list:anchors-in-items:item1]
+| Item 3 a| link:test.html#norm:description-list:anchors-in-items:item3[norm:description-list:anchors-in-items:item3]
 
 .1+| admon1
-a| link:test.html#norm:admonition:single-paragraph-note[norm:admonition:single-paragraph-note] | Single paragraph note
-that spans lines.
+| Single paragraph note
+that spans lines. a| link:test.html#norm:admonition:single-paragraph-note[norm:admonition:single-paragraph-note]
 
 .1+| admon2
-a| link:test.html#norm:admonition:no-anchors-in-notes:entire-note[norm:admonition:no-anchors-in-notes:entire-note] | Paragraph A
+| Paragraph A
 
 Paragraph B
 
-Paragraph C
+Paragraph C a| link:test.html#norm:admonition:no-anchors-in-notes:entire-note[norm:admonition:no-anchors-in-notes:entire-note]
 
 .1+| admon3
-a| link:test.html#norm:admonition:anchors-in-notes:entire-note[norm:admonition:anchors-in-notes:entire-note] | Paragraph 1
+| Paragraph 1
 
 Paragraph 2
 
-Paragraph 3
+Paragraph 3 a| link:test.html#norm:admonition:anchors-in-notes:entire-note[norm:admonition:anchors-in-notes:entire-note]
 
 .2+| admon4
-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
+| Paragraph X a| link:test.html#norm:admonition:only-anchors-in-notes:note1[norm:admonition:only-anchors-in-notes:note1]
+| Paragraph Z a| link:test.html#norm:admonition:only-anchors-in-notes:note3[norm:admonition:only-anchors-in-notes:note3]
 
 .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
+| One line description | Rule Description
+| parameter | Rule Kind
+| [MY_PARAMETER] | Rule Instances
+| Paragraph 1 a| link:test.html#norm:admonition:anchors-in-notes:note1[norm:admonition:anchors-in-notes:note1]
+| Paragraph 3 a| link:test.html#norm:admonition:anchors-in-notes:note3[norm:admonition:anchors-in-notes:note3]
 |===