Skip to content

Commit 4b6af80

Browse files
james-ball-qualcommjames-ball-qualcomm
authored
Merge pull request #101 from riscv/100-inline-anchors-for-list-table-items
Update test.adoc to use inline anchors.
2 parents 14a3283 + e9f5494 commit 4b6af80

File tree

5 files changed

+82
-53
lines changed

5 files changed

+82
-53
lines changed

‎normative-rules.md‎

Lines changed: 55 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -34,7 +34,7 @@ Quite often there is a "1:1" mapping between normative rules and tags, but not a
3434

3535
## AsciiDoc Anchor Background
3636

37-
AsciiDoc provides facilities to create invisible anchors associated with an entire paragraph or portions of a paragraph. These anchors are only visible in raw AsciiDoc files and are invisible in the PDF and GitHub AsciiDoc previewer. Each "tag" added to an AsciiDoc file to identify normative text (remember, not always 1:1 mapping from normative rules to tags) has an associated anchor name. These anchor names must be unique across all the AsciiDoc files used by a particular standard but aren't required to be unique across standards. Each RISC-V standard defines the naming convention of these anchor names but the anchor names must start with the prefix of "norm:" so they can be readily located by tools.
37+
AsciiDoc provides facilities to create invisible anchors associated with an entire paragraph or portions of a paragraph. These anchors are only visible in raw AsciiDoc files and are invisible in the PDF and GitHub AsciiDoc previewer. Each "tag" added to an AsciiDoc file to identify normative text (remember, not always a 1:1 mapping from normative rules to tags) has an associated anchor name. These anchor names must be unique across all the AsciiDoc files used by a particular standard but aren't required to be unique across standards. Each RISC-V standard defines the naming convention of these anchor names but the anchor names must start with the prefix of "norm:" so they can be readily located by tools.
3838

3939
AsciiDoc supports several styles of anchors:
4040
* _inline anchor_ such as:<br>
@@ -46,7 +46,7 @@ AsciiDoc supports several styles of anchors:
4646
>
4747
> `This isn't part of the anchor since it is the next paragraph.`
4848
49-
* You must use the _paragraph anchor_ for table cells, unordered/ordered list items or description list terms
49+
* You must use the _inline anchor_ for table cells, unordered/ordered list items, description list items.
5050

5151
Naming restrictions:
5252
* Start anchor names with a letter and use `:` to separate fields in the anchor name. No spaces allowed in name.
@@ -59,35 +59,64 @@ If you'd like to get more detailed AsciiDoc information on anchors, please read:
5959
* How to make cross-references: https://docs.asciidoctor.org/asciidoc/latest/macros/xref/
6060
* How to create anchors: https://docs.asciidoctor.org/asciidoc/latest/attributes/id/
6161

62+
If you'd like to see detailed AsciiDoc examples of tagging cases, see https://github.com/riscv/docs-resources/blob/main/tests/norm-rule/test.adoc.
63+
6264
## Using AsciiDoc Anchors to Tag Normative Rules
63-
1. Tag part of a paragraph
65+
1. Tagging entire paragraph, entire table, entire unordered/ordered/description list
66+
67+
> Syntax: `[[<anchor-name]]`<br>
68+
>
69+
> Example:<br>
70+
>> `[[norm:zort]]`<br>
71+
>> `Here is an example of anchoring a whole paragraph.`<br>
72+
>> Tagged text: Entire paragraph<br>
73+
>
74+
> Example:<br>
75+
>> `My favorite fruits:`<br><br>
76+
>> `[[norm:favorite-fruits]]`<br>
77+
>> `* mango`<br>
78+
>> `* banana`<br>
79+
>> `* apple`<br>
80+
>> Tagged text: `mango, banana, apple`<br>
81+
>
82+
> Example:<br>
83+
>> `[[norm:fruit-colors]]`<br>
84+
>> `Apples::`<br>
85+
>> `Typically be red, yellow, or green.`<br>
86+
>> <br>
87+
>> `Oranges:: Generally orange in color`<br>
88+
>> <br>
89+
>> `Bananas::`<br>
90+
>> `Typically yellow`<br>
91+
>> Tagged text: Entire description list
92+
93+
2. Tagging part of a paragraph, table cells, unordered list items (AKA bullet list), or ordered list items (AKA numbered list)
6494

