Skip to content

Commit 3e01674

Browse files
author
james-ball-qualcomm
authored
Merge pull request #115 from riscv/114-improve-adoc-format-of-norm-rules
Actually just decided it was easier to output native HTML instead of adoc to HTML.
2 parents 93422ee + d099e94 commit 3e01674

File tree

11 files changed

+1035
-78
lines changed

11 files changed

+1035
-78
lines changed

‎Makefile‎

Lines changed: 27 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -63,15 +63,18 @@ EXPECTED_NORM_TAGS := $(NORM_RULE_EXPECTED_DIR)/$(MAIN_NORM_TAGS_OUTPUT_FNAME)
6363
EXPECTED_NORM_RULES_JSON := $(NORM_RULE_EXPECTED_DIR)/$(NORM_RULE_JSON_OUTPUT_FNAME)
6464
EXPECTED_NORM_RULES_XLSX := $(NORM_RULE_EXPECTED_DIR)/$(NORM_RULE_XLSX_OUTPUT_FNAME)
6565
EXPECTED_NORM_RULES_ADOC := $(NORM_RULE_EXPECTED_DIR)/$(NORM_RULE_ADOC_OUTPUT_FNAME)
66+
EXPECTED_NORM_RULES_HTML := $(NORM_RULE_EXPECTED_DIR)/$(NORM_RULE_HTML_OUTPUT_FNAME)
6667

