search

usfm-bible / docs.usfm.bible

Antora playbook project for the USFM / USX end-user documentation site.
0 stars 0 forks source link

A11y expression of diagrams #2

Open merchako opened 2 months ago

merchako commented 2 months ago

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

Problem

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 commented 2 months ago

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 https://github.com/usfm-bible/docs.usfm.bible/issues/2, or unsubscribe https://github.com/notifications/unsubscribe-auth/ABLMO3M7HTAPXBI3226XXRLZTZ6M5AVCNFSM6AAAAABNJNM64GVHI2DSMVQWIX3LMV43ASLTON2WKOZSGQ4TGMRZGQ2TCOA . You are receiving this because you are subscribed to this thread.Message ID: @.***>

merchako commented 2 months ago

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

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 commented 1 month ago

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

mhosken commented 1 month ago

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 commented 1 month ago

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 commented 1 month ago

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.