6595
> Syntax: `[#<anchor-name>]# ... #`<br>
66-
> Example: `Here is an example of [#norm:foo]#anchoring part# of a paragraph
67-
> and can have [#norm:bar]#multiple anchors# if needed.`<br>
68-
> Tagged text: `anchoring part` and `multiple anchors`<br>
96+
>
97+
> Example:
98+
>> `Here is an example of [#norm:foo]#anchoring part# of a paragraph
99+
>> and can have [#norm:bar]#multiple anchors# if needed.`<br>
100+
>> Tagged text: `anchoring part` and `multiple anchors`<br>
101+
>
102+
> Example:<br>
103+
>> `| Alan Turing | [#norm:Alan_Turing_Birthday]#June 23, 1912# | London`<br>
104+
>> Tagged text: `June 23, 1912`<br>
105+
>
106+
> Example:<br>
107+
>> `My favorite fruits:`<br><br>
108+
>> `* [#norm:fruit1]#mango#`<br>
109+
>> `* banana`<br>
110+
>> `* [#norm:fruit3]#apple#`<br>
111+
>> Tagged text: `mango` and `apple`<br>
69112
>
70113
> Limitations:
71114
> * Can't anchor text across multiple paragraphs.
72-
> * Can't use in table cells, list items, or description list items (see #3 below for work-around).
73115
> * Must have text next to the 2nd hash symbol (i.e., can't have newline after `[#<anchor-name]#`).
74-
> * Can't put inside admonitions such as [NOTE] (see #5 below for solution).
116+
> * Can't put inside admonitions such as [NOTE] (see #4 below for solution).
75117
> * Can't have `.` in anchor-name (replace with `-`)
76118
77-
2. Tag entire paragraph
78-
79-
> Syntax: `[[<anchor-name]]`<br>
80-
> Example: `[[norm:zort]]`<br>
81-
> `Here is an example of anchoring a whole paragraph.`<br>
82-
> Tagged text: Entire paragraph<br>
83-
84-
3. Tag tables, unordered lists (AKA bullet), or ordered lists (AKA numbered)
85-
* Don't have acceptable solution right now (see https://github.com/riscv/docs-resources/issues/72)
86-
87-
> Example: `| Alan Turing | [[norm:Alan_Turing_Birthday]] June 23, 1912 | London`<br>
88-
> Won't create a tag (just creates hyperlink to anchor in table/list entry so not so useful)
89-
90-
4. Tag description lists
119+
3. Tagging description lists
91120
* For description list terms (e.g., `Apples`, `Oranges`), put the anchor immediately after the term on its own line as follows:
92121
> `Apples::`<br>
93122
> `[[norm:apple-colors]]`<br>
@@ -105,8 +134,7 @@ If you'd like to get more detailed AsciiDoc information on anchors, please read:
105134
> `Bananas::`<br>
106135
> `Generally yellow in color`
107136
108-
5. Tag admonitions (e.g. `[NOTE]`):
109-
* Must use `[[<anchor-name]]` before each paragraph (with unique anchor names of course) being tagged
110-
* Can't use `[#<anchor-name]#Here's some note text.#` since it just shows up in HTML as normal text
111-
* Don't put `[[<<anchor-name]]` before the entire admonition (e.g., before `[NOTE]`) to apply to entire admonition
112-
(one or more paragraphs) since it will just create a hyperlink with no associated text.
137+
4. Tagging admonitions (e.g. `[NOTE]`):
138+
* Can tag entire admonition by putting ``[[anchor-name]]`` before `[NOTE]`
139+
* Can also tag individual paragraphs in admonition using `[[<anchor-name]]` before each paragraph
140+
* Only use `NOTE: [#<anchor-name]#Here's some note text.#` for this style of admonition

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -74,7 +74,7 @@
7474
"tags": [
7575
{
7676
"name": "norm:table:anchors-in-cells:entire-table",
77-
"text": "===\n cell with anchor\ncell without anchor\n===",
77+
"text": "===\ncell with anchor\ncell without anchor\n===",
7878
"tag_filename": "/build/test-norm-tags.json"
7979
}
8080
]
@@ -98,7 +98,7 @@
9898
"tags": [
9999
{
100100
"name": "norm:unordered-list:anchors-in-items:entire-list",
101-
"text": "Item 1\n Item 2\nItem 3",
101+
"text": "Item 1\nItem 2\nItem 3",
102102
"tag_filename": "/build/test-norm-tags.json"
103103
}
104104
]

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

-2 Bytes
Binary file not shown.

‎tests/norm-rule/expected/test-norm-tags.json‎

Lines changed: 11 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -6,28 +6,28 @@
66
"norm:paragraph:inline-anchors:entire": "Paragraph with inline anchor and something.",
77
"norm:paragraph:tag_with_newlines": "Here&#8217;s the first line. Here&#8217;s the second line.",
88
"norm:table:no-anchors-in-cells:entire-table": "Header 1|Header 2\n===\nCell in column 1, row 1|Cell in column 2, row 1\nCell in column 1, row 2|Cell in column 2, row 2\n===",
9-
"norm:table:anchors-in-cells:cell": "",
10-
"norm:table:anchors-in-cells:entire-table": "===\n cell with anchor\ncell without anchor\n===",
9+
"norm:table:anchors-in-cells:cell": "cell with anchor",
10+
"norm:table:anchors-in-cells:entire-table": "===\ncell with anchor\ncell without anchor\n===",
1111
"norm:unordered-list:no-anchors-in-items:entire-list": "Item A\nItem B\nItem C",
12-
"norm:unordered-list:anchors-in-items:item1": "",
13-
"norm:unordered-list:anchors-in-items:item2": "",
14-
"norm:unordered-list:anchors-in-items:entire-list": "Item 1\n Item 2\nItem 3",
12+
"norm:unordered-list:anchors-in-items:item1": "Item 1",
13+
"norm:unordered-list:anchors-in-items:item2": "Item 2",
14+
"norm:unordered-list:anchors-in-items:entire-list": "Item 1\nItem 2\nItem 3",
1515
"norm:unordered-list:multiple-levels": "Zca and not F\nZca, Zcf and F (but not D) is specified (RV32 only)\nZca, Zcf and Zcd if D is specified (RV32 only)\n\nthis configuration excludes Zcmp, Zcmt\nZca, Zcd if D is specified (RV64 only)\n\nthis configuration excludes Zcmp, Zcmt",
1616
"norm:ordered-list:no-anchors-in-items:entire-list": "Item A\nItem B\nItem C",
17-
"norm:ordered-list:anchors-in-items:item1": "",
18-
"norm:ordered-list:anchors-in-items:item2": "",
19-
"norm:ordered-list:anchors-in-items:entire-list": "Item 1\n Item 2\nItem 3",
17+
"norm:ordered-list:anchors-in-items:item1": "Item 1",
18+
"norm:ordered-list:anchors-in-items:item2": "Item 2",
19+
"norm:ordered-list:anchors-in-items:entire-list": "Item 1\nItem 2\nItem 3",
2020
"norm:description-list:no-anchors-in-items:entire-list": "Description-A\nItem A\nDescription-B\nItem B\nDescription-C\nItem C",
2121
"norm:description-list:anchors-in-items:entire-list": "Description-1",
2222
"norm:description-list:anchors-in-items:item1": "Item 1",
2323
"norm:description-list:anchors-in-items:item3": "Item 3",
24-
"norm:admonition:single-paragraph-note": "",
24+
"norm:admonition:single-paragraph-note": "Single paragraph note\nthat spans lines.",
2525
"norm:admonition:no-anchors-in-notes:entire-note": "Paragraph A\n\nParagraph B\n\nParagraph C",
2626
"norm:admonition:anchors-in-notes:note1": "Paragraph 1",
2727
"norm:admonition:anchors-in-notes:note3": "Paragraph 3",
2828
"norm:admonition:anchors-in-notes:entire-note": "Paragraph 1\n\nParagraph 2\n\nParagraph 3",
29-
"norm:admonition:only-anchors-in-notes:note1": "Paragraph 1",
30-
"norm:admonition:only-anchors-in-notes:note3": "Paragraph 3"
29+
"norm:admonition:only-anchors-in-notes:note1": "Paragraph X",
30+
"norm:admonition:only-anchors-in-notes:note3": "Paragraph Z"
3131
},
3232
"sections": {
3333
"title": "",

‎tests/norm-rule/test.adoc‎

Lines changed: 14 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -47,8 +47,8 @@ Here's the second line.
4747
[[norm:table:anchors-in-cells:entire-table]]
4848
|===
4949

50-
// FAILS - Tag is empty string
51-
| [[norm:table:anchors-in-cells:cell]] cell with anchor
50+
// PASSES
51+
| [#norm:table:anchors-in-cells:cell]#cell with anchor#
5252
| cell without anchor
5353
|===
5454

@@ -64,9 +64,9 @@ Some text here.
6464

6565
// PASSES - Tag includes all items
6666
[[norm:unordered-list:anchors-in-items:entire-list]]
67-
// FAILS - Tags are empty strings
68-
* [[norm:unordered-list:anchors-in-items:item1]] Item 1
69-
* [[norm:unordered-list:anchors-in-items:item2]] Item 2
67+
// PASSES
68+
* [#norm:unordered-list:anchors-in-items:item1]#Item 1#
69+
* [#norm:unordered-list:anchors-in-items:item2]#Item 2#
7070
* Item 3
7171

7272
Some text here.
@@ -90,9 +90,9 @@ Some text here.
9090

9191
// PASSES - Tag contains entire list
9292
[[norm:ordered-list:anchors-in-items:entire-list]]
93-
// FAILS - Tags are empty strings
94-
. [[norm:ordered-list:anchors-in-items:item1]] Item 1
95-
. [[norm:ordered-list:anchors-in-items:item2]] Item 2
93+
// PASSES
94+
. [#norm:ordered-list:anchors-in-items:item1]#Item 1#
95+
. [#norm:ordered-list:anchors-in-items:item2]#Item 2#
9696
. Item 3
9797

9898
== Chapter 5 - Tagging Description Lists
@@ -124,8 +124,9 @@ Item 3
124124

125125
== Chapter 6 - Tagging Admonitions
126126

127-
// FAILS - Tag is empty string
128-
NOTE: [[norm:admonition:single-paragraph-note]] Single paragraph note
127+
// PASSES
128+
NOTE: [#norm:admonition:single-paragraph-note]#Single paragraph note
129+
that spans lines.#
129130

130131
// PASSES - Tag contains entire list
131132
[[norm:admonition:no-anchors-in-notes:entire-note]]
@@ -157,11 +158,11 @@ Paragraph 3
157158
====
158159
// PASSES - Tag contains paragraph
159160
[[norm:admonition:only-anchors-in-notes:note1]]
160-
Paragraph 1
161+
Paragraph X
161162
162-
Paragraph 2
163+
Paragraph Y
163164
164165
// PASSES - Tag contains paragraph
165166
[[norm:admonition:only-anchors-in-notes:note3]]
166-
Paragraph 3
167+
Paragraph Z
167168
====

0 commit comments

Comments
 (0)