Hybrid PDF 2.0 UA-2 math/alt/use or Hybrid PDF 1.7 UA-1 math/setup=mathml-AF ?

[alexanderperlis]

A colleague asked me about improving Ally scores with math/alt/use. I hadn't heard of this. A web search for latex tagging "math/alt/use" does indeed reveal help pages at various institutions combining pdfstandard=ua-2 with math/alt/use, but
the LaTeX Tagging Project usage instructions do not currently mention math/alt/use.

It seems with math/alt/use one could produce a potentially conformant PDF 2.0 UA-2 that—in addition to the required MathML—includes the math alt text previously required by PDF 1.7 UA-1. Such a document would then be potentially readable by older assistive technology (AT) that understands alt text but does not understand MathML. Since the alt text is less structured compared to MathML, any newer AT that understands both ought to ignore the alt text (at least certainly ought to do so for a document claiming conformance to UA-2), but I suppose there could exist buggy AT that understands MathML yet erroneously prefers alt text over MathML.

Question: Is it a violation of any PDF standard to claim conformance to PDF 2.0 UA-2 (and to validate as such) yet to also embed math alt text along with the MathML?

In other words, is it okay to create a hybrid that is PDF 2.0 UA-2 yet in some sense is also backwards compatible with PDF 1.7 UA-1? The PDF Association guide on conforming to PDF/UA states “PDF 2.0 documents must not [state conformance to] UA-1” but also “PDF 2.0 documents may use PDF 1.7 standard structure tag sets”, whatever that means precisely but loosely speaking it could mean “PDF 2.0 is allowed to include extra stuff that used to be required under older standards”.

Question: Are there any standards for how MathML-capable AT should behave by default (perhaps overridable by user settings) when a document contains both math alt text and MathML? For a document claiming conformance to UA-1 I could imagine it might be okay for AT to prefer math alt text, but for a document claiming conformance to UA-2 I feel AT should prefer MathML.

I understand it might not be good practice in certain situations to create a hybrid PDF, for example if you're targeting a specific AT as part of an accommodation for a specific user and you know their specific AT would do better with a pure PDF 2.0 UA-2 (only MathML, no alt text) or with a pure PDF 1.7 UA-1 (only math alt text, no MathML). But for general document creation for general consumption, it seems there might be several possibilities to consider, listed next.

Four types of potentially accessible PDF

Pure PDF 1.7 UA-1 (only math alt text, no MathML, no TeX-AF)

• Seems achievable in TeX Live 2026 with pdfversion=1.7, pdfstandard=ua-1, tagging-setup={math/setup={}}.

• Avoid this document type—math alt text doesn't have the rich structure of MathML.

• Note that pdfstandard=ua-1 alone leads to an error about downgrading from 2.0 to 1.7, while pdfversion=1.7, pdfstandard=ua-1 avoids the error yet leads to a hybrid PDF 1.7 UA-1 that has the required math alt text but also has TeX-AF. Is the inclusion of TeX-AF even allowed in PDF 1.7 UA-1? pdf4wcag 1.6.1 validated the result as UA-1, but the tagpdf documentation (v0.99z, §3.2.8 Math) seems to indicate MathML-SE can go into PDF 1.7 but MathML-AF and TeX-AF can go only into PDF 2.0.

Hybrid PDF 1.7 UA-1 (both math alt text and MathML, also TeX-AF)

• Seems achievable in TeX Live 2026 with pdfversion=1.7, pdfstandard=ua-1, tagging-setup={math/setup={mathml-AF,tex-AF}}.

• Note that I had to specify mathml-AF, not mathml-SE, otherwise pdf4wcag 1.6.1 reports UA-1 validation errors…

Pure PDF 2.0 UA-2 (only MathML, no math alt text, no TeX-AF)

• Seems achievable in TeX Live 2026 with pdfstandard=ua-2, tagging-setup={math/setup={mathml-SE}}.

• Note that pdfstandard=ua-2 alone results in a PDF 2.0 with TeX-AF but no MathML (specifying pdfstandard=ua-2, tagging-setup={math/setup={}} also removes the TeX-AF). There's no MathML, yet the document claims conformance to UA-2 and pdf4wcag 1.6.1 even validates it as UA-2. I'm confused. Does UA-2 require MathML for math content?

Hybrid PDF 2.0 UA-2 (both MathML and math alt text, also TeX-AF)

• Seems achievable in TeX Live 2026 with pdfstandard=ua-2, tagging-setup={math/setup={mathml-SE,tex-AF},math/alt/use}.

Which to use?

At this moment in time (early 2026), I imagine various embedded older AT (such as Ally embedded into various LMS platforms) does not know MathML, thus math alt text is necessary to satisfy the older AT, yet document authors might also want to include MathML for users who might open the document in different current or future AT. This then leaves two possible targets:

• Hybrid PDF 1.7 UA-1 (both math alt text and MathML, also TeX-AF)
• Hybrid PDF 2.0 UA-2 (both MathML and math alt text, also TeX-AF)

Question: In my naïve descriptions here, these both seem to have the same stuff in them, and I believe either is able to represent content that meets WCAG 2.2, so is one better than the other, more capable in some way than the other? I ask this both from the practical perspective of current AT, but also from the more objective perspective of potential future AT, whether the Hybrid 2.0 is merely a different underlying format—the file looks different in a hex editor and contains cool claims like “UA-2” and “WTPDF” that don't exist in PDF 1.7—or actually contains additional AT-related content that could in principle allow (future) AT to do useful things it simply could never possibly do with the Hybrid 1.7?

[u-fischer]

