A11y expression of diagrams

[merchako]

The Diagrams are helpful (example: Characters). Thank you!

Problem

• not A11y accessible
• not searchable
• not CTRL+F-able
• not linked

Suggested solution

1. Add a Code view to let us see the UML markup (or whatever's behind the diagram) and/or
2. Add a key-value section modeled after the Technical Summary in MDN

[mhosken]

The images are SVG or PNG can;t remember which. If I gave you an SVG could you mark it up as an exemplar for a11y? See https://github.com/usfm-bible/tcdocs/tree/main/markers/images/schema for source. These files are auto-generated from the grammar so we might be able insert stuff.

…

On Thu, 29 Aug 2024, 09:02 Alex Mercado, ***@***.***> wrote: The Diagrams are helpful. Thank you! Problem - not A11y accessible - not searchable - not CTRL+F-able - not linked Suggested solution 1. Add a Code view to let us see the UML markup (or whatever's behind the diagram) and/or 2. Add a key-value section modeled after the Technical Summary in MDN <https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span#technical_summary> — Reply to this email directly, view it on GitHub <#2>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/ABLMO3M7HTAPXBI3226XXRLZTZ6M5AVCNFSM6AAAAABNJNM64GVHI2DSMVQWIX3LMV43ASLTON2WKOZSGQ4TGMRZGQ2TCOA> . You are receiving this because you are subscribed to this thread.Message ID: ***@***.***>

[merchako]

Thank you for your prompt reply. I want to make sure I understand you to be the most helpful. Do I have this right?:

• When you ask for "an exemplar for a11y", you'd like me to convert one diagram to HTML markup so you can understand what good output would look like if you were to generate more for other diagrams.

Correct?

Could I get a link to the grammar from which these diagrams are derived? That might be helpful. I'm also going to poke around the internet to see if other people have solved this problem before. For all I know, there's already a standard way to represent grammars for accessibility.

[merchako]

My first thought is to grab a human readable markup language and express them in that. I'm currently exploring

• Mermaid is what Platform is using. This StackExchange thread recommends Mermaid.
• Obsidan's [JSON Canvas]

[mhosken]

The source basis for all the syntax diagrams is: (https://github.com/usfm-bible/tcdocs/blob/main/grammar/usx.rnc) some rather complex tooling creates syntax diagrams for selected definitions in that grammar, direct to SVG. I notice from the StackExchange thread that mentions SVG as a good target format, and that the thread is primarily about accessible content creators rather than how to create accessible content.
Which returns me to my original question: given an svg file like (https://github.com/usfm-bible/tcdocs/blob/main/markers/images/schema/f_rail.svg) what needs to be added to the file to make it accessible?
I'm not asking for tooling, I'm asking for specifications, and engineering details. We won't be retooling for this job it is too complex. You would be welcome to try.

[merchako]

Thank you for the additional information, @mhosken . I'm working on getting you an exemplar and comprehensive list of changes that would fulfill this request. In the meantime, one sure improvement is a combination of
(1) link every element's label to that element's page (using xlink)
(2) ensure the SVG lightbox allows uses to notice and click on the links.

Untested pseudocode

- <text x="495.0" y="541">Figure</text>
+ <a xlink:href="https://docs.usfm.bible/usfm/latest/fig/fig.html"><text x="495.0" y="541">Figure</text></a>

(Aside: ideally, the link would go around the containing box, but I'm not confident enough to put the correct SVG elements in this example.)

More to come after the Paratext Summit. Thank you!

[mhosken]

This issue is blocked by this bug in antora: https://gitlab.com/antora/antora/-/issues/1001 unless someone can think of a way around it.