\includegraphics should have a way to set an alternative text

[sthibaul]

Hello,

Brief outline of the bug

For proper accessibility of pdf documents, images should have an alternative text, that screen readers can speak when going through the pdf document. The \includegraphics command should thus have some way to specify this text. On the web we can find some packages which allow to add a tag in the pdf, but they are rather hacks, and for instance pandoc can not catch the alternative text when converting e.g. to html, and just use a boilerplate "image" alternative instead. Adding support to \includegraphics would allow to have a standard way of setting the alternative text, and tools like pandoc etc. to be able to get it.

Minimal example showing the bug

\RequirePackage{latexbug}
\documentclass{article}
\usepackage{graphicx}

\begin{document}

% needs a way to set an alternate text for the image
\includegraphics{test.png}

\end{document}

[u-fischer]

We are aware that alternative descriptions are important.

The last time I tried it screen readers ignored the content of the /Alt key in a pdf if the document wasn't fully tagged. This means that a functional alternative text for the pdf output requires much more than adding simple key-val interface and something equivalent to accsupp to \includegraphics.

While pandoc will for html output need "only" an interface this shouldn't be done in an ad-hoc way: Alternative descriptions will be needed also in other places and the interface needs to scale and be well designed - regarding both the input methods and the escaping.

We are in the process of setting up a larger project to enable accessibility features in LaTeX (a first implementation to tag a pdf can be found in the tagpdf package) but it will need time and there will be no immediate solution.

[algeboy]

In the short term though, would it not make sense to make this option and have even a rudimentary version to iron out the basics?

For example, if I use tex4html then perhaps I would not have as much trouble getting the Alt text to work, and then as PDF accessibility improves the \includgraphics command's alt text would be set to already work with all necessary options having been explored in the medium term.

For now a hack way that works on many readers (importantly Acrobat), is to simply use pdfcomments with

\pdftooltip{\includegraphics{myimage.png}}{An amazing diagram of the empty set.}

so could be that \includegraphics could have modes like \usepackage[pdfcomment]{graphix} and another for HTML.

While none of this will pass full ADA compliance, I think tagging this as long-term is perhaps missing an opportunity to make this aspect of including images with metadata the default even if it does not fully deploy yet. In particular it is not only the latex technology stack that is behind on accessibility it is also the content creators who will need to start making or remaking content with the appropriate hooks, and those hooks very well could be issued in present day releases with admittedly limited effect but allowing for rapid buildup when the technology progresses.

[josephwright]

@algeboy 'Long-term' is used to mark issues that will not be closed shortly but which shouldn't causing nagging by the automated tools we use. We added an alt tag to \includegraphics some time ago, and this is used within the PDF tagging project. We do not want to make 'temporary' changes to stable LaTeX, as we (almost) never remove any functionality from the core. As such,alt tags are currently something that requires use of the test phase code, which is there exactly so we can iron out issues. Depending on your inputs, you can happily use the test phase; the alt key is stable so can be added to sources now in expectation of change.

[u-fischer]

@algeboy As Joseph wrote, the alt-key is already implemented and used by the tagging code and also by tex4ht. If you do something like

% \DocumentMetadata{testphase=phase-III} %for tagging
\documentclass{article}
\usepackage{graphicx}
\begin{document}
\includegraphics[alt=a yellow duck]{image.png}
\end{document}

then make4ht file will produce an html with <img alt='a yellow duck' src='image.png' />.

And pdflatex or lualatex a tagged PDF with a figure tag with an alternative text:

[davidcarlisle]

@algeboy

In the short term though, would it not make sense to make this option

As Ulrike just wrote, since this issue was opened the alt key has been added to \includegraphics in the default version. It's used by (at least) tex4ht and in html output and the latex tagging code in tagged pdf, and is available as data for any othr package that can use the text. So I think this issue can be closed as completed now.

[u-fischer]

For now a hack way that works on many readers (importantly Acrobat), is to simply use pdfcomments with

Sorry, we can not load pdfcomment in kernel code. There are too many dependencies to external packages (e.g. soul and xkeyval)

\pdftooltip{\includegraphics{myimage.png}}{An amazing diagram of the empty set.}

I agree, that works quite nicely in an untagged PDF (but not with active tagging, pdfcomment is not compatible) .
I could implement something with kernel code, but this would then require the PDF management and so \DocumentMetadata at the begin and so not work with legacy documents.

An external package could do something like the following. If tex4ht should be supported too, and additional test will be needed to suppress \pdftooltip and avoid to overwrite the tex4ht definition of the alt-key.

\documentclass{article}
\usepackage{graphicx}