You are not violating a standard if you add an alt text. But currently I do not know of any PDF reader which will ignore the alt and prefer the mathml. So to make a drastic example: If you add the alt in the following example users will hear something like "LaTeX formula start blub LaTeX formula end".

\DocumentMetadata
  {
    lang=en-US,
    pdfversion=2.0,
    pdfstandard=ua-2,
    tagging=on,
    tagging-setup={math/setup=mathml-SE,math/alt/use}
  }
\newcommand\blub{\sqrt{x^2}}
\documentclass{article}
\begin{document}
$\blub$
\end{document}

Are there any standards for how MathML-capable AT should behave by default

No not yet. But this has been discussed in various TWG/LWG of the pdf association and there is agreement that mathml-SE should win over mathml-AF and both should win over the alt text. But when implementation will actually do that is unknown.

Which to use?

If you want the best experience for the (blind) user of the PDF use PDF 2.0 and mathml-SE and nothing else. If you only want to improve your score use also math/alt/use. Take then at least care that the math does not contain commands like the \blub above.

Note: TeX-AF (which embed the tex source as associated file) is used by no-one yet, it is irrelevant if you use it or not.

[alexanderperlis]

The \blub example aptly demonstrates the potential for LaTeX source to bewilder, both for auto-generated math alt text and for auto-generated TeX-AF. But even auto-generated MathML can't know whether the \sqrt inside \blub should be “square root” or “nilradical”. To compensate for poorly chosen macros and overloaded math symbols, an author could specify custom alt text (not sure how an author would specify custom TeX-AF), but it would be more prudent for an author to choose intent-conveying macro names, and also to specify MathML intent in the macro definition:

\newcommand{\parallelto}{\MathMLintent{is parallel to}\parallel}
\newcommand{\exactlydivides}{\MathMLintent{exactly divides}\parallel}
In synthetic geometry, $m \parallelto n$; in elementary number theory, $9 \exactlydivides 45$.

This approach seems to lead to reasonable outcomes with math alt text, with TeX-AF, and with MathML. By including both math alt text and MathML, today's AT that only knows math alt text or mistakenly prefers it over MathML will still provide an acceptable experience, while future AT that knows and prefers MathML will provide a superb experience. By this reasoning it seems that enabling math alt text at this moment in time (early 2026) is not just about improving Ally scores but also about ensuring the document is accessible both with current AT and with future AT. Am I misunderstanding the situation?

My other questions:

• Is a PDF 1.7 UA-1 allowed (by PDF standards) to include AF? LaTeX happily (somehow) inserts MathML-AF, and Vera (pdf4wcag) does not complain.
• Is a PDF 1.7 UA-1 allowed (by PDF standards) to include SE? LaTeX happily (somehow) inserts MathML-SE, but Vera doesn't like the result. Is this perhaps a Vera bug?
• Is a PDF 2.0 UA-2 required to have MathML for math content? LaTeX lets me make a document with math content but no MathML that (falsely?) claims UA-2, and Vera curiously agrees it is valid UA-2. Is this perhaps a Vera bug?
• I understand MathML-SE is superior to MathML-AF in the sense that the various individual bits of MathML-SE are coupled to the individual displayed glyphs whereas the entire MathML-AF just sits as a separate blob at the start of the formula. On the other hand, a document author can control the MathML-AF by editing <file>-mathml.html, but doing so did not seem to affect the MathML-SE. Is there a way for document authors to control the MathML-SE?

[u-fischer]

Am I misunderstanding the situation?

As I wrote: if you add an alt-text you are currently breaking the MathML for every user.

If there is no Alt-text then quite a lot reader (e.g. adobe reader) will happily forward the mathml-SE inside the Formula even if they have no idea what mathml is, and the screen reader/AT have a chance to process the mathml-SE. As soon as there is an Alt-text all readers currently will drop all structure elements inside the Formula and only forward the alt. So no one sees the MathML.

Do not do it!

• Is a PDF 1.7 UA-1 allowed (by PDF standards) to include AF? LaTeX happily (somehow) inserts MathML-AF, and Vera (pdf4wcag) does not complain.

Yes, associated files are allowed.

• Is a PDF 1.7 UA-1 allowed (by PDF standards) to include SE? LaTeX happily (somehow) inserts MathML-SE, but Vera doesn't like the result. Is this perhaps a Vera bug?

Yes, but as mathml is not a predeclared name space in PDF 1.7 you must rolemap all mathml-SE e.g. to Span and AT will only see these Span and no mathml. Not that it matters much: as UA-1 requires an Alt on the formula, the math is lost anyway.

• Is a PDF 2.0 UA-2 required to have MathML for math content? LaTeX lets me make a document with math content but no MathML that (falsely?) claims UA-2, and Vera curiously agrees it is valid UA-2. Is this perhaps a Vera bug?

Yes, you need either mathml-SE or mathml-AF. And yes, LaTeX allows to produce invalid documents, see the documentation of the pdfstandard key in documentmetadata-support.pdf and l3pdfmeta.pdf:

Note that using these keys doesn’t mean that the document actually follows the standard. LaTeX can neither ensure nor check all requirements of a standard, and not everything it can do theoretically has already been implemented.

And yes, no validator catches everything. Lots of requirements from PDF/UA are human checks. And you have to check if they are fullfiled.

• I understand MathML-SE is superior to MathML-AF in the sense that the various individual bits of MathML-SE are coupled to the individual displayed glyphs whereas the entire MathML-AF just sits as a separate blob at the start of the formula. On the other hand, a document author can control the MathML-AF by editing <file>-mathml.html, but doing so did not seem to affect the MathML-SE. Is there a way for document authors to control the MathML-SE?

Theoretically yes, practically it needs currently lots of skills and good knowledge of lua.