Re: Support alt text in LaTeX output

--0000000000002f140d065774c1d7
Content-Type: text/plain; charset="UTF-8"

On Sat, 25 Jul 2026 at 17:19, Patrice Dumas <[email protected]> wrote:

> On Sat, Jul 25, 2026 at 02:08:47PM +0100, David Carlisle wrote:
> > Not sure if you want to document this, or perhaps only for your own
> > information, if alt was passed through the following would be enough to
> > generate tagged pdf usable for a screen reader
> >
> > texi2any --latex -I . -o asymptote.tex asymptote.texi
> >
> > to get asymptote.tex then run lualatex through a file say
> > asymptote-tagged.tex that contains just
> >
> >
> > \DocumentMetadata{tagging=on,
> >   pdfstandard=UA-2
> > }
> > \AtBeginDocument{\hypersetup{pdftitle=asymptote manual}}
> > \RequirePackage{unicode-math}
> > \input{asymptote}
>
> We could output that kind of code based on a customization variable too.
>

Ok I leave the architecture for the texi2any interface to you.

There are other options, I showed the simplest default DocumentMetadata,
that produces PDF 2.0 with PDF/UA-2  accessibility standard.

You could however have

\DocumentMetadata{tagging=on,
  pdfstandard={UA-2,A-4f},
  tagging-setup={math/setup=mathml-SE}
}

which also asserts conformance to the PDF/A (long term archival) standard
as well as UA-2
and uses MathML Structure elements rather than MathML Associated files for
Math. That last
ought to be an implementation detail of the internal pdf encoding but some
systems support one better than the other.

despite being a standard for almost a decade PDF 2 isn't universally
supported so some people may want to make PDF 1.7 (and its PDF/UA-1
standard which is not as good especially for mathematical documents) but

\DocumentMetadata{
pdfversion=1.7,
pdfstandard=ua-1
}

which is why I thought perhaps you wouldn't want to generate this and just
tell people what they need to do,  but as I say
that is up to you, it probably helps if you can generate the main PDF2,
PDF/UA-2 declaration.




similarly in the main generated preamble it's generating

\documentclass{book}

I'd typically want

\documentclass[a4paper]{book}

to get A4 paper size

(perhaps you already have that configuration, sorry it's been a while (er
30 years I think) since I really used texinfo:-)







> Should \usepackage{unicode-math} replace \usepackage{amsmath} or should
> it be there in addition?


unicode-math internally inputs amsmath first, changes things for unicode
then prevents it being re-loaded
so technically the document can have both in either order  and it's
equivalent to just having unicode-math
but just having one or the other is perhaps clearer.


And is \usepackage{amsfonts} needed/useful if
> \usepackage{unicode-math} is in the header?
>

No not needed and not useful (but not uncommon of course when updating
documents so unicode-math can cope)


>
> > If texinfo has the document title to hand it could probably add that by
> > default as well but as you see if it doesn't it's not too bad I just need
> > AtBeginDocument here so the setting is delayed until hyperref package is
> > loaded.
>
> We should add it by default, as we have ways to get a title that should
> make sense, using @settitle or other possibilities as we do for HTML
> output.
>
>
That would be good



> We cannot know if there are characters that would be problematic, both
> in alt= for images and in the pdftitle=.  Which characters should be
> escaped and how?  Is that described somewhere that could be used for all
> the graphicx/hyperref options?
>

the pdftitle and  alt text in includegraphics in the end have to be a PDF
encoded string with no markup, so
over the years latex has got better at "cleaning up text" basically now any
unicode text should work, the only characters that you need to quote are %
{ }  as for instance

\includegraphics[alt={something about % increase}]{some image}

would comment out everything after the % unless you use \% but that is
nothing specific to this key it is general tex syntax.

Note the {} used here as in alt={...}  are not normally required but allow
[ and ] to be used without closing the overall [] optional argument.

\includegraphics[alt=text with ], width=3cm]{image}

will not parse correctly

\includegraphics[alt={text with ]}, width=3cm]{image}

