Accessibility with Figures

[cderv]

I opening this so share our work and findings regarding the difficulty to support alt text in Figures in several format because of Pandoc handling in some formats.

This is how Figure is parsed currently

❯ pandoc -t native
![look a puffin](https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg "Title: A proper puffin")
^Z
[Para [Image ("",[],[]) [Str "look",Space,Str "a",Space,Str "puffin"] ("https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg","fig:Title: A proper puffin")]]

And this is not used the same depending on the output formant

HTML 4

See that no alt text is set

❯ pandoc -t html4
![look a puffin](https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg "Title: A proper puffin")
^Z
<div class="figure">
<img src="https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg" title="Title: A proper puffin" alt="" />
<p class="caption">look a puffin</p>
</div>

• link text in brackets is used as caption
• Text after the link as title

You could try set attribute explicitly

❯ pandoc -t html4
![look a puffin](https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg "Title: A proper puffin"){alt="This is an alt text"}
^Z
<div class="figure">
<img src="https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg" title="Title: A proper puffin" alt="This is an alt text" alt="" />
<p class="caption">look a puffin</p>
</div>

but you'll get the attribute twice - not great.

HTML 5

❯ pandoc -t html5
![look a puffin](https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg "Title: A proper puffin")
^Z
<figure>
<img src="https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg" title="Title: A proper puffin" alt="look a puffin" /><figcaption aria-hidden="true">look a puffin</figcaption>
</figure>

• link text in brackets is also used as caption
• Text after the link as title
• link text used as caption is aslo used as alt text

LaTeX

❯ pandoc -t latex
![look a puffin](https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg "Title: A proper puffin")
^Z
\begin{figure}
\centering
\includegraphics{https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg}
\caption{look a puffin}
\end{figure}

Word and PPTX

This is not quite good

In word

![look a puffin](https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg "Title: A proper puffin")

Will lead to having

• link text in brackets is used as caption : "look a puffin"
• Both text used as alternative text description : the one in bracket and the one after link

  Title: A proper puffin
  
  look a puffin
  

See yihui/knitr#1965 (comment)

For PPTX, we'll get the link as alt text ! See rstudio/rmarkdown#2106

We try to fix this in R Markdown as we could (by bypassing Pandoc wirting raw ouput) but we do it for HTML4 output only currently. The other format still needs to be done: yihui/knitr#1967

Why this could be important for our project here ?

I think knowing this could help design a Figure type that clearly has or know how to deal with this.

This syntax could be a solution with the current system using link_attributes extension, if the attributes from HTML would be recognized and processed for other formats.

![look a puffin](https://upload.wikimedia.org/wikipedia/commons/9/94/Puffin_Mrkoww.jpg "Title: A proper puffin"){alt="My alt text"}

@apreshill I wrote this after looking more at your different research and comments in our issues to centralize in this project in case in can help.

[cderv]

Also, first reported in Pandoc in jgm#6782 with more details on how it should be handled

[argent0]

These inconsistencies seem to arise from the different interpretations that different writers do of the internal representation.

I believe that, in the best case, the alt text should be explicitly provided in the input (for the case of markdown) and perhaps capture it as an Attr in the Image constructor.

This is the current native representation:

$ stack run pandoc -- -t native
![caption](url "Title"){alt = "alt description"} 
[Para 
   [ Image 
        ("",[],[])
        [Str "caption"]
        ("url","Title"),
        Str "{alt",Space,Str "=",Space,Quoted DoubleQuote [Str "alt",Space,Str "description"],Str "}"]]

I think the last should be instead (Not the actual output)

$ stack run pandoc -- -t native
![caption](url "Title"){alt = "alt description"} 
[Para 
   [ Image 
        ("",[],[("alt", "alt description"])
        [Str "caption"]
        ("url","Title") ]]

Perhaps there is also an issue with the markdown reader.

[tarleb]

There must not be any spaces between the attribute name and its value, so this would work:

![caption](url "title"){alt="the description"}

[cderv]

oh yes it is a typo in my last example in the post above. In the example for HTML4 it is correct. Sorry for the misdirection. Post edited .

❯ pandoc -t native
![caption](url "Title"){alt="alt description"}
^Z
[Para [Image ("",[],[("alt","alt description")]) [Str "caption"] ("url","fig:Title")]]

[argent0]

@cderv , Do you think the aria-hidden="true" should be removed in this case? Since caption is different from alt.

$ pandoc -f markdown -t html
![caption](../media/rId25.jpg "title"){alt="alt"}

<figure>
<img src="../media/rId25.jpg" title="title" alt="alt" /><figcaption aria-hidden="true">caption</figcaption>
</figure>

[apreshill]

What about:

<div role="figure" aria-labelledby="caption">
  <img src="image.png"
      alt="full alternative image description">
  <p id="caption">Figure 1: The caption</p>
</div>

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Figure_Role

[cderv]

In your link, I read this :

Instead of using ARIA to create a figure, consider using the native, semantic HTML

element. along with the element. See Best practices below.

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Roles/Figure_Role#best_practices

With HTML 5 <figure> element, best practice seem to be this

<figure>
  <img src="diagram.png"
       alt="diagram showing the four layers of awesome and their relative priority order —
       music, cats, nature, and ice cream">
  <pre><code>
    let awesome = ['music', 'cats', 'nature', 'ice cream'];
  </code></pre>
  <figcaption>Figure 1: The four layers of awesome.</figcaption>
</figure>

What you share above should probably be what we should do in HTML4 document where <figure> is not available

[apreshill]

Yes I am reading that now- the more semantic version doesn't seem to need aria at all: https://www.hassellinclusion.com/blog/figure-figcaption-extended-alternate-text-screen-readers/

[apreshill]

However, at the bottom of this article they find:

Summary

There was no evidence of any linkage between the image and the <figcaption> without the use of of aria-labelledby or aria-describedby – which of course could reference any other text elements other than the <figcaption>.

[argent0]

Authors MAY, with caution, use aria-hidden to hide visibly rendered content from assistive technologies only if the act of hiding this content is intended to improve the experience for users of assistive technologies by removing redundant or extraneous content. Authors using aria-hidden to hide visible content from screen readers MUST ensure that identical or equivalent meaning and functionality is exposed to assistive technologies.

from the recommendation.

Can be understood to support the removal of aria-hidden=true since when the alt differs from the caption, they won't have "identical or equivalent meaning and functionality".