accessibility: add SVG metadata and alt text to wavedrom diagrams

[Maanvi212006]

Fixes #1129

This PR adds accessibility improvements to WaveDrom and bytefield diagrams in the HTML output.

Changes:

• Add docs-resources/tools/wavedrom_a11y.py — a script that processes .edn files and injects <title>, , and aria-label into generated SVGs, and also updates the alt text in the [wavedrom, ,svg] block so screen readers can read it when embedded as base64
• Update b-immediate.edn, atomic-mem.edn, c-breakpoint-instr.edn as examples

- Add a11y-desc comment to fprs.edn for bytefield diagrams that can't be auto-parsed

[Maanvi212006]

I notice the CI is failing due to the script being placed in the docs-resources submodule. Should I move it to a tools/ folder in the main repo instead, or is there a preferred location for this kind of script?

[Masanori Ogino (omasanori)]

I guess a PR would be sent to docs-resources and then another one to here after the first one is accepted, as this script would help other docs. Bill Traynor (@wmat) Andrew Waterman (@aswaterman) Your opinions?

[Bill Traynor (wmat)]

Agreed, please add the script to docs-resources. As soon as the PR is there, we can update to the latest version of docs-resources and test the accessibility examples.

[Maanvi212006]

Alright! I'll open a PR in docs-resources first with the script, and then follow up with a PR here once it's accepted. Will close this one.

[Bill Traynor (wmat)]

Reopening so I can test locally. DO NOT MERGE yet.

[Bill Traynor (wmat)]

So what's the exact test case for this? I have checked out the PR for the accessibility changes to 3 figures, pointed my local source at the latest docs-resources and builts all of the docs with Make. What should happen from an accessibility perspective? I've tried with the Read Aloud chrome extension but don't get any results from the built HTML.

[Maanvi212006]

It should actually pick up alt attribute.
It should now read something like:

<img src="data:image/svg+xml;base64,..." alt="B-immediate instruction encoding">

But I guess Read Aloud is not able to pick it up. When I searched online, it says that screen readers like NVDA and VoiceOver can give more accurate results.
But, we will have to make a fix that works for Read Aloud as well.
So, a proper fix is to inline the SVGs directly into the HTML by disabling data-uri: for HTML builds. That way title and desc are directly readable by all screen readers including Read Aloud and alt attribute will then be irrelevant in this case.

Let me know if this works

[Bill Traynor (wmat)]

​Everything is at top of tree now, so you should be able to build and view.

[Maanvi212006]

Hi Bill Traynor (@wmat)! Good news — the alt text fix is working.

However I found that Read Aloud still skips the image even with the correct alt text when SVGs are base64 embedded. The only way to make it work is to disable :data-uri: for HTML builds.
I tried this and the SVGs are no longer base64. But there's a problem: when :data-uri: is disabled, the SVG files are generated in a temporary workdir and deleted after the build, so the HTML ends up with broken image links.

Two possible approaches:

1. Modify the Makefile WORKDIR_TEARDOWN to also copy the generated SVG files to the build folder
2. Keep :data-uri: but write a post-processor that replaces base64 SVGs with inline SVGs in the final HTML

Which approach would you prefer?

[Bill Traynor (wmat)]

I would suggest to try each solution and see which one works best. Note that you have to consider the PDF as well, not just the HTML.

[Maanvi212006]

Hi Bill Traynor (@wmat) , just an update!
HTML accessibility is now working. Here's what ended up working:

• Reverted :data-uri: to PDF-only (via ifdef::backend-pdf[]) so SVGs are linked as files in HTML builds
• Updated WORKDIR_TEARDOWN in the Makefile to copy generated SVGs to build/unpriv/images/ before the workdir is deleted
• Ran wavedrom_a11y.py across all .edn files in both unpriv and priv to populate meaningful alt= text
• Added post_process_html.py as a post-build script that wraps each SVG <img> in a <figure> with a visually hidden <figcaption> — this is what Read Aloud actually picks up and reads aloud

PDF accessibility is the next step

[Maanvi212006]

Hi Bill Traynor (@wmat)

PDF Accessibility — Investigation Summary

As a follow-up to the HTML fix, I investigated whether the same accessibility improvements could be applied to the PDF output. After tracing the full build pipeline, here is what I found.

What was investigated

The WaveDrom diagram pipeline for PDF follows the same path as HTML up to a point: .edn files → asciidoctor-diagram gem → SVG → handed to asciidoctor-pdf for embedding. The alt= text we updated in the .edn files does survive through asciidoctor-diagram — it is correctly set on the image block passed to asciidoctor-pdf.

The problem is what happens next.

Root cause

Inspecting the built riscv-spec.pdf directly reveals two things:

1. The PDF contains no StructTreeRoot and no MarkInfo — it is completely untagged. There is no accessibility tag tree at all, which means screen readers have no structured information to work with. They either skip content or read raw drawing instructions in paint order.

2. Image XObjects carry no filenames or identifiers — every diagram is stored as anonymous pixel data (/I1, /I2, etc.) with keys only for dimensions, encoding, and color space. There is no reference back to the source file or alt text.

A search through the entire asciidoctor-pdf 2.3.24 source found no code for writing tagged PDF structures, StructTreeRoot, or /Alt entries on images. The only alt-text-related code in the codebase is an on_image_error handler that renders alt text as visible fallback text when an image file fails to load — this is unrelated to screen reader accessibility.

What this means

Injecting /Alt entries via post-processing would have no effect without a tag tree — screen readers only look for /Alt inside tagged structure elements. Building a full tag tree as a post-processing step would require re-describing the entire document structure (headings, paragraphs, figures, tables) from scratch, which is effectively reimplementing what asciidoctor-pdf should do natively.

Recommendation

Tagged PDF output is not currently supported by asciidoctor-pdf 2.3.24. This is an upstream limitation outside the scope of what can be fixed in this repository. I would suggest:

• Opening a separate tracking issue for PDF accessibility, noting the upstream dependency
• Raising this with the asciidoctor-pdf project as a feature request for tagged PDF / PDF/UA support

The HTML fix in this PR remains fully working and addresses the accessibility need for the primary format most users interact with online.