"hides" the ] so it does not terminate the argument.

The current code also makes a "best attempt" to make a plain text string if
there is latex markup such as font changes that can be silently ignored,
but that will fail if you push it too far, best to document that these
should be plain text (especially as you'll want the same texinfo source to
cleanly convert to html alt attributes with overlapping requirements)



> --
> Pat
>

David

--0000000000002f140d065774c1d7
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><div><br></div><div><br></div><div><br></=
div></div><br><div class=3D"gmail_quote gmail_quote_container"><div dir=3D"=
ltr" class=3D"gmail_attr">On Sat, 25 Jul 2026 at 17:19, Patrice Dumas &lt;<=
a href=3D"mailto:[email protected]">[email protected]</a>&gt; wrote:<br></div=
><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border=
-left:1px solid rgb(204,204,204);padding-left:1ex">On Sat, Jul 25, 2026 at =
02:08:47PM +0100, David Carlisle wrote:<br>
&gt; Not sure if you want to document this, or perhaps only for your own<br=
>
&gt; information, if alt was passed through the following would be enough t=
o<br>
&gt; generate tagged pdf usable for a screen reader<br>
&gt; <br>
&gt; texi2any --latex -I . -o asymptote.tex asymptote.texi<br>
&gt; <br>
&gt; to get asymptote.tex then run lualatex through a file say<br>
&gt; asymptote-tagged.tex that contains just<br>
&gt; <br>
&gt; <br>
&gt; \DocumentMetadata{tagging=3Don,<br>
&gt;=C2=A0 =C2=A0pdfstandard=3DUA-2<br>
&gt; }<br>
&gt; \AtBeginDocument{\hypersetup{pdftitle=3Dasymptote manual}}<br>
&gt; \RequirePackage{unicode-math}<br>
&gt; \input{asymptote}<br>
<br>
We could output that kind of code based on a customization variable too.<br=
></blockquote><div><br></div><div><div></div><div>Ok I leave the=C2=A0archi=
tecture for the texi2any interface to you.</div><div><br></div><div>There a=
re other options, I showed the simplest default DocumentMetadata, that prod=
uces PDF 2.0 with PDF/UA-2=C2=A0 accessibility=C2=A0standard.</div><div><br=
></div><div>You could however have</div><div><br></div><div>\DocumentMetada=
ta{tagging=3Don,<br>=C2=A0 pdfstandard=3D{UA-2,A-4f},<br>=C2=A0 tagging-set=
up=3D{math/setup=3Dmathml-SE}<br>}<br><br></div><div>which also asserts con=
formance to the PDF/A (long term archival) standard as well as UA-2</div><d=
iv>and uses MathML Structure elements rather than MathML Associated files f=
or Math. That last</div><div>ought to be an implementation detail of the in=
ternal pdf encoding but some systems support one better than the=C2=A0other=
.</div><div><br></div><div>despite being a standard for almost a decade PDF=
 2 isn&#39;t universally supported so some people may want to make PDF 1.7 =
(and its PDF/UA-1 standard which is not as good especially for mathematical=
 documents) but</div><div><br></div><div>\DocumentMetadata{</div><div>pdfve=
rsion=3D1.7,</div><div>pdfstandard=3Dua-1</div><div>}</div><div><br></div><=
div>which is why I thought perhaps you wouldn&#39;t want to generate this a=
nd just tell people=C2=A0what they need to do,=C2=A0 but as I say=C2=A0</di=
v><div>that is up to you, it probably helps if you can generate the main PD=
F2, PDF/UA-2 declaration.</div><div><br></div><div><br></div><div><br></div=
><div><br></div><div>similarly=C2=A0in the main generated preamble it&#39;s=
 generating=C2=A0</div><div><br></div><div>\documentclass{book}</div><div><=
