feat(equations): add alt-text and div syntax for equations

[mcanouil]

Important

For the Typst tests to pass on CI/CD, Typst >= 0.14 is required.

Implement alt-text functionality for math equations to comply with the PDF UA-1 accessibility standard.

This enhancement allows users to specify alternative text for equations using the alt attribute in Typst 0.14 and above.

This PR also adds support for the div-syntax.

$$
E = mc^2
$$ {#eq-einstein}

::: {#eq-einstein}

$$
E = mc^2
$$

:::

$$
E = mc^2
$$ {#eq-einstein alt="Einsteins mass-energy equivalence equation"}

::: {#eq-einstein alt="Einsteins mass-energy equivalence equation"}

$$
E = mc^2
$$

:::

Additionally, refactor the code to reduce duplication (brought by div processing).

Fixes #13870

[posit-snyk-bot]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scanner	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.

[mcanouil]

Because to trigger the use of math.equation a cross-reference is required, it means alt can be added only when a cross-reference.
It's possible to allow to set alt text independently of the cross-reference, if deemed appropriate.

[cderv]

For the Typst tests to pass on CI/CD, Typst >= 0.14 is required.

Does this mean it requires #13249?

You could make this PR against that branch, that way we'll benefit the updated version. and we'll be sure to merge after.

[mcanouil]

Done

[mcanouil]

The PR is a bit noisy because it contains commits from main not in the new base branch.

[cderv]

Thanks a lot !

I reviewed with mostly some questions because this PR touches functions in Lua that are used for all crossref.

So it is indeed adding support for Typst, but we should verify the side effect for other cases and formats where the function are used - possibly by adding more tests than equations as all crossref will be impacted.

Also, if we do add support for alt in equation for typst, do we need to try add support for other format ? usually when we add a feature we try to cover all formats, so I am wondering.

At least we'll need a companion Documentation PR that explains the limitations.

• Either we document alt= in equation syntax only in Typst page: https://quarto.org/docs/output-formats/typst.html
• Either we document new alt support in generic markdown: https://quarto.org/docs/authoring/cross-references.html#equations but in that case it will need a callout for "Typst only" feature.

So maybe former is better.

Again, thanks for the feature!

[cderv]

This comes from a commit we already merged on main.
We'll sort out while merging to keep PR scoped and clean.

[cderv]

Same for this test folder. We'll remove from this PR before merging to get clean PR as it does not belong to this one.

[mcanouil]

Also, if we do add support for alt in equation for typst, do we need to try add support for other format ? usually when we add a feature we try to cover all formats, so I am wondering.

Briefly, I don't believe LaTeX/OpenXML care about this and if there is even a way. I did not take a deep look at those, so I might have missed something.
For HTML, it's usually the math library that is responsible of accessibility and it's not really doable to do something unless the team officially choose one library to support over the others.
Typst on the other hand has the right tooling and it is actually making us do it. Using math.equation() without alternative text is not possible if one wants to be compliant with UA-1.

For the context, I was playing around with my template when I hit those issues, instead of making myself a Lua workaround, I started this PR as it's mandatory for UA-1.

---

Thanks for the review and comments about other functions/tools defined elsewhere in the codebase.
I'll check and revise.

[cderv]

Also, if we do add support for alt in equation for typst, do we need to try add support for other format ? usually when we add a feature we try to cover all formats, so I am wondering.

Briefly, I don't believe LaTeX/OpenXML care about this and if there is even a way. I did not take a deep look at those, so I might have missed something. For HTML, it's usually the math library that is responsible of accessibility and it's not really doable to do something unless the team officially choose one library to support over the others. Typst on the other hand has the right tooling and it is actually making us do it. Using math.equation() without alternative text is not possible if one wants to be compliant with UA-1.

Ok it makes sense, so maybe this something to document only at Typst doc level as an exception, and be sure that we don't impact other format with this.

For LaTeX, I am aware of the following package for accessibility (https://ctan.org/pkg/axessibility), but I have never tried it. Just overall with the new accessibility requirement, maybe there is something with new standard that we don't know yet about.

For HTML, yes this is the library, but we do know which one is used html-math-method. So it is our job to pass the information the right way for those method if they support alt text. Do you see what I mean?
That is why I am wondering what we can do (and maybe it is pandoc as we rely on Pandoc writer for the equation rendering I think - which we don't for Typst).

[mcanouil]

For HTML, yes this is the library, but we do know which one is used html-math-method. So it is our job to pass the information the right way for those method if they support alt text. Do you see what I mean?
That is why I am wondering what we can do (and maybe it is pandoc as we rely on Pandoc writer for the equation rendering I think - which we don't for Typst).

I meant, I'm not aware of them using alternative text, for example MathJax https://docs.mathjax.org/en/latest/basic/accessibility.html

[mcanouil]

@cderv I'll refocus this PR and open a separate feature request for the div syntax.
This will simplify this PR and "address" your concerns.