HTML writer: improve alt-text/caption handling for HTML5

Screen readers read an image's `alt` attribute and the figure caption,
both of which come from the same source in pandoc. The figure caption is
hidden from screen readers with the `aria-hidden` attribute. This
improves accessibility.

For HTML4, where `aria-hidden` is not allowed, pandoc still uses an
empty `alt` attribute to avoid duplicate contents.

Closes: #6491

6 files changed, 17 insertions, 9 deletions

diff --git a/src/Text/Pandoc/Writers/HTML.hs b/src/Text/Pandoc/Writers/HTML.hs
index 11daaf06b..4bfd95674 100644
--- a/src/Text/Pandoc/Writers/HTML.hs
+++ b/src/Text/Pandoc/Writers/HTML.hs
@@ -1,6 +1,7 @@
 {-# LANGUAGE MultiWayIf          #-}
 {-# LANGUAGE OverloadedStrings   #-}
 {-# LANGUAGE ScopedTypeVariables #-}
+{-# LANGUAGE TypeApplications    #-}
 {-# LANGUAGE ViewPatterns        #-}
 {- |
    Module      : Text.Pandoc.Writers.HTML
@@ -587,11 +588,18 @@ figure :: PandocMonad m
        => WriterOptions -> Attr -> [Inline] -> (Text, Text)
        -> StateT WriterState m Html
 figure opts attr txt (s,tit) = do
-  img <- inlineToHtml opts (Image attr [Str ""] (s,tit))
   html5 <- gets stHtml5
+  -- Screen-readers will normally read the @alt@ text and the figure; we
+  -- want to avoid them reading the same text twice. With HTML5 we can
+  -- use aria-hidden for the caption; with HTML4, we use an empty
+  -- alt-text instead.
+  let alt = if html5 then txt else [Str ""]
   let tocapt = if html5
-                  then H5.figcaption
+                  then H5.figcaption !
+                       H5.customAttribute (textTag "aria-hidden")
+                                          (toValue @Text "true")
                   else H.p ! A.class_ "caption"
+  img <- inlineToHtml opts (Image attr alt (s,tit))
   capt <- if null txt
              then return mempty
              else tocapt `fmap` inlineListToHtml opts txt
diff --git a/test/command/3577.md b/test/command/3577.md
index d1df1610d..2f415146d 100644
--- a/test/command/3577.md
+++ b/test/command/3577.md
@@ -16,10 +16,10 @@
 \end{figure}
 ^D
 <figure>
-<img src="img1.jpg" alt="" /><figcaption>Caption 1</figcaption>
+<img src="img1.jpg" alt="Caption 1" /><figcaption aria-hidden="true">Caption 1</figcaption>
 </figure>
 <figure>
-<img src="img2.jpg" alt="" /><figcaption>Caption 2</figcaption>
+<img src="img2.jpg" alt="Caption 2" /><figcaption aria-hidden="true">Caption 2</figcaption>
 </figure>
 ```
 ```
@@ -30,6 +30,6 @@
 \end{figure}
 ^D
 <figure>
-<img src="img1.jpg" alt="" /><figcaption>Caption 3</figcaption>
+<img src="img1.jpg" alt="Caption 3" /><figcaption aria-hidden="true">Caption 3</figcaption>
 </figure>
 ```
diff --git a/test/command/4677.md b/test/command/4677.md
index 482db4c02..2694624b9 100644
--- a/test/command/4677.md
+++ b/test/command/4677.md
@@ -3,6 +3,6 @@
 ![Caption](img.png){#img:1}
 ^D
 <figure>
-<img src="img.png" id="img:1" alt="" /><figcaption>Caption</figcaption>
+<img src="img.png" id="img:1" alt="Caption" /><figcaption aria-hidden="true">Caption</figcaption>
 </figure>
 ```
diff --git a/test/command/5121.md b/test/command/5121.md
index 42f2fdea2..419b8b9f4 100644
--- a/test/command/5121.md
+++ b/test/command/5121.md
@@ -5,7 +5,7 @@
 ## Header 2
 ^D
 <figure>
-<img src="./my-figure.jpg" width="500" alt="" /><figcaption>My caption</figcaption>
+<img src="./my-figure.jpg" width="500" alt="My caption" /><figcaption aria-hidden="true">My caption</figcaption>
 </figure>
 
 Header 2
diff --git a/test/command/5642.md b/test/command/5642.md
index 7fe8f5a5f..cd60df812 100644
--- a/test/command/5642.md
+++ b/test/command/5642.md
@@ -3,6 +3,6 @@
 ![test](foo){aria-describedby="barbaz"}
 ^D
 <figure>
-<img src="foo" aria-describedby="barbaz" alt="" /><figcaption>test</figcaption>
+<img src="foo" aria-describedby="barbaz" alt="test" /><figcaption aria-hidden="true">test</figcaption>
 </figure>
 ```
diff --git a/test/writer.html5 b/test/writer.html5
index 321b65afd..0f0db799e 100644
--- a/test/writer.html5
+++ b/test/writer.html5
@@ -523,7 +523,7 @@ Blah
 <h1 id="images">Images</h1>
 <p>From “Voyage dans la Lune” by Georges Melies (1902):</p>
 <figure>
-<img src="lalune.jpg" title="Voyage dans la Lune" alt="" /><figcaption>lalune</figcaption>
+<img src="lalune.jpg" title="Voyage dans la Lune" alt="lalune" /><figcaption aria-hidden="true">lalune</figcaption>
 </figure>
 <p>Here is a movie <img src="movie.jpg" alt="movie" /> icon.</p>
 <hr />