Add fancy hyperlinking code

[Timmmm]

It would be really cool if you could publish that code you demonstrated a while ago to bundle the code and add hyperlinks.

Adding Sail to the ISA manual seems to have completely stalled, so Prashanth suggested we maintain our own version with it added - I've set that up here, but it would be extra great if it had the hyperlinking.

[Alasdair]

Oh, I just looked and it's on the sail-xref branch of this repository. I can probably merge it into the main branch.

[Timmmm]

Ah yeah I found that. I made a branch that uses that branch. (Btw I was wrong earlier when I said asciidoctor-sail updates will immediately get picked up; it is part of the Dockerfile but not pinned so it will get updated when that Docker image is rebuilt.)

I replaced some vector instruction (vwsll.*) but it doesn't seem to have had any effect:

Should there be links to get_sew() etc? Have I missed some setup?

[Timmmm]

Here's the relevant commit: riscv/riscv-isa-manual@7762f18

[Alasdair]

You need to add a :sail-xref: attribute in the document, then it should try to hyperlink things together.

For external links, I have something like:

:sail-xref-external: https://alasdair.github.io/sail-riscv/%filehtml%#L%line%

which is a separate attribute that tells it where to link whenever it can't find an in document cross-reference.

What happens is it looks through any Sail code block for things of the form

sailref:attr#type[identifier]

and it uses attr to find the sail JSON bundle from something like

:attr: some_sail_doc_bundle.json

the type and identifier tell it what to link to, so it might be something like sailref:attr#function[foo]. It then does substitution very late on the asciidoctor produced HTML (the trick here is to teach the syntax highlighter about the sailref syntax so it doesn't get in the way) to insert the links.

I found asciidoc's built in linking features somewhat inadequate compared to say LaTeX which is why it ends up working this way, but it does come with the downside of not working in the PDF backend.

One gotcha is that if anything is even a little wrong, it basically just catches any exception that happens during the cross referencing process and substitutes back the raw identifier without a link. That makes it fairly robust, but it does mean that a small typo and all your links just vanish without much feedback.

[Alasdair]

Also small fix from yesterday: 30527b2

Might not be related to whatever issue you are having, but might be worth pulling anyway

[Timmmm]

Can you give me a hint how to:

a) Generate the HTML from the Sail code so it can be hyperlinked?
b) Do the instruction specialisation in Sail?

Is either of that documented somewhere I've missed?

[Alasdair]

For the HTML it should just be sail --html <files> -o <output directory>. There are a few other options to specify a prefix for each hyperlink in the output. If you use my Sail module PR it can just be sail --html riscv.sail_project ... which makes it quite easy.

The manual here has most of the information for the splitting I think

https://github.com/Alasdair/asciidoctor-sail/blob/master/doc/built/sail_to_asciidoc.pdf

The gist of it is you add an attribute on the function or execute clause you want to split, that references one of the arguments (which should be a finite type like an enumeration), and then all the specialised versions should be in the generated documentation.

$[split op]
function instr(rd: bits(5), rs1: bits(5), rs2: bits(5), op: Op) -> unit = {
  let rs1_val = X(rs1);
  let rs2_val = X(rs2);
  let result: bits(32) = match op {
    ADD => add_bits(rs1_val, rs2_val),
    SUB => sub_bits(rs1_val, rs2_val),
  };
  X(rd) = result
}

The caveat the manual mentions that it will contain desugared identifiers should now be fixed as I added a re-sugaring option to the pretty printer that reintroduces the original operators and overloads.

[Timmmm]

I got this working for riscv-isa-manual, e.g. see this instruction. It would be nice to get it merged!

Also I think there are a few more things that could be hyperlinked, e.g. union variants like VAESKF1_VI and global lets like RETIRE_SUCCESS. Also registers if they aren't already.

It's pretty great already though so I would just merge that branch and do a release for now.

[Timmmm]

Another thing that might be nice is to be able to have hyperlinks for built-in things like unsigned and vector_init that go somewhere that explains what they are. Maybe a reference section in the manual or something?

[wmat]

Which PR from the riscv-isa-manual directly implements this? Is it riscv/riscv-isa-manual#1838

[Timmmm]

That PR was just to add the initial snippets. I haven't made an PRs for the later changes (adding more snippets and now this). The work is all in this sail branch, and the change to make this highlighting stuff work is in this commit.

When I said "It would be nice to get it merged", I meant the asciidoctor-sail sail-xref branch btw. (It would be nice to get my sail branch merged too, but I think more persuasion is needed first.)