search

w3c / did-core

W3C Decentralized Identifier Specification v1.0
https://www.w3.org/TR/did-core/
Other
407 stars 95 forks source link

Add detailed description for figures in Section C (Architectural Considerations) #771

Closed clehner closed 3 years ago

clehner commented 3 years ago

For #625

This adds descriptions for the five diagrams in Section C: figure id image
did-and-did-document-graph figure-a.1-did-and-did-document-graph.png
alsoKnownAs-graph figure-a.2-also-known-as-graph.png
controller-subject-equivalence figure-b.1-controller-and-subject-equivalence.png
independent-did-controllers figure-c.1-independent-did-controllers.png
group-did-controllers figure-c.2-group-did-controllers.png

These changes use the "longdesc" HTML attribute, which results, in Firefox on Debian Linux, in a context menu item "View Description" for the image: view-description

For better discoverability, and since I found no similar menu item in Chromium, I also add a link, "Text Description" for the respective images. Either clicking the link, or choosing the "View Description" menu item if present, navigates the browser to the fragment URL for the element containing the long description.

The long descriptions added here attempt to describe the image such that someone may recreate the image from the description with close to the same meaning. These long descriptions may therefore be considered redundant with the actual image, so I hid them by default to reduce clutter on the page. Using the "View Description" browser feature, clicking the "See also: Text Description" link, or otherwise navigating to a description's id fragment URL, causes the textual description to appear, and it is then highlighted to draw attention to it in that case:

longdesc

This PR adds similar long descriptions for the five diagrams in Section C. I thought these most needed it, while the remaining diagrams mostly capture the meaning in their alt text, although those could also have similar long descriptions added.

cc @peacekeeper

Preview | Diff

peacekeeper commented 3 years ago

Thanks @clehner looks good I think!

peacekeeper commented 3 years ago

Maybe convert this from "draft PR" to "ready for review PR"?

clehner commented 3 years ago

Added three more descriptions, to complete this set of five. Marked this PR ready for review.

I had to move the long description HTML elements outside their corresponding figure elements, because they are not supposed to be next to the figcaption element, and can't be in the figcaption element either - because the HTML generator wraps the figcaption contents in a span tag, while the descriptions are in a div. I thought having the long descriptions in the figure element might be better semantically - but at least there are still the a links in the figcaptions and the longdesc links pointing to them.

The markup validation in CI errors that the longdesc attribute is obsolete: https://github.com/w3c/did-core/pull/771/checks?check_run_id=2964931082 Should use of longdesc be removed? The "See also: Text Description" links would still work.

msporny commented 3 years ago

Editorial, multiple reviews, changes requested and made, no objections, merging.