\makeatletter
\IfDocumentMetadataTF{}
 {
  \usepackage{pdfcomment,patchcmd}
  \newcommand\tooltiptext{no text available!}
  \define@key{Gin}{alt}{\def\tooltiptext{#1}}
  \patchcmd\Gin@setfile{\box\z@}{\pdftooltip{\copy\z@}{\tooltiptext}}{}{\fail}
 } 
\makeatother 
\begin{document}

some text 

\includegraphics[alt=a yellow duck,width=10cm]{image.png}

\end{document}

[u-fischer]

@davidcarlisle it would perhaps make sense to store the alt value in some public variable always. Then packages like tex4ht (or that tagging code) to not need to redefine the key.

[davidcarlisle]

@u-fischer oh good idea, I'l make a PR \Gin@alt would be the graphicx name convention I guess or do you mean a more public no @ name?

[muzimuzhi]

I'l make a PR \Gin@alt would be the graphicx name convention I guess or do you mean a more public no @ name?

@davidcarlisle Chances to add documentation of alt option to grfguide.tex.

alt option was requested in #651 and implemented in #669, then shipped with LaTeX2e 2023-11-15.

[davidcarlisle]

@muzimuzhi oh certainly yes, it should have been added when I added the code, I'll add.

Something like this?

diff --git a/required/graphics/grfguide.tex b/required/graphics/grfguide.tex
index 585e87ad..5094f99a 100644
--- a/required/graphics/grfguide.tex
+++ b/required/graphics/grfguide.tex
@@ -62,7 +62,7 @@ stroke
 \begin{document}
 \title{Packages in the `graphics' bundle}
 \author{D. P. Carlisle \and The \LaTeX\ Project}
-\date{2021-03-05}
+\date{2024-01-01}

 \maketitle

@@ -617,6 +617,10 @@ The value should be one of
 Page of a multi-page PDF file. (by default the first page will be used.)
 \item[interpolate]\NEWfeature{2017/06/01}
 Enable/disable interpolation of bitmap images by the viewer.
+\item[alt]\NEWfeature{2021/09/16}
+  Alternative text for accessibility uses. By default this key is not used
+  but users are encouraged to add descriptive text here that may be used in
+  tagged PDF or as the |alt| attribute in conversions to HTML.
 \end{description}

 For the keys specifying the original size (i.e,, the bounding box,

[muzimuzhi]

@davidcarlisle If its documentation will be added along with public variable (assuming called \Gin@alt), then maybe document alt as sth like

+\item[alt]\NEWfeature{2021/09/16}
+  Specify alternative text for accessibility uses that may be used
+  in tagged PDF or as the |alt| attribute in conversions to HTML.
+  Users are encouraged to add descriptive text here.
+  The value is stored in \cs{Gin@alt}.

-\date{2021-03-05}
+\date{2024-01-01}

Also, 2024-02-01, not 01-01.

[davidcarlisle]

@muzimuzhi yes I wondered about that but I'm not sure it's clear yet if this should be \Gin@.. or as @u-fischer suggested something more generic that could be used as the alt text on other things. grfguide does not say anything about the implementation of any of the other keys, so I thought safer not to mention it. The macro is set in a local group of \includegraphics so it's not usable in anywhere that a typical reader of grfguide can access.

Oh yes it's february, thanks:-)

[muzimuzhi]

The macro is set in a local group of \includegraphics so it's not usable in anywhere that a typical reader of grfguide can access.

Ah I forgot the scope thing. So any package that wants to use the passed alternative text has to redefine some \includegraphics internal(s), e.g. example given in https://github.com/latex3/latex2e/issues/258#issuecomment-1918774917 patched \Gin@setfile.

[FrankMittelbach]

maybe a bad idea, but I mention it anyway: if you want to have a publicly available value in some variable, you could set it globally with the meaning "holds the last alt= value until overwritten. For most applications that should be good enough, shouldn't it? E.g. \lastaltvalue

[u-fischer]

so any package that wants to use the passed alternative text has to redefine some \includegraphics internal(s

maybe a bad idea, but I mention it anyway: if you want to have a publicly available value in some variable, you could set it globally with the meaning "holds the last alt= value until overwritten. For most applications that should be good enough, shouldn't it? E.g. \lastaltvalue

The current uses of the alt-value (tagging + html) need to redefine internals anyway to add the structure info. But I see no harm (and it could be useful) to store that globally, or at least let it "escape". Other similar values do that too: \@currentHref is fully global, and variables like \@currentlabel and \@currentlabelname are still valid after the command that set them.

I would suggest a name that fits into this set. The main question is if we want something only for the alt-text of graphic-like objects, or for all uses of an alt-key (so e.g. also for formulas)? Options could be \@currentimagealt or \@currentalt or \@currentalttext?

[davidcarlisle]

I'm not convinced it should be global really, it makes sense for \@currentlabel as it may be set in a section heading but has meaning for the following section. \currentHref less so.

I think really the alt value is internal data for the image inclusion. as @u-fischer says it is better integrated with the image tagging anyway. An externally visible value would allow a package to essentialy wrap it in a /Span with alttext but directly integrating it would be better. Any new backend (hint perhaps) that supports text on images has to define \Gin@include and use all the internal local data from the keys for filename, size, rotation,.. and having the alt text available without having to define the key makes that more consisitent, but all those other attributes are local.