br></div><div>I&#39;d typically want</div><div><br></div><div>\documentclas=
s[a4paper]{book}</div><div><br></div><div>to get A4 paper size</div><div><b=
r></div><div>(perhaps you already have that configuration, sorry it&#39;s b=
een a while (er 30 years I think) since I really used texinfo:-)</div><div>=
<br></div><div><br></div><div><br></div><div></div><br></div><div><br></div=
><div>=C2=A0</div><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px=
 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
Should \usepackage{unicode-math} replace \usepackage{amsmath} or should<br>
it be there in addition?=C2=A0</blockquote><div><br></div><div>unicode-math=
 internally inputs amsmath first, changes things=C2=A0for unicode then prev=
ents it being re-loaded</div><div>so technically the document can have both=
 in either order=C2=A0 and it&#39;s equivalent to just having unicode-math<=
/div><div>but just having one or the other is perhaps clearer.</div><div><b=
r></div><div><br></div><blockquote class=3D"gmail_quote" style=3D"margin:0p=
x 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"> A=
nd is \usepackage{amsfonts} needed/useful if<br>
\usepackage{unicode-math} is in the header? <br></blockquote><div><br></div=
><div>No not needed and not useful (but not uncommon of course when updatin=
g documents so unicode-math can cope)</div><div>=C2=A0</div><blockquote cla=
ss=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid =
rgb(204,204,204);padding-left:1ex">
<br>
&gt; If texinfo has the document title to hand it could probably add that b=
y<br>
&gt; default as well but as you see if it doesn&#39;t it&#39;s not too bad =
I just need<br>
&gt; AtBeginDocument here so the setting is delayed until hyperref package =
is<br>
&gt; loaded.<br>
<br>
We should add it by default, as we have ways to get a title that should<br>
make sense, using @settitle or other possibilities as we do for HTML<br>
output.<br>
<br></blockquote><div><br></div><div>That would be good</div><div><br></div=
><div>=C2=A0</div><blockquote class=3D"gmail_quote" style=3D"margin:0px 0px=
 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex">
We cannot know if there are characters that would be problematic, both<br>
in alt=3D for images and in the pdftitle=3D.=C2=A0 Which characters should =
be<br>
escaped and how?=C2=A0 Is that described somewhere that could be used for a=
ll<br>
the graphicx/hyperref options?<br></blockquote><div><br></div><div>the pdft=
itle=C2=A0and=C2=A0 alt text in includegraphics in the end have to be a PDF=
 encoded string with no markup, so=C2=A0</div><div>over the years latex has=
 got better at &quot;cleaning up text&quot; basically now any unicode=C2=A0=
text should work, the only characters that you need to quote are % { }=C2=
=A0 as for instance=C2=A0</div><div><br></div><div>\includegraphics[alt=3D{=
something about % increase}]{some image}</div><div><br></div><div>would com=
ment out everything after the % unless you use \% but that is nothing speci=
fic to this key it is general tex syntax.</div><div><br></div><div>Note the=
 {} used here as in alt=3D{...}=C2=A0 are not normally required but allow [=
 and ] to be used without closing the overall=C2=A0[] optional=C2=A0argumen=
t.</div><div><br></div><div>\includegraphics[alt=3Dtext with ], width=3D3cm=
]{image}</div><div><br></div><div>will not parse correctly=C2=A0</div><div>=
<br></div><div>
\includegraphics[alt=3D{text with ]}, width=3D3cm]{image}</div><div><br></d=
iv><div>&quot;hides&quot; the ] so it does not terminate the argument.</div=
><div><br></div><div>The current code also makes a &quot;best attempt&quot;=
 to make a plain text string if there is latex markup such as font changes =
that can be silently ignored, but that will fail if you push it too far, be=
st to document that these should be plain text (especially=C2=A0as you&#39;=
ll want the same texinfo source to cleanly convert to html alt attributes w=
ith overlapping requirements)</div><div><br></div><div><br></div><blockquot=
e class=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px s=
olid rgb(204,204,204);padding-left:1ex">
<br>
-- <br>
Pat<br></blockquote><div><br></div><div>David=C2=A0</div></div></div>

--0000000000002f140d065774c1d7--