Skip to content

Commit 1fb9a74

Browse files
author
james-ball-qualcomm
authored
Merge pull request #68 from riscv/67-rename-creation-to-definition-and-add-isa-object-names
Improvements to Ruby script to create normative rules and addition of JSON schema files
2 parents d7974ea + 6bb4a5a commit 1fb9a74

File tree

5 files changed

+513
-151
lines changed

5 files changed

+513
-151
lines changed

‎normative-rules.md‎

Lines changed: 37 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -46,9 +46,28 @@ AsciiDoc supports several styles of anchors:
4646
>
4747
> `This isn't part of the anchor since it is the next paragraph.`
4848
49-
* You can also use the _paragraph anchor_ for table cells and list items if placed before the text such as:
50-
51-
> `| [[foo]] Here is the table cell contents | next cell`
49+
* You must use the _paragraph anchor_ for table cells, list items, or description list terms
50+
* For table cells and list items, put the anchor before its associated text as follows:
51+
* Table cell<br>
52+
> `| [[foo]] Here are the table cell contents | next cell`
53+
* List item<br>
54+
> `* [[foo]] Here is the list item`
55+
* For description list terms (e.g., `Apples`, `Oranges`), put the anchor immediately after the term on its own line as follows:
56+
> `Apples::`<br>
57+
> `[[apple-colors]]`<br>
58+
> `Typically be red, yellow, or green.`<br>
59+
> <br>
60+
> `Oranges:: Generally orange in color`<br>
61+
> <br>
62+
> `Bananas::`<br>
63+
> `[[banana-color]]`<br>
64+
> `Generally yellow in color`
65+
* These won't work
66+
> * `Bananas:: [[banana-color]] Generally yellow in color`<br>
67+
> * `[[banana-color]] Bananas:: Generally yellow in color`
68+
> * `[[banana-color]]`<br>
69+
> `Bananas::`<br>
70+
> `Generally yellow in color`
5271
5372
Naming restrictions:
5473
* Start anchor names with a letter and use `:` to separate fields in the anchor name. No spaces allowed in name.
@@ -67,27 +86,32 @@ If you'd like to get more detailed AsciiDoc information on anchors, please read:
6786
> Syntax: `[#<anchor-name>]# ... #`<br>
6887
> Example: `Here is an example of [#foo]#anchoring part# of a paragraph
6988
> and can have [#bar]#multiple anchors# if needed.`<br>
70-
> Tagged text: `anchoring part` and `multiple anchors`
71-
72-
2. Limitations:
73-
* Can't anchor text across multiple paragraphs.
74-
* Must have text next to the 2nd hash symbol (i.e., can't have newline after `[#<anchor-name]#`).
75-
* Can't put inside admonitions such as [NOTE] (see #5 below for solution).
76-
* Can't have `.` in anchor-name (replace with `-`)
89+
> Tagged text: `anchoring part` and `multiple anchors`<br>
90+
>
91+
> Limitations:
92+
> * Can't anchor text across multiple paragraphs.
93+
> * Can't use in table cells, list items, or description list items (see #3 below for work-around).
94+
> * Must have text next to the 2nd hash symbol (i.e., can't have newline after `[#<anchor-name]#`).
95+
> * Can't put inside admonitions such as [NOTE] (see #5 below for solution).
96+
> * Can't have `.` in anchor-name (replace with `-`)
7797
78-
3. Anchor to entire paragraph
98+
2. Anchor to entire paragraph
7999

80100
> Syntax: `[[<anchor-name]]`<br>
81101
> Example: `[[zort]]`<br>
82102
> `Here is an example of anchoring a whole paragraph.`<br>
83103
> Tagged text: Entire paragraph<br>
84104
85-
4. Anchor to entire table cell or a list entry
105+
3. Anchor to entire table cell, list entry, or description list entry
86106

87107
> Example: `| Alan Turing | [[Alan_Turing_Birthday]] June 23, 1912 | London`<br>
88108
> Tagged text: None (just creates hyperlink to anchor in table/list so not so useful)
109+
>
110+
> Limitations:
111+
> * Anchor must be to entire contents of cell/item.
112+
> * Only one anchor per cell/item.
89113
90-
5. Anchor inside admonition (e.g. `[NOTE]`):
114+
4. Anchor inside admonition (e.g. `[NOTE]`):
91115
* Must use `[[<anchor-name]]` before each paragraph (with unique anchor names of course) being tagged
92116
* Can't use `[#<anchor-name]#Here's some note text.#` since it just shows up in HTML as normal text
93117
* Don't put `[[<<anchor-name]]` before the entire admonition (e.g., before `[NOTE]`) to apply to entire admonition

‎schemas/common-schema.json‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
4+
"title": "Common content used by multiple schemas (reduces copy & paste)",
5+
6+
"summaryDesc": {
7+
"description": "Short summary of the normative rule (just a few words)"
8+
},
9+
"descriptionDesc": {
10+
"description": "Comprehensive description of the normative rule (sentence, paragraph, or longer)"
11+
},
12+
"kindRuleDesc": {
13+
"description": "The kind of ISA object associated with this normative rule"
14+
},
15+
"instancesRuleDesc": {
16+
"description": "The names of ISA object instances of the specified kind associated with this normative rule"
17+
},
18+
"stringArray": {
19+
"type": "array",
20+
"items": { "type": "string" }
21+
},
22+
"ruleNamePattern" : {
23+
"pattern": "^[a-zA-z][a-zA-z0-9_-]+$"
24+
},
25+
"tagNamePattern" : {
26+
"pattern": "^[a-zA-z][:a-zA-z0-9_-]+$"
27+
},
28+
"isaObjectKind": {
29+
"type": "string",
30+
"enum": ["extension", "instruction", "csr", "csr_field"]
31+
},
32+
"ruleName": {
33+
"type": "string",
34+
"$ref": "#/ruleNamePattern"
35+
},
36+
"ruleNameArray": {
37+
"type": "array",
38+
"items": {
39+
"type": "string",
40+
"$ref": "#/ruleNamePattern"
41+
}
42+
},
43+
"tagName": {
44+
"type": "string",
45+
"$ref": "#/tagNamePattern"
46+
},
47+
"tagObject": {
48+
"type": "object",
49+
"properties": {
50+
"name": { "$ref": "#/tagName" },
51+
"kind": {
52+
"$ref": "#/isaObjectKind",
53+
"description": "The kind of ISA object associated with this tag"
54+
},
55+
"instances": {
56+
"$ref": "#/stringArray",
57+
"description": "The names of ISA object instances of the specified kind associated with this tag"
58+
}
59+
},
60+
"required": ["name"],
61+
"additionalProperties": false
62+
},
63+
"tagArray": {
64+
"type": "array",
65+
"items": {
66+
"anyOf": [
67+
{ "$ref": "#/tagName" },
68+
{ "$ref": "#/tagObject" }
69+
]
70+
}
71+
}
72+
}

‎schemas/defs-schema.json‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,62 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"title": "Schema for normative rule definitions input files",
4+
"type": "object",
5+
6+
"properties": {
7+
"normative_rule_definitions": {
8+
"type": "array",
9+
"items": {
10+
"type": "object",
11+
"properties": {
12+
"name": {
13+
"$ref": "common-schema.json#/ruleName",
14+
"description": "Single normative rule name"
15+
},
16+
"names": {
17+
"$ref": "common-schema.json#/ruleNameArray",
18+
"description": "Multiple normative rule names"
19+
},
20+
"summary": {
21+
"type": "string",
22+
"$ref": "common-schema.json#/summaryDesc"
23+
},
24+
"description": {
25+
"type": "string",
26+
"$ref": "common-schema.json#/descriptionDesc"
27+
},
28+
"kind": {
29+
"allOf": [
30+
{ "$ref": "common-schema.json#/isaObjectKind" },
31+
{ "$ref": "common-schema.json#/kindRuleDesc" }
32+
]
33+
},
34+
"instances": {
35+
"allOf": [
36+
{ "$ref": "common-schema.json#/stringArray" },
37+
{ "$ref": "common-schema.json#/instancesRuleDesc" }
38+
]
39+
},
40+
"tags": {
41+
"$ref": "common-schema.json#/tagArray",
42+
"description": "List of normative rule tags that have normative text from adoc files"
43+
},
44+
"tags_without_text": {
45+
"$ref": "common-schema.json#/tagArray",
46+
"description": "List of normative rule tags that don't have normative text (just an anchor) from adoc files"
47+
}
48+
},
49+
"oneOf": [
50+
{ "required": ["name"] },
51+
{ "required": ["names"] }
52+
],
53+
"anyOf": [
54+
{ "required": ["tags"] },
55+
{ "required": ["tags_without_text"] }
56+
],
57+
"additionalProperties": false
58+
}
59+
}
60+
},
61+
"required": ["normative_rule_definitions"]
62+
}

