Look at ASCIIDoc extension to list tables and figures

[kersten1]

No description provided.

[kbroch-rivosinc]

I tested it out manually and it WAI.

PR to add it to the docker image: riscv/riscv-docs-base-container-image#6

[wmat]

Is that extension good enough?

I had intended on implementing this one: https://gitlab.com/baiyibai/asciidoctor-pdf-lofte which adheres the asciidoctor-pdf's TOC formatting and is also style-able.

[kbroch-rivosinc]

I wasn't aware of this other plugin. My hope was we'd find something that worked with both pdf and html output.

This one does: https://github.com/Alwinator/asciidoctor-lists but I do see that it has some features missing that we might care about (pg number on list?) and the pdf styling may not be honored.

I'll take a look at both and let you know.

[kbroch-rivosinc]

asciidoctor-lists

using latest release: https://github.com/Alwinator/asciidoctor-lists/releases/tag/v1.0.9
I used this spec to test.

HTML output :

PDF output:

Findings:

• both pdf and html output appears to use the theme's styling correctly
• listing is not capable of rendering the "code" backtick text correctly. Instead just leaves tags. ex: memvcfg

asciidoctor-pdf-lofte

using the latest release: asciidoctor-pdf-lofte

Here's branch of changes to example spec: https://github.com/kbroch-rivosinc/riscv-cfi/tree/dev/kbroch/try-asciidoctor-pdf-lofte

Findings:

• doesn't package code into gem, you simple have to download the unversioned ruby file
• pdf output has header theme correct but doesn't have the link color (instead same color as regular text not sure this is a problem given one expects a list of listings to be links)
• anchors have to be added to everything or no list items are generated (NOTE: I didn't add all of them)
• doesn't support HTML output at all
• the "List of Listings" comes after the "Preamble"?

My recommendation

Given asciidoctor-lists supports styling of themes, both pdf/html outputs, and is packaged as a gem for easy installation and maintenance, I would recommend using that. I'll file an issue on the back-tick code block not getting rendered in the title.

[kbroch-rivosinc]

Filed issue on backtick literal not rendered: Alwinator/asciidoctor-lists#23

[wmat]

Thanks @kbroch-rivosinc I agree, we should move forward with asciidoctor-lists for now.

[kbroch-rivosinc]

Filed issue on backtick literal not rendered: Alwinator/asciidoctor-lists#23

This works fine if list-of::image[enhanced_rendering=true] is used:

I can imagine wanting to use both of these parameters: list-of::image[hide_empty_section=true, enhanced_rendering=true]

[kbroch-rivosinc]

The only other feature I can see wanting currently is page numbers: Alwinator/asciidoctor-lists#14.
The maintainer of asciidoctor-pdf-lofte was also in this issue discussion (and zulipchat) but it doesn't look like it has progressed past that in over a year.

[wmat]

Lists of Tables/List of Figures has been raised as a possible addition to Unpriv and Priv. See riscv/riscv-isa-manual#1532

I have created a Branch from that issue and added Lof/Lot to Priv and Unpriv there. Note that only figures & tables with captions get picked up, which makes sense as asciidoctor needs to populate the list with some text. I have opened a discussion with Andrew W. in that issue for thoughts on moving forward. You can also either grab PDFs with the lists included from the Actions tab here https://github.com/riscv/riscv-isa-manual/actions/runs/9940634186 or run the Build ISAs action against that branch.