Skip to content

Commit e9f5494

Browse files
james-ball-qualcommjames-ball-qualcomm
committed
Update normative rule documentation to match improvements in tagging made by Tim Hutt
Signed-off-by: James Ball <[email protected]>
1 parent 992c7a1 commit e9f5494

File tree

1 file changed

+55
-27
lines changed

1 file changed

+55
-27
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

0 commit comments

Comments
 (0)