‎schemas/norm-rules-schema.json‎

Lines changed: 70 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,70 @@
1+
{
2+
"$schema": "http://json-schema.org/draft-07/schema#",
3+
"title": "Schema for norm-rules.json in build directory. Created by build-norm-rules Makefile target.",
4+
"type": "object",
5+
6+
"properties": {
7+
"normative_rules": {
8+
"type": "array",
9+
"items": {
10+
"type": "object",
11+
"properties": {
12+
"name": {
13+
"$ref": "common-schema.json#/ruleName",
14+
"description": "Normative rule name"
15+
},
16+
"def_filename": {
17+
"type": "string",
18+
"description": "Normative rule definition file that defines this rule"
19+
},
20+
"summary": {
21+
"type": "string",
22+
"$ref": "common-schema.json#/summaryDesc"
23+
},
24+
"description": {
25+
"type": "string",
26+
"$ref": "common-schema.json#/descriptionDesc"
27+
},
28+
"kind": {
29+
"allOf": [
30+
{ "$ref": "common-schema.json#/isaObjectKind" },
31+
{ "$ref": "common-schema.json#/kindRuleDesc" }
32+
]
33+
},
34+
"instances": {
35+
"allOf": [
36+
{ "$ref": "common-schema.json#/stringArray" },
37+
{ "$ref": "common-schema.json#/instancesRuleDesc" }
38+
]
39+
},
40+
"tags": {
41+
"type": "array",
42+
"description": "List of normative rule tags that reference the standard",
43+
"items": {
44+
"type": "object",
45+
"properties": {
46+
"name": {
47+
"$ref": "common-schema.json#/tagName",
48+
"description": "Name of the tag (an anchor in the standard's adoc files)"
49+
},
50+
"text": {
51+
"type": "string",
52+
"description": "The text from the standard associated with this tag"
53+
},
54+
"tag_filename": {
55+
"type": "string",
56+
"description": "Tag file that maps tag names to tag text"
57+
}
58+
},
59+
"required": ["name"]
60+
}
61+
}
62+
},
63+
"required": ["name", "def_filename"],
64+
"additionalProperties": false
65+
}
66+
}
67+
},
68+
"required": ["normative_rules"],
69+
"additionalProperties": false
70+
}

0 commit comments

Comments
 (0)