67-
# All normative rule definition input YAML files
68-
NORM_RULE_DEF_FILES := $(wildcard $(NORM_RULE_DEF_DIR)/*.yaml)
68+
# Normative rule definition input YAML files.
69+
GOOD_NORM_RULE_DEF_FILES := $(NORM_RULE_DEF_DIR)/test.yaml
70+
BAD_NORM_RULE_DEF_FILES := $(NORM_RULE_DEF_DIR)/missing_tag_refs.yaml
6971

7072
# Add -t to each normative tag input filename and add prefix of "/" to make into absolute pathname.
7173
NORM_TAG_FILE_ARGS := $(foreach relative_pname,$(BUILT_NORM_TAGS_MAIN),-t /$(relative_pname))
7274

7375
# Add -d to each normative rule definition filename
74-
NORM_RULE_DEF_ARGS := $(foreach relative_pname,$(NORM_RULE_DEF_FILES),-d $(relative_pname))
76+
GOOD_NORM_RULE_DEF_ARGS := $(foreach relative_pname,$(GOOD_NORM_RULE_DEF_FILES),-d $(relative_pname))
77+
BAD_NORM_RULE_DEF_ARGS := $(foreach relative_pname,$(BAD_NORM_RULE_DEF_FILES),-d $(relative_pname))
7578

7679
# Provide mapping from an standard's norm tags JSON file to its corresponding HTML file. Used to create links into standard's HTML files.
7780
NORM_RULE_DOC2HTML_ARGS := $(foreach doc_name,$(DOCS),-tag2html /$(BUILD_DIR)/$(doc_name)$(DOC_NORM_TAG_SUFFIX) $(doc_name).html)
@@ -152,7 +155,7 @@ build-test-tags-without-rules: $(BUILT_NORM_RULES_TAGS_NO_RULES)
152155

153156
# Compare tests against expected
154157
.PHONY: compare-tests
155-
compare-tests: compare-test-tags compare-test-norm-rules-json compare-test-norm-rules-adoc
158+
compare-tests: compare-test-tags compare-test-norm-rules-json compare-test-norm-rules-adoc compare-test-norm-rules-html
156159

157160
compare-test-tags: $(EXPECTED_NORM_TAGS) $(BUILT_NORM_TAGS_MAIN)
158161
@echo "CHECKING BUILT TAGS AGAINST EXPECTED TAGS"
@@ -168,9 +171,13 @@ compare-test-norm-rules-adoc: $(EXPECTED_NORM_RULES_ADOC) $(BUILT_NORM_RULES_ADO
168171
@echo "CHECKING ADOC BUILT NORM RULES AGAINST EXPECTED NORM RULES"
169172
diff $(EXPECTED_NORM_RULES_ADOC) $(BUILT_NORM_RULES_ADOC) && echo "diff PASSED" || (echo "diff FAILED"; exit 1)
170173

174+
compare-test-norm-rules-html: $(EXPECTED_NORM_RULES_HTML) $(BUILT_NORM_RULES_HTML)
175+
@echo "CHECKING HTML BUILT NORM RULES AGAINST EXPECTED NORM RULES"
176+
diff $(EXPECTED_NORM_RULES_HTML) $(BUILT_NORM_RULES_HTML) && echo "diff PASSED" || (echo "diff FAILED"; exit 1)
177+
171178
# Update expected files from built files
172179
.PHONY: update-expected
173-
update-expected: update-test-tags update-test-norm-rules-json update-test-norm-rules-xlsx update-test-norm-rules-adoc
180+
update-expected: update-test-tags update-test-norm-rules-json update-test-norm-rules-xlsx update-test-norm-rules-adoc update-test-norm-rules-html
174181

175182
update-test-tags: $(BUILT_NORM_TAGS_MAIN)
176183
cp -f $(BUILT_NORM_TAGS_MAIN) $(EXPECTED_NORM_TAGS)
@@ -184,6 +191,9 @@ update-test-norm-rules-xlsx: $(BUILT_NORM_RULES_XLSX)
184191
update-test-norm-rules-adoc: $(BUILT_NORM_RULES_ADOC)
185192
cp -f $(BUILT_NORM_RULES_ADOC) $(EXPECTED_NORM_RULES_ADOC)
186193

194+
update-test-norm-rules-html: $(BUILT_NORM_RULES_HTML)
195+
cp -f $(BUILT_NORM_RULES_HTML) $(EXPECTED_NORM_RULES_HTML)
196+
187197
# Build normative tags with main adoc input
188198
$(BUILT_NORM_TAGS_MAIN): $(NORM_RULE_TESTS_DIR)/$(MAIN_TEST_ADOC_INPUT_FNAME) $(CONVERTERS_DIR)/$(TAGS_BACKEND)
189199
$(WORKDIR_SETUP)
@@ -198,33 +208,33 @@ $(BUILT_NORM_TAGS_DUPLICATE): $(TAGS_TESTS_DIR)/$(DUPLICATE_TEST_ADOC_INPUT_FNAM
198208
$(WORKDIR_TEARDOWN)
199209

200210
# Build normative rules with JSON output format
201-
$(BUILT_NORM_RULES_JSON): $(BUILT_NORM_TAGS_MAIN) $(NORM_RULE_DEF_FILES)
211+
$(BUILT_NORM_RULES_JSON): $(BUILT_NORM_TAGS_MAIN) $(GOOD_NORM_RULE_DEF_FILES)
202212
$(WORKDIR_SETUP)
203213
cp -f $(BUILT_NORM_TAGS_MAIN) $@.workdir
204214
mkdir -p $@.workdir/build
205-
$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -w -j $(NORM_TAG_FILE_ARGS) $(NORM_RULE_DEF_ARGS) $@ $(DOCKER_QUOTE)
215+
$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -j $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $@ $(DOCKER_QUOTE)
206216
$(WORKDIR_TEARDOWN)
207217

208218
# Build normative rules with XLSX output format
209-
$(BUILT_NORM_RULES_XLSX): $(BUILT_NORM_TAGS_MAIN) $(NORM_RULE_DEF_FILES)
219+
$(BUILT_NORM_RULES_XLSX): $(BUILT_NORM_TAGS_MAIN) $(GOOD_NORM_RULE_DEF_FILES)
210220
$(WORKDIR_SETUP)
211221
cp -f $(BUILT_NORM_TAGS_MAIN) $@.workdir
212222
mkdir -p $@.workdir/build
213-
$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -w -x $(NORM_TAG_FILE_ARGS) $(NORM_RULE_DEF_ARGS) $@ $(DOCKER_QUOTE)
223+
$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -x $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $@ $(DOCKER_QUOTE)
214224
$(WORKDIR_TEARDOWN)
215225

216-
$(BUILT_NORM_RULES_ADOC): $(BUILT_NORM_TAGS_MAIN) $(NORM_RULE_DEF_FILES)
226+
$(BUILT_NORM_RULES_ADOC): $(BUILT_NORM_TAGS_MAIN) $(GOOD_NORM_RULE_DEF_FILES)
217227
$(WORKDIR_SETUP)
218228
cp -f $(BUILT_NORM_TAGS_MAIN) $@.workdir
219229
mkdir -p $@.workdir/build
220-
$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -w -a $(NORM_TAG_FILE_ARGS) $(NORM_RULE_DEF_ARGS) $(NORM_RULE_DOC2HTML_ARGS) $@ $(DOCKER_QUOTE)
230+
$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -a $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $(NORM_RULE_DOC2HTML_ARGS) $@ $(DOCKER_QUOTE)
221231
$(WORKDIR_TEARDOWN)
222232

223-
$(BUILT_NORM_RULES_HTML): $(BUILT_NORM_RULES_ADOC) $(BUILT_MAIN_TEST_HTML)
233+
$(BUILT_NORM_RULES_HTML): $(BUILT_MAIN_TEST_HTML) $(GOOD_NORM_RULE_DEF_FILES)
224234
$(WORKDIR_SETUP)
235+
cp -f $(BUILT_NORM_TAGS_MAIN) $@.workdir
225236
mkdir -p $@.workdir/build
226-
cp -f $(BUILT_NORM_RULES_ADOC) $@.workdir/build
227-
$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) $< $(DOCKER_QUOTE)
237+
$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) -h $(NORM_TAG_FILE_ARGS) $(GOOD_NORM_RULE_DEF_ARGS) $(NORM_RULE_DOC2HTML_ARGS) $@ $(DOCKER_QUOTE)
228238
$(WORKDIR_TEARDOWN)
229239

230240
# This is the HTML file that represents the standards doc. THe norm rule HTML links into this HTML.
@@ -234,13 +244,13 @@ $(BUILT_MAIN_TEST_HTML) : $(NORM_RULE_TESTS_DIR)/$(MAIN_TEST_ADOC_INPUT_FNAME)
234244
$(DOCKER_CMD) $(DOCKER_QUOTE) $(ASCIIDOCTOR_HTML) -o $@ $< $(DOCKER_QUOTE)
235245
$(WORKDIR_TEARDOWN)
236246

237-
# Build normative rules that should create an error due to tags without norm rules referencing them
247+
# Build normative rules with different YAML that should create an error due to tags without norm rules referencing them.
238248
# Should exit with a non-zero status and then we just "touch" the output file so it exists and make is happy.
239-
$(BUILT_NORM_RULES_TAGS_NO_RULES): $(BUILT_NORM_TAGS_MAIN) $(NORM_RULE_DEF_FILES)
249+
$(BUILT_NORM_RULES_TAGS_NO_RULES): $(BUILT_NORM_TAGS_MAIN) $(BAD_NORM_RULE_DEF_FILES)
240250
$(WORKDIR_SETUP)
241251
cp -f $(BUILT_NORM_TAGS_MAIN) $@.workdir
242252
mkdir -p $@.workdir/build
243-
$(DOCKER_CMD) $(DOCKER_QUOTE) $(CREATE_NORM_RULE_RUBY) $(NORM_TAG_FILE_ARGS) $(NORM_RULE_DEF_ARGS) $(BUILD_DIR)/bogus || touch $(BUILT_NORM_RULES_TAGS_NO_RULES) $(DOCKER_QUOTE)
253+
$(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)
244254
$(WORKDIR_TEARDOWN)
245255

246256
# Update docker image to latest

‎converters/tags.rb‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -157,7 +157,7 @@ def node_text_content(node)
157157
content_or_nil.nil? ? "" : content_or_nil
158158
end
159159

160-
# Convert spaces to newlines.
160+
# Convert newlines to spaces.
161161
def normalize_space text
162162
text.tr("\n", " ")
163163
end

‎normative-rules.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -44,7 +44,10 @@ AsciiDoc supports several styles of anchors:
4444
> `[[foo]]`<br>
4545
> `This is an anchor for the entire paragraph.`
4646
>
47-
> `This isn't part of the anchor since it is the next paragraph.`
47+
> `This isn't part of the above anchor since it is the next paragraph.`
48+
>
49+
> `[#bar]`<br>
50+
> `This is an alternative paragraph anchor syntax equivalent to [[]]`
4851
4952
* You must use the _inline anchor_ for table cells, unordered/ordered list items, description list items.
5053

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

Lines changed: 100 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -2,58 +2,131 @@
22

33
== my-chapter_name
44

5-
[cols="20%,80%"]
5+
[cols="20%,20%,60%"]
66
|===
7-
| Rule Name | Rule Information
7+
| Rule Name | Link to Standard | Text from Standard
88

99
.2+| inline
10-
a| Summary: A few words
11-
a| link:test.html#norm:inline[norm:inline] => inside inline
10+
| Summary | A few words
11+
a| link:test.html#norm:inline[norm:inline] | inside inline
1212

1313
.2+| paragraph-with-a-really-wide-rule-name
14-
a| Description: Here's a description.
14+
| Description | Here's a description.
1515
It's got 2 lines.
16-
a| link:test.html#norm:paragraph:no-inline-anchors[norm:paragraph:no-inline-anchors] => Paragraph without inline anchors
16+
a| link:test.html#norm:paragraph:no-inline-anchors[norm:paragraph:no-inline-anchors] | Paragraph without inline anchors
1717

1818
.1+| inline-anchors-in-paragraph-entire
19-
a| link:test.html#norm:paragraph:inline-anchors:entire[norm:paragraph:inline-anchors:entire] => Paragraph with inline anchor and something.
19+
a| link:test.html#norm:paragraph:inline-anchors:entire[norm:paragraph:inline-anchors:entire] | Paragraph with inline anchor and something.
2020

2121
.1+| inline-anchors-in-paragraph-inline-anchor
22-
a| link:test.html#norm:paragraph:inline-anchors:inline-anchor[norm:paragraph:inline-anchors:inline-anchor] => inline anchor
22+
a| link:test.html#norm:paragraph:inline-anchors:inline-anchor[norm:paragraph:inline-anchors:inline-anchor] | inline anchor
2323

2424
.1+| formulae
25-
a| link:test.html#norm:formulae[norm:formulae] => This paragraph looks like a formulae to Excel because it has this &lt; 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.
25+
a| link:test.html#norm:formulae[norm:formulae] | This paragraph looks like a formulae to Excel because it has this &lt; 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.
2626

2727
.1+| rule_with_newlines
28-
a| link:test.html#norm:paragraph:tag_with_newlines[norm:paragraph:tag_with_newlines] => Here&#8217;s the first line. Here&#8217;s the second line.
28+
a| link:test.html#norm:paragraph:tag_with_newlines[norm:paragraph:tag_with_newlines] | Here&#8217;s the first line. Here&#8217;s the second line.
29+
30+
.1+| double_tags
31+
a| link:test.html#norm:def[norm:def] | This paragraph has two tags but we only ever get a tag for norm:def.
2932

3033
.1+| table1
31-
a| link:test.html#norm:table:anchors-in-cells:entire-table[norm:table:anchors-in-cells:entire-table] => ENTIRE TABLE
34+
a| link:test.html#norm:table:anchors-in-cells:entire-table[norm:table:anchors-in-cells:entire-table] | ENTIRE TABLE
3235

3336
.1+| table2
34-
a| link:test.html#norm:table:no-anchors-in-cells:entire-table[norm:table:no-anchors-in-cells:entire-table] => ENTIRE TABLE
37+
a| link:test.html#norm:table:no-anchors-in-cells:entire-table[norm:table:no-anchors-in-cells:entire-table] | ENTIRE TABLE
3538

36-
.1+| anchors-in-cells1
37-
a| link:test.html#norm:table:anchors-in-cells:entire-table-tagged:cell[norm:table:anchors-in-cells:entire-table-tagged:cell] => WITH anchor
39+
.1+| table3
40+
a| link:test.html#norm:table:anchors-in-cells:entire-table-tagged:cell[norm:table:anchors-in-cells:entire-table-tagged:cell] | WITH anchor
3841

39-
.1+| anchors-in-cells2
40-
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
42+
.1+| table4
43+
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
4144

4245
.1+| unordered1
43-
a| link:test.html#norm:unordered-list:anchors-in-items:entire-list[norm:unordered-list:anchors-in-items:entire-list] => Item 1
46+
a| link:test.html#norm:unordered-list:no-anchors-in-items:entire-list[norm:unordered-list:no-anchors-in-items:entire-list] | Item A
47+
Item B
48+
Item C
49+
50+
.1+| unordered2
51+
a| link:test.html#norm:unordered-list:anchors-in-items:entire-list[norm:unordered-list:anchors-in-items:entire-list] | Item 1
52+
Item 2
53+
Item 3
54+
55+
.1+| unordered3
56+
a| link:test.html#norm:unordered-list:anchors-in-items:item1[norm:unordered-list:anchors-in-items:item1] | Item 1
57+
58+
.1+| unordered4
59+
a| link:test.html#norm:unordered-list:anchors-in-items:item2[norm:unordered-list:anchors-in-items:item2] | Item 2
60+
61+
.1+| unordered5
62+
a| link:test.html#norm:unordered-list:multiple-levels[norm:unordered-list:multiple-levels] | Zca and not F
63+
Zca, Zcf and F (but not D) is specified (RV32 only)
64+
Zca, Zcf and Zcd if D is specified (RV32 only)
65+
66+
this configuration excludes Zcmp, Zcmt
67+
Zca, Zcd if D is specified (RV64 only)
68+
69+
this configuration excludes Zcmp, Zcmt
70+
71+
.1+| ordered1
72+
a| link:test.html#norm:ordered-list:no-anchors-in-items:entire-list[norm:ordered-list:no-anchors-in-items:entire-list] | Item A
73+
Item B
74+
Item C
75+
76+
.1+| ordered2
77+
a| link:test.html#norm:ordered-list:anchors-in-items:entire-list[norm:ordered-list:anchors-in-items:entire-list] | Item 1
4478
Item 2
4579
Item 3
4680

47-
.3+| note_with_2_tags
48-
a| Description: One line description
49-
a| link:test.html#norm:admonition:anchors-in-notes:note1[norm:admonition:anchors-in-notes:note1] => Paragraph 1
50-
a| link:test.html#norm:admonition:anchors-in-notes:note3[norm:admonition:anchors-in-notes:note3] => Paragraph 3
81+
.1+| ordered3
82+
a| link:test.html#norm:ordered-list:anchors-in-items:item1[norm:ordered-list:anchors-in-items:item1] | Item 1
83+
84+
.1+| ordered4
85+
a| link:test.html#norm:ordered-list:anchors-in-items:item2[norm:ordered-list:anchors-in-items:item2] | Item 2
86+
87+
.1+| desc1
88+
a| link:test.html#norm:description-list:no-anchors-in-items:entire-list[norm:description-list:no-anchors-in-items:entire-list] | Description-A
89+
Item A
90+
Description-B
91+
Item B
92+
Description-C
93+
Item C
94+
95+
.1+| desc2
96+
a| link:test.html#norm:description-list:anchors-in-items:entire-list[norm:description-list:anchors-in-items:entire-list] | Description-1
97+
98+
.2+| desc3
99+
a| link:test.html#norm:description-list:anchors-in-items:item1[norm:description-list:anchors-in-items:item1] | Item 1
100+
a| link:test.html#norm:description-list:anchors-in-items:item3[norm:description-list:anchors-in-items:item3] | Item 3
101+
102+
.2+| desc4
103+
a| link:test.html#norm:description-list:anchors-in-items:item1[norm:description-list:anchors-in-items:item1] | Item 1
104+
a| link:test.html#norm:description-list:anchors-in-items:item3[norm:description-list:anchors-in-items:item3] | Item 3
105+
106+
.1+| admon1
107+
a| link:test.html#norm:admonition:single-paragraph-note[norm:admonition:single-paragraph-note] | Single paragraph note
108+
that spans lines.
109+
110+
.1+| admon2
111+
a| link:test.html#norm:admonition:no-anchors-in-notes:entire-note[norm:admonition:no-anchors-in-notes:entire-note] | Paragraph A
112+
113+
Paragraph B
114+
115+
Paragraph C
116+
117+
.1+| admon3
118+
a| link:test.html#norm:admonition:anchors-in-notes:entire-note[norm:admonition:anchors-in-notes:entire-note] | Paragraph 1
119+
120+
Paragraph 2
121+
122+
Paragraph 3
51123

52-
.2+| desc1
53-
a| link:test.html#norm:description-list:anchors-in-items:item1[norm:description-list:anchors-in-items:item1] => Item 1
54-
a| link:test.html#norm:description-list:anchors-in-items:item3[norm:description-list:anchors-in-items:item3] => Item 3
124+
.2+| admon4
125+
a| link:test.html#norm:admonition:only-anchors-in-notes:note1[norm:admonition:only-anchors-in-notes:note1] | Paragraph X
126+
a| link:test.html#norm:admonition:only-anchors-in-notes:note3[norm:admonition:only-anchors-in-notes:note3] | Paragraph Z
55127

56-
.2+| desc2
57-
a| link:test.html#norm:description-list:anchors-in-items:item1[norm:description-list:anchors-in-items:item1] => Item 1
58-
a| link:test.html#norm:description-list:anchors-in-items:item3[norm:description-list:anchors-in-items:item3] => Item 3
128+
.3+| admon5
129+
| Description | One line description
130+
a| link:test.html#norm:admonition:anchors-in-notes:note1[norm:admonition:anchors-in-notes:note1] | Paragraph 1
131+
a| link:test.html#norm:admonition:anchors-in-notes:note3[norm:admonition:anchors-in-notes:note3] | Paragraph 3
59132
|===

0 commit comments

Comments
 (0)