Add overview diagram

[yamdan]

I've added the overview diagram at the beginning of Section 4.
I initially considered placing it in Section 4.4 where the Issue Marker originally was, but it might cause confusion with the immediate steps 1-6 in 4.4.1.
If more information is needed for accessibility in the alt text, please let me know.

I have added @iherman as a reviewer for this PR, because he reviewed the previous version of this diagram on the Google slides.

Fixes #98.

Edit: we can preview it here on GitHack (thanks @gkellogg)

---

Preview | Diff

[iherman]

@yamdan, unfortunately, the preview tool fails on externally reference content, so the figure does not appear in it. To make it worse, I cannot even access the content by trying to click on the SVG access in the preview.

I could, of course, download the branch to my local machine and view it here, and I am happy to do it, but I wonder whether you have the picture available on-line somewhere to make the review easier for everyone...

[yamdan]

@iherman Sorry, I pasted the diagram on the top of this PR.

[gkellogg]

Best thing for viewing the spec with included files is GitHack. See this link.

The image is quite useful, and this is a good location for it. I added some suggestion on wording.

[yamdan]

Thanks @gkellogg for your information and suggestions.
I added the GitHack link to the top of this PR.

[iherman]

Hi @yamdan, this is really useful. Some suggestions on the diagram as possible improvements...

• To be consistent, it should be <…/knows> and <…/name> everywhere. To the uninitiated, the diagram makes you believe that the URLs disappear in the abstract RDF (which is not the case). I realize it is not easy to add this to the diagram… (maybe by using two lines of entries in the abstract RDF boxes, reflecting the n-Quads?)

• I wonder whether it is not better, although it makes the diagram a bit more complex, to use an RDF graph that also includes a non-blank node as an object or subject. This should then be reflected by two different types of nodes (or different style of labels) in the graph, making it clear that the regular nodes go through the process unchanged. Again, I realize it makes the diagram a bit larger and more complex, but may be better for the messaging…

[iherman]

I do have a problem in terms of accessibility, though.

From an Accessibility point of view, we should add a more detailed alternate description to the figure in the HTML code. The paragraph serving as "described-by" does not really tell anything about the diagram, meaning that it does not make the diagram palatable for a low vision reader.

I realize it is more work, and it is also not clear how to put it into the code without distorting the text. As an example for a possible solution, you can look at what we did in the EPUB Overview Note, which has a separate “Image description” field underneath the image itself. The corresponding HTML structure is as follows:

<img src="images/epub.svg" width="600" 
   aria-details="fig-epub-structure-diagram" 
   alt="Visual structure of the main constituents of an EPUB publication" />

<details id="fig-epub-structure-diagram" class="desc">
	<summary style="font-weight: normal; font-style: italic">Image description</summary>
	<p>
           'EPUB (OCF) container' as the outer most component which encapsulates the 'EPUB publication'
	  containing two documents 'Publication Document' and 'EPUB navigation document' along with a
	  inner component labelled 'publication resources' which contains multiple 'EPUB content
	  documents' (XHTML, SVG), and multiple 'Other resources' (CSS, png, mp3, mov, etc.).
       </p>
</details>

I am not saying you have to follow exactly the same structure, but something along those lines would be good to have.

cc @gkellogg

[dlongley]

Thanks, @yamdan, this is really useful!

My only other comment is that I can't read it on my default browser that uses "Dark mode for web contents" (chrome://flags/#enable-force-dark), but I don't know if that's easily resolved (I don't have any recommendations for how to address it). It looks fine if I open it in a browser without that setting.

[yamdan]

I've updated the diagram, which is now expected to be readable even in dark mode (could you please check it again, @dlongley)
and cover the first two comments from @iherman.
Later, I will add more alt texts to make its accessibility better.

[iherman]

and cover the first two comments from @iherman.

Thanks for those changes, @yamdan. The diagram looks great, thank you for it!

[dlongley]

@yamdan,

I've updated the diagram, which is now expected to be readable even in dark mode (could you please check it again, @dlongley)

Yes, I can read it easily now, thank you!

[gkellogg]

I think we can put a fuller explanation of the diagram within the image object tag to satisfy accessibility requirements.

[gkellogg]

Suggested change

	<p id="fig-ca-overview-alt">
	The image represents an overview of the <a>RDFC-1.0</a> algorithm.</p>
	<p id="fig-ca-overview-alt">
	The image represents an overview of the <a>RDFC-1.0</a> algorithm.
	The Input Document is deserialized into the Input Dataset
	and Input Blank Node Identifier Map.
	Canonicalization steps 1-6 are executed resulting in
	the Canonicalized Dataset including the
	Input Blank Node Identifier Map and Issued Identifiers Map.
	Step 7 of the Canonicalization algorithm creates
	the canonical n-quads form of the Canonicalized Dataset.</p>

[iherman]

The question is the visibility. I presume you rely on setting the ...overview-alt with the visibility turned off, and rely on screen readers or other tools to retrieve the alt text for the case when it is needed. However, this may not be optimal; I do not remember from the top of my head but, unless you use display:none, the alt description affects the overall formatting. On the other hands, some screen readers may skip over texts with alt text (I may be wrong with that). We did an internal a11y review with our spec in EPUB (we had several persons in the group with low vision) and the preference went to the approach based on details.

Another approach that was taken in other specs is to gather all the image description to an appendix, and use aria to link to those.

[gkellogg]

I believe that because the element in inside an object, it does not appear for readers not using alternative screen readers, but is available for those unable to see the picture. Keeping it inside the object element satisfies the accessibility requirements without cluttering the presentation.

In JSON-LD, we did place alternate text in an appendix with a reference from the image, which is certainly acceptable, but I don't believe is required.

[yamdan]

Thank you @gkellogg for adding the alt text!
There's still some debate about how to display these, but I believe there's no problem with the text itself, so I have reflected your suggestion in the PR.

[yamdan]

The current method, as @gkellogg mentioned, embeds the alt text within the object element, and since they are not rendered when the SVG image is displayed, I don't believe they unnecessarily reduce readability.
Also, since the alt text is referred to by aria-describedby, I expect it to be properly read out by screen readers that support WAI-ARIA... However, to be honest, I'm not very familiar with the behavior of ARIA or screen readers, so I can't be fully confident here.

[iherman]

Ok. I am o.k. leaving it as is; at some point we may get another WAI review (getting close to PR) and we may come back to this then.

[iherman]

@yamdan can you tell me how you solved #152 (comment) ? As far as I can see your figure is done by google draw, so it is maybe a trick in the latter...

I have a similar issue with a diagram I prepared (see w3c/vc-data-integrity#171 (comment)) and, to be honest, I am not sure how to solve this.

Thx.

[yamdan]

@iherman What I did here was to avoid adding a background color (FFFFFF) to the shapes as much as possible, and instead used a transparent color.
In dark mode, the browser automatically turns text to white, so if there's a white-ish background color shape, the text on it becomes invisible. This issue can be avoided by using transparent background. I used Google Slides as a drawing tool, but I believe we can achieve the same result with other tools.
However if there's a need to use a fancy or white-ish background color in a diagram, another trick might be required to edit the SVG's CSS to change the text color based on the mode, but I haven't tried this.

[iherman]

Thanks @yamdan. I am afraid I will have to reengineer my drawing, removing the background colors. I tried some CSS setting, but it did not really work.

Actually, avoiding colors is a good idea for other purposes as well, like people having Dalton problems.