diff --git a/CHANGELOG.md b/CHANGELOG.md --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,3 +1,24 @@ +## 0.3.24 + +- Fix for #506 + + A prior fix/workaround for https://github.com/jgm/pandoc/issues/9720 had + unintentionally clobbered explicitly-specified `alt` attributes on images. + + Unfortunately, Pandoc does not expose `alt` attribute explicitly to filters, + instead it's only seen as image caption. So a simple heuristic is used: + if image caption does not match the figure caption, we assume it's an + explicitly-specified alt text and preserve it. Otherwise, clobber it. + +- `preserveAltText` option. As stated above, if `alt` is missing or matches the + figure caption, it will be clobbered, and figure caption will be generated + by Pandoc with `aria-hidden="true"`. When `preserveAltText` is set to `True`, + pandoc-crossref will preserve the alt text (be it explicit or implicit from + caption) verbatim, forcing Pandoc to produce both alt text and figure + caption in the output. The hope is this may prove useful in some workflows, + but you definitely should just specify alt text on all your images if you + care about screen readers at all. + ## 0.3.23 - Center subfigures in LaTeX diff --git a/docs/index.md b/docs/index.md --- a/docs/index.md +++ b/docs/index.md @@ -707,6 +707,14 @@ This option doesn't affect LaTeX output (which offloads numbering to the LaTeX engine). - `listOfMetadata`, default `false`. Enables setting `list-of-figures` &c variables to pass through to the Pandoc's templating engine. +- `preserveAltText`, default `false`. By default, if an image in a figure does not have an explicit + `alt` attribute, pandoc-crossref will assume it's only the figure caption, and not an `alt` + text. Pandoc will then produce a figure caption with `aria-hidden="true"` attribute and no `alt` + text on the image itself. Setting this flag to `true` will make pandoc-crossref preserve the + `alt` text (even if it is inferred from the figure caption) verbatim, which forces Pandoc to + generate an image with `alt` text and figure caption without `aria-hidden`. This is certainly + a half-measure at best, hence disabled by default, but may be better than nothing in certain + workflows. ### Item title format diff --git a/lib-internal/Text/Pandoc/CrossRef/References/Blocks/Subfigures.hs b/lib-internal/Text/Pandoc/CrossRef/References/Blocks/Subfigures.hs --- a/lib-internal/Text/Pandoc/CrossRef/References/Blocks/Subfigures.hs +++ b/lib-internal/Text/Pandoc/CrossRef/References/Blocks/Subfigures.hs @@ -227,10 +227,16 @@ let label' = normalizeLabel label let title = blocksToInlines [btitle] (attrs, content') = case blocksToInlines content of - [Image attr@(_, _, as) _ tgt] -> + [Image attr@(_, _, as) alt tgt] -> -- the second argument is a fix for -- https://github.com/jgm/pandoc/issues/9720 - (fattrs <> as, \capt -> [Plain [Image attr capt tgt]]) + let newContent + -- and this is a fix for https://github.com/lierdakil/pandoc-crossref/issues/506, + -- wherein we want to preserve alt if it's specified. Odd heuristic, but should + -- generally work... + | preserveAltText opts || title /= alt = const [Plain [Image attr alt tgt]] + | otherwise = \capt -> [Plain [Image attr capt tgt]] + in (fattrs <> as, newContent) _ -> (fattrs, const content) ref <- replaceAttr label' attrs title SPfxImg idxStr <- chapIndex ref diff --git a/lib-internal/Text/Pandoc/CrossRef/Util/Options.hs b/lib-internal/Text/Pandoc/CrossRef/Util/Options.hs --- a/lib-internal/Text/Pandoc/CrossRef/Util/Options.hs +++ b/lib-internal/Text/Pandoc/CrossRef/Util/Options.hs @@ -82,6 +82,7 @@ , setLabelAttribute :: Bool , equationNumberTeX :: Text , listOfMetadata :: Bool + , preserveAltText :: Bool } isLatexFormat :: Options -> Bool diff --git a/pandoc-crossref.cabal b/pandoc-crossref.cabal --- a/pandoc-crossref.cabal +++ b/pandoc-crossref.cabal @@ -1,11 +1,11 @@ cabal-version: 2.0 --- This file has been generated from package.yaml by hpack version 0.37.0. +-- This file has been generated from package.yaml by hpack version 0.38.1. -- -- see: https://github.com/sol/hpack name: pandoc-crossref -version: 0.3.23 +version: 0.3.24 synopsis: Pandoc filter for cross-references description: pandoc-crossref is a pandoc filter for numbering figures, equations, tables and cross-references to them. category: Text @@ -24,6 +24,9 @@ data-files: docs/demo/demo.md docs/index.md + test/m2m/altAttribute/expect.md + test/m2m/altAttribute/expect.tex + test/m2m/altAttribute/input.md test/m2m/chapDelim/expect.md test/m2m/chapDelim/expect.tex test/m2m/chapDelim/input.md @@ -175,7 +178,7 @@ , microlens >=0.4.12.0 && <0.5.0.0 , microlens-mtl >=0.2.0.1 && <0.3.0.0 , mtl >=1.1 && <2.4 - , pandoc >=3.8.2 && <3.9 + , pandoc >=3.8.2 && <3.10 , pandoc-crossref-internal , pandoc-types ==1.23.* , text >=1.2.2 && <2.2 @@ -229,7 +232,7 @@ , microlens-mtl >=0.2.0.1 && <0.3.0.0 , microlens-th >=0.4.3.10 && <0.5.0.0 , mtl >=1.1 && <2.4 - , pandoc >=3.8.2 && <3.9 + , pandoc >=3.8.2 && <3.10 , pandoc-types ==1.23.* , syb >=0.4 && <0.8 , template-haskell >=2.7.0.0 && <3.0.0.0 @@ -259,7 +262,7 @@ , gitrev >=1.3.1 && <1.4 , open-browser >=0.2 && <0.4 , optparse-applicative >=0.13 && <0.20 - , pandoc >=3.8.2 && <3.9 + , pandoc >=3.8.2 && <3.10 , pandoc-crossref , pandoc-types ==1.23.* , template-haskell >=2.7.0.0 && <3.0.0.0 @@ -289,7 +292,7 @@ , directory >=1 && <1.4 , filepath >=1.1 && <1.6 , hspec >=2.4.4 && <3 - , pandoc >=3.8.2 && <3.9 + , pandoc >=3.8.2 && <3.10 , pandoc-crossref , pandoc-types ==1.23.* , text >=1.2.2 && <2.2 @@ -325,7 +328,7 @@ , microlens >=0.4.12.0 && <0.5.0.0 , microlens-mtl >=0.2.0.1 && <0.3.0.0 , mtl >=1.1 && <2.4 - , pandoc >=3.8.2 && <3.9 + , pandoc >=3.8.2 && <3.10 , pandoc-crossref , pandoc-crossref-internal , pandoc-types ==1.23.* @@ -354,7 +357,7 @@ build-depends: base >=4.19 && <5 , criterion >=1.5.9.0 && <1.7 - , pandoc >=3.8.2 && <3.9 + , pandoc >=3.8.2 && <3.10 , pandoc-crossref , pandoc-types ==1.23.* , text >=1.2.2 && <2.2 diff --git a/test/m2m/altAttribute/expect.md b/test/m2m/altAttribute/expect.md new file mode 100644 --- /dev/null +++ b/test/m2m/altAttribute/expect.md @@ -0,0 +1,4 @@ +![Figure 1: A medium length description about sets +$\{\oplus ,\Phi ,\kappa \}$. See footnote for long +description\[\^1\]](./Slide1.PNG){#fig:one +alt="Problem 1 description of overlapping sets"} diff --git a/test/m2m/altAttribute/expect.tex b/test/m2m/altAttribute/expect.tex new file mode 100644 --- /dev/null +++ b/test/m2m/altAttribute/expect.tex @@ -0,0 +1,7 @@ +\begin{figure} +\centering +\pandocbounded{\includegraphics[keepaspectratio,alt={Problem 1 description of overlapping sets}]{./Slide1.PNG}} +\caption{A medium length description about sets +\(\{\oplus ,\Phi ,\kappa \}\). See footnote for long +description{[}\^{}1{]}}\label{fig:one} +\end{figure} diff --git a/test/m2m/altAttribute/input.md b/test/m2m/altAttribute/input.md new file mode 100644 --- /dev/null +++ b/test/m2m/altAttribute/input.md @@ -0,0 +1,1 @@ +![A medium length description about sets $\{\oplus ,\Phi ,\kappa \}$. See footnote for long description[^1]](./Slide1.PNG){#fig:one alt="Problem 1 description of overlapping sets"}