Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add links / tags for each statement #1397

Open
Timmmm opened this issue May 11, 2024 · 73 comments
Open

Add links / tags for each statement #1397

Timmmm opened this issue May 11, 2024 · 73 comments

Comments

@Timmmm
Copy link
Contributor

Timmmm commented May 11, 2024

It is very useful for specs to be linkable, for example to link coverpoints, test plans, tests, etc. to specific statements in the spec. This allows you to ensure that you

  1. have covered everything in the spec,
  2. notice when a part of the spec that you've already covered changes,
  3. notice when new parts of the spec are added.

There are some examples of this in the Ferrocene Rust Specification: (note each item has a unique ID, just not rendered):

image

In ARM's ASL reference manual (here they render the unique IDs):

image

Note that in both examples the writing style is a lot more like #1396 but you don't necessarily have to do it like that. In a previous company I implemented this system but you could tag parts of paragraphs too and the tag would highlight the tagged text when you hover it.
@Timmmm Timmmm mentioned this issue May 11, 2024
Open
@dhower-qc
Copy link

@edolnx was exploring something similar at one point

@wmat
Copy link
Collaborator

wmat commented Dec 2, 2024 via email

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 2, 2024

Yeah it's going to be quite tedious but I don't think there's any reason it has to happen all at once. We should probably start with the infrastructure, so it can be rendered as in the examples above.

@james-ball-qualcomm
Copy link
Contributor

We need links for our activity being lead in the CSC to create a golden list of all implementation-defined behaviors (calling them "parameters"). Umer is leading this effort and we are capturing our parameters in a spreadsheet at https://docs.google.com/spreadsheets/d/1tFGLbocTp1YNn11aN8JTmvxL_23e7x8SlBNJfOPRmAE

Notice there is a column for a "Reference to Standard" that is empty.

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 3, 2024 •
edited
Loading

Asciidoc's built in ID feature supports tagging a span. For example this:

This is a paragraph. [#rv_pmp-entries]#Up to 64 PMP entries blah blah blah.# The end of the paragraph.

Generates this HTML:

<p>This is a paragraph. <span id="rv_pmp-entries">Up to 64 PMP entries blah blah blah.</span> The end of the paragraph.</p>

It is possible to use pure CSS to show the tag with highlighting when you hover it (I've done this before). I'll have a go at doing it again.

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 3, 2024

Ok roughly something like this: asciidoc_link_test.zip. CSS isn't quite right but you get the idea.

Looks like this:

anchors.mp4

@wmat
Copy link
Collaborator

wmat commented Dec 3, 2024 via email

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 3, 2024

That is the HTML output, not PDF. I don't think there's any point trying to modify the PDF output.

@james-ball-qualcomm
Copy link
Contributor

Tim, the highlighting of the text is pretty cool. Also not sure about the tags being displayed in the right column. Can we put them inline in the text with special formatting somehow without affecting the readability of the existing text or requiring them to be heavily edited? I had thought of using an admonition like NOTE but that would be very disruptive to existing text.

Since I've proposed moving the email thread (https://lists.riscv.org/g/csc-tests-models-recommend/topic/109815116) to this GitHub case, let me add in some content from that thread here.

Here's my adoc code trying out the 3 different kinds of IDs.

This is before the parameter definition. [#param-foo-1]#Here's a parameter defined using inline anchors.# This is after the parameter definition.

[#param-foo-2]
Here's a parameter defined in its own block using the # ID syntax.

[[param-foo-3]]
Here's a parameter defined using an anchor.

|===
| Parameter Name | Parameter Reference | Parameter Text

| foo-1 | <<param-foo-1,foo-1>> | TBD
| foo-2 | <<param-foo-2,foo-2>> | TBD
| foo-3 | <<param-foo-3,foo-3>> | TBD

|===

and here's the output:

image

@james-ball-qualcomm
Copy link
Contributor

Is there some way in adoc to get the text associated with an ID? For a inline assignment that would be the text between the # marks. For an anchor, that would be the whole block associated with that anchor.

Here's links to the adoc documentation I'm using:

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 3, 2024 •
edited
Loading

Is there some way in adoc to get the text associated with an ID?

Yes you can convert it to XML using the Docbook output, and then you get elements like this:

<anchor xml:id="rv_fence_tso" xreflabel="The FENCE.TSO instruction is encoded as a FENCE instruction with fm=1000, predecessor=RW, and successor=RW."/>

Can we put them inline in the text with special formatting somehow without affecting the readability of the existing text or requiring them to be heavily edited?

Yeah there's a whole range of aesthetic options. We could style the text that has been highlighted in some subtle way, and then when you hover it it could show you the ID as a tooltip. Or maybe just make them all into links that link to themselves (so you can easily copy the URL), and don't show the ID at all.

@james-ball-qualcomm
Copy link
Contributor

Thank Tim. Is there a way to get the text inside adoc so it could fill in my table column I showed that currently says "TBD"?

@wmat
Copy link
Collaborator

wmat commented Dec 3, 2024 via email

@james-ball-qualcomm
Copy link
Contributor

Can we agree to allow the CSC to add parameter tags (i.e., implementation-defined options) to the ISA manuals using inline and block anchors (using [# ] for the latter)? If yes, then we need to agree on a naming convention for these tags. If no, what is required to get an agreed upon solution?

@wmat
Copy link
Collaborator

wmat commented Dec 4, 2024 via email

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 4, 2024

The IDs also need to start with something unique to this tagging effort so they are distinguishable from other IDs (e.g. the auto IDs used for section headers). I used rv_ in the example above but it could be anything.

@james-ball-qualcomm
Copy link
Contributor

@dhower-qc, you are familiar with Antora and our needs for the CSC parameter linking to standards. Will the rewriting of IDs by Antora's assembler impact our use?

As for a naming convention, how about a prefix of "param-" followed by the parameter name with dashes to separate words?

@dhower-qc
Copy link

I suggest our ID standards be more strict than Antora -- we want globally-unique IDs.

As for the specifics, I think we need to get a wish list of what we want out of tagging first. @kasanovic might have ideas on this, too, but as a start:

Must have:

  • unique, immutable, ID per linkable "statement" (even grammar changes, ID doesn't)

Nice to have:

  • Extension the statement belongs to
  • Base (RV32/64) the statement belongs to, when not both
  • Conditions when the statement applies (e.g., "when H is implemented...)

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 4, 2024

As for a naming convention, how about a prefix of "param-" followed by the parameter name with dashes to separate words?

These IDs aren't going to be just for parameters. The idea is every statement (at least the normative ones) has a tag, so you can link test plans and coverage to them.

@james-ball-qualcomm
Copy link
Contributor

Understood Tim. I'm focusing on the parameters at the moment given our effort to create a golden list of implementation-defined behaviors. I'd like to start making these tags and adding them to the parameter spreadsheet and see how it goes. Do I have permission to create a new issue for this specific case and then start putting parameter tags into the adoc manual source? Then I'll be doing a PR to get them merged in.

@allenjbaum
Copy link

allenjbaum commented Dec 4, 2024 via email

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 4, 2024

The text only has one tag, as shown in my example. Then the parameter list, coverpoints, test plans, test suites, etc. can all refer to that same tag.

@james-ball-qualcomm
Copy link
Contributor

Tim, your suggestion of having a tag for every normative statement sounds like a pretty large change to the way our specs are currently written. Am I correct? If so, I'm wondering how we take that one without delaying some solution for parameter tags. There are probably something like 100 parameter tags we need to add so a much smaller problem then having a unique tag for each normative statement and much less disruptive to the current adoc specs.

Allen, couldn't we have multiple tags to the same adoc content? If adoc doesn't support this, we could add our own extension to adoc to better support multiple tags or a more sophisticated tagging mechanism. We could UDB to convert such adoc with our own tagging extension into normal adoc to be rendered into PDF/HTML. We might want to go down this pay anyways for other related reasons (discussed at the UDB meeting today).

@allenjbaum
Copy link

allenjbaum commented Dec 4, 2024 via email

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 4, 2024

Yeah adding tags everywhere is a very big task. I think adding a subset that are needed for the parameter list as the initial set is totally reasonable.

we could add our own extension to adoc to better support multiple tags or a more sophisticated tagging mechanism

That's not necessary unless I've missed something. The tags provide a programmatic way to identify statements in the spec. Other documents (the parameter list, test plans, etc.) can then use those tags to programmatically connect to those statements. The spec itself (and the tags) will have no idea that the parameter list or the test plans exist.

@james-ball-qualcomm
Copy link
Contributor

Instead of making links to Tim's website, we could use this: https://riscv-software-src.github.io/riscv-unified-db/manual/html/isa/20240411/index.html

This is the 2024-04-11 version of the ISA manuals so should be static. It is generated by UDB and it gets the ISA manual contents from the RVI GitHub.

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 5, 2024

A slight issue with that is that it is multipage, which is not how the spec is built by default so the links will be different.

The fact that it is on my domain is not an issue - it's trivial to change the base of the URLs. The important thing would be that the file & fragment are the same.

Consider:

Note chapters/zifencei.html#:~:text=... vs unpriv-isa-asciidoc.html#zifencei:~:text=... - that's the important thing. @wmat is planning to host an official copy at some point and then we can just rewrite all the URLs to point to that (see #1427).

Anyway this is kind of off-topic for this issue.

@allenjbaum
Copy link

allenjbaum commented Dec 5, 2024 via email

@wmat
Copy link
Collaborator

wmat commented Dec 6, 2024 via email

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 11, 2024

This is because a PR to the ISA manual could change things like section names and or the content that has a tag.

Do you mean because the .html filenames might change in the multi-page output? If so, I agree that is a slightly annoying. I think the best solution is probably to also host single-page versions of the documents. (And anyone using this feature is free to do that themselves of course.)

@james-ball-qualcomm
Copy link
Contributor

james-ball-qualcomm commented Dec 11, 2024 •
edited
Loading

Bill, what happens if a PR changes a sentence that we have tagged using Asciidoc tags? If we have certification test plans that rely on the previous content of the sentence then it could mean the test plan is no longer valid.

@wmat
Copy link
Collaborator

wmat commented Dec 11, 2024

If a PR changes actual content that is tagged and your certification test plan relies on the content prior to the change then yes, the test plan could be invalid moving forward, however the test would remain valid prior to the change being made. So you'd have to point at a specific commit hash to continue to rely on that test.

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 11, 2024

Yes, the fact that the tag persists across content changes is a good thing. It allows you to detect those content changes in a nice way.

As @wmat said you should include the spec version or commit hash in your reference. When you want to update to a new spec version you can extract the content of each tag and check which ones have changed (and possibly update your tests/coverpoints/assertions/etc.).

An alternative would be to have the tag be the hash of the content, but I think the UX of that would be worse (tag 384bef23 no longer present rather than tag qx_x0_is_zero changed from "x0 is hardwired to zero" to "x0 is hardwired to 0 or 1"), and also it's harder to implement in Asciidoc. I guess this is how the ASL example at the top of this thread works, but I haven't checked. I don't think we should do that.

@james-ball-qualcomm
Copy link
Contributor

I discussed this with @jrgrimm11 today at our 1:1 and came to pretty the same conclusion as you two (Tim & Bill). As long as we can extract the tags and their content from the adoc in an automated fashion and we have our certification test plans point to a particular release of the manuals then we can create a tool to detect changes to the tagged content. So, maybe that should be our plan of record. We just need a agreed upon naming scheme to identify tags and some way to extract them from the adoc. I'd prefer something smarter than just grepping for them. Tim/Bill/Derek, any recommendations here?

I believe we should initially assume the tags aren't allowed to change the ISA manual content since it is ratified text. We'll see how that goes and we can focus on the base ISA and extensions for MC100 (see https://riscv-software-src.github.io/riscv-unified-db/pdfs/MC100.pdf) as a pipe cleaner. The tags wouldn't be visible in the standard PDF and HTML generated from the adoc. I would expect to add the ISA manuals as appendices to certification test plans (which we can generate from riscv-unified-db with some work) and then the tag references in the certification test plans will become hyperlinks into the ISA manual appendices. It would be cool if we could show the tag names and identify what they reference like Tim was showing with CSS and HTML.

@james-ball-qualcomm
Copy link
Contributor

Just saw this in Tim's example in #1769:

"Detecting when parts of the spec change. You can extract these snippets via Asciidoc's docbook output and parsing the XML."

@james-ball-qualcomm
Copy link
Contributor

Let's discuss a standard naming scheme for tags. So far, we need tags for parameters (AKA implementation-defined behaviors) and we need tags for normative rules which we need for CSC certification test plans (although I expect many community members will use the tags to create their verification test plans for their IP cores they are developing).

Naming of parameters (AKA implementation-defined behaviors):

  • rv_param-<category>-<name>

I'm using - to separate fields and _ within fields. The combination of category and name must be unique (ignoring case) across all RVI standards (ISA and non-ISA). The category is whatever is most related to the parameter. For example, if a parameter is clearly related to just one extension it can be the extension name. Could also be related to a CSR name, CSR field, ISA feature, etc. Category is just used for filtering/searching.

Examples:

  • rv_param-U-endianess // U isn't strictly speaking a named extension but probably should be
  • rv_param-S-endianess // S actually is a named extension
  • rv_param-cache-block_size // Block size is defined by multiple extensions so the category is set to cache and not an extension name
  • rv_param-Zicntr-time_CSR_implemented // Associated with the Zicntr extension

Naming of normative rules:

  • rv_norm_rule-<category>-<name>

Same rules for category and name as for parameters.

@dhower-qc
Copy link

Since all param-creating statements come from normative text, do they get two tags?

@james-ball-qualcomm
Copy link
Contributor

Hummm, good point. Having 2 tags wouldn't be great or even work properly using the adoc facility. The parameters are meant to capture implemented-defined behaviors (AKA parameters, AKA options) whereas the normative rules are meant to capture certification test coverage points. I think of parameters as a particular type of normative rule so if the normative text can be characterized as a parameter the rv_param is used and otherwise rv_norm_rule is used. How's this idea?

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 13, 2024

There's no need to encode information into the IDs like "is it a parameter". The only requirement is that it uniquely identifies a bit of text, so rv_cache_block_size is sufficient. This also helps avoid making them too long because that's going to make reading and writing the asciidoc even more annoying.

We should use a more unique prefix than rv to avoid the risk of clashes with automatically generated IDs. I used qx_ in my PR.

@aswaterman
Copy link
Member

Any idea when Andrew will complete that?

I'd like to do so this before Christmas, but it might spill over into next year.

@james-ball-qualcomm
Copy link
Contributor

Actually Andrew, I now realize that we need to be adding tags to ISA manual contents in the main branch so there isn't a dependency on you identifying a suitable Priv ISA manual release anymore. However, it would still be good to get that done so that we can point the UDB manual it uses to the release you identify.

@james-ball-qualcomm
Copy link
Contributor

Tim, you raised a couple of issues with my proposal:

  1. Unique prefix
  2. Naming after prefix

Let me focus on #2 first since it is the juicier topic. At the very minimum, the name has to be unique and immutable. However, we could also encode some meta data into the name. There is a continuum of possibilities of encoding meta data into the name from having no meta data to trying to encode every conceivable type of meta data such as:

  • The kind of normative rule (e.g., parameter or generic normative rule)
  • Some kind of category (e.g., extension name, ISA feature, etc)
  • Version number of category when normative rule becomes in-scope (e.g., version 1.13 of Priv ISA)
  • Dependencies on other extensions (e.g., normative rule only applies if F or D extension is present)

Here's some screenshots of how other references have done this. Note that these are all visible tags and not adoc tags we are talking about here but I think they are still interesting to see. You'll see that the RISC-V Server SoC spec has a category and 3-digit number for the name. Arm uses "R" for normative rules and "I" for non-normative rules (AKA informative) followed by a 5 letter randomly generated unique name. SPARC had a tag to highlight implementation dependencies followed by a unique integer.

For UDB, we just need a unique prefix and a unique name after that we can then put all the meta data associated with a tag in UDB. However, UDB isn't the only tool that will probably use these tags. In particular, I would imagine that customers creating verification test plans for their implementations could find them useful. This is why I'm proposing a category and a different unique prefix for parameters vs. generic normative rules.

image

image

image

@allenjbaum
Copy link

allenjbaum commented Dec 14, 2024 via email

@james-ball-qualcomm
Copy link
Contributor

Allen, I fully anticipate that when we start this tagging activity we'll encounter all of the problems you imagine. This is because the normative prose in the manuals weren't written with the requirement that it could be tagged some day into crisp normative rules and implementation-defined behaviors. This tagging activity will highlight examples of where tagging doesn't work well with the existing prose. Hopefully this will help RVI understand better the nature of the issue/challenge and we'll be able to find an acceptable solution.

For example, we may decide to edit the content of the manuals without changing any normative behaviors (keeping the same intent) so that we can have crisp tags. This will better meet the needs of certification and verification. To be clear, by verification, I mean the activity a processor design team engages in to fully debug their implementation (i.e., not certification).

@aswaterman
Copy link
Member

Actually Andrew, I now realize that we need to be adding tags to ISA manual contents in the main branch so there isn't a dependency on you identifying a suitable Priv ISA manual release anymore. However, it would still be good to get that done so that we can point the UDB manual it uses to the release you identify.

Ack. But I agree it would still be good to get that done, since it has been a while since the last release, and much has been ratified since then.

@wmat
Copy link
Collaborator

wmat commented Dec 16, 2024 via email

@jalobaba
Copy link
Collaborator

Thanks Bill. I took I look at your links and they're related to sections. Those are too coarse-grained (we need to be able to tag things like sentences or even portions of a sentence). So I'm not so sure that it helps in this situation.

By the way this is James Ball from my personal account instead of my work account.

@wmat
Copy link
Collaborator

wmat commented Dec 16, 2024

Yes, the first link was about sections. The second talks about inline assignment, I believe.

@Timmmm
Copy link
Contributor Author

Timmmm commented Dec 16, 2024

IMO encoding information into the tag adds extra work, verbosity and opens up awkward questions (e.g. Allen's points) without really giving significant advantages. The metadata associated with the tags would be much better stored in external documents.

Perhaps the best course of action would be to pick a section of the spec and fully add tags? Then we can compare a realistic example of how it looks with either scheme.

@james-ball-qualcomm
Copy link
Contributor

Yes, the second link was related to inline tags and we've already seen that page (and plan to use it).

@james-ball-qualcomm
Copy link
Contributor

james-ball-qualcomm commented Dec 16, 2024 •
edited
Loading

I think Allen's issues are orthogonal to whether our tag names contain some meta data or not. That's because I see Allen's issues are related to the current writing style of the ISA manuals that were written without a requirement to make crisp normative rules. Because I plan to use UDB with the tags, I can add all the meta data I need in UDB and have none in the tags. However, as I mentioned earlier, I don't want to assume that all consumers of the tags will be using UDB so having the minimal meta data I suggested (i.e., having a category and differentiating between generic normative rules and implementation-defined behaviors) seems like a good compromise. I don't really see how it adds significantly to the work but does make the tag names larger but is that really a significant constraint? IMO what I'm proposing is the sweet-spot between having no meta data vs. having all the meta data possible. However, that's just my opinion and I'm looking for a consensus from those following this GitHub issue so I'd like to hear other opinions.

@james-ball-qualcomm
Copy link
Contributor

james-ball-qualcomm commented Jan 16, 2025 •
edited
Loading

I'm finally moving ahead with this today. I've forked the ISA manual into https://github.com/RISC-V-Certification-Steering-Committee/riscv-isa-manual (hope this was the right thing to do) and am now starting to put anchors into the ISA manual adoc source. Note that I've been poking around in the ISA manual adoc source and see extensive use of both the anchor syntax (e.g., [[foo]]) and ID syntax (e.g., [#foo]) so I'm assuming Antora can work with both. Bill hypothesized earlier in this issue that Antora can only work with the ID syntax but I think I have an existence proof that it can handle either syntax.

According to https://docs.asciidoctor.org/asciidoc/latest/attributes/id/, the anchor syntax ([[foo]]) has the advantage over the ID syntax ([#foo]) that the anchor name can contain a "." without being incorrectly interpreted as a "role". The anchor syntax also works in a list item or table cell whereas the ID syntax doesn't. The only place is seems that the ID syntax has an advantage is for an inline anchor such as:

[#bookmark-b]#Inline anchors can be applied to a phrase# like this one.

Both the anchor syntax and ID syntax can be associated with a block (on the line before it starts) such as:

[[notice]]  
This paragraph gets a lot of attention.

or

[#notice]  
This paragraph gets a lot of attention.

Another advantage of the anchor syntax is that you can put multiple of them on the same section or block such as:

<<inst-add-def>>
<<inst-c.add-def>>
= [[inst-add-def]][[inst-c.add-def]]add

and

<<inst-add-def>>
<<inst-c.add-def>>
[[inst-add-def]][[inst-c.add-def]]
Here's a block of text.

as long as you put them before the section name like in the above example.

@james-ball-qualcomm
Copy link
Contributor

I see the ISA manuals have this format for the newer instructions that have an instruction per page (like B extension, scalar crypto, Zc extension). Must be the work of @kdockser and @tariqkurd-repo.

Anchor: [#insns-czero-eqz,reftext="Conditional zero, if condition is equal to zero"]
Link: <<#insns-czero-eqz>>

I haven't seen using a "#" in the link before in AsciiDoc. I tried an experiment and the VSCode adoc previewer seems to ignore one leading "#" in the link (a "#" isn't required though).

image

@james-ball-qualcomm
Copy link
Contributor

BTW, I noticed this when I built the ISA manual and got lots of messages about missing link anchors (for older instructions). Maybe we should provide these in the UDB appendices so that the links actually have an anchor to go to.

asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-lui
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-auipc
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-addi
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-slti
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sltiu
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-xori
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-ori
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-andi
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-slli
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-srli
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-srai
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-add
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sub
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sll
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-slt
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sltu
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-xor
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-srl
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sra
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-or
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-and
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-addiw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-slliw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-srliw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sraiw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-addw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-subw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sllw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-srlw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sraw

@jjscheel
Copy link
Contributor

Note that I've been poking around in the ISA manual adoc source and see extensive use of both the anchor syntax (e.g., [[foo]]) and ID syntax (e.g., [#foo]) so I'm assuming Antora can work with both. Bill hypothesized earlier in this issue that Antora can only work with the ID syntax but I think I have an existence proof that it can handle either syntax.

Because the rollout of Antora deployments is incomplete, this is not a safe assumption. @wmat, can you take a definitive position on this, please?

@jjscheel
Copy link
Contributor

BTW, I noticed this when I built the ISA manual and got lots of messages about missing link anchors (for older instructions). Maybe we should provide these in the UDB appendices so that the links actually have an anchor to go to.

Seems like the better approach would be to fix the base ISA doc. @kersten1, can you work to drive this list of invalid anchors to 0?

@wmat
Copy link
Collaborator

wmat commented Jan 16, 2025

BTW, I noticed this when I built the ISA manual and got lots of messages about missing link anchors (for older instructions). Maybe we should provide these in the UDB appendices so that the links actually have an anchor to go to.

asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-lui
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-auipc
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-addi
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-slti
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sltiu
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-xori
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-ori
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-andi
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-slli
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-srli
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-srai
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-add
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sub
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sll
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-slt
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sltu
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-xor
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-srl
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sra
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-or
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-and
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-addiw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-slliw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-srliw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sraiw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-addw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-subw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sllw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-srlw
asciidoctor: WARNING: riscv-unprivileged.adoc: invalid reference to unknown anchor: insns-sraw

This is logged here: #1458

@wmat
Copy link
Collaborator

wmat commented Jan 16, 2025 via email

@james-ball-qualcomm
Copy link
Contributor

There are tons of anchor syntax (e.g., [[foo]]) in the ISA manuals. Do you plan to remove them all?

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
8 participants
@wmat @Timmmm @aswaterman @jjscheel @allenjbaum @jalobaba @dhower-qc @james-ball-qualcomm