Alt-text for math equations in Typst

[mcanouil]

PDF UA-1 accessibility standard requires math equations (cross-references) to have alternative text.
Typst (> 0.14) supports this with alt of math.equation() but currently cannot be set.

• quarto-cli/src/resources/filters/crossref/equations.lua

  Lines 56 to 63 in c7b25ea

  	elseif _quarto.format.isTypstOutput() then
  	local is_block = eq.mathtype == "DisplayMath" and "true" or "false"
  	targetInlines:insert(pandoc.RawInline("typst",
  	"#math.equation(block: " .. is_block .. ", numbering: \"(1)\", " ..
  	"[ "))
  	targetInlines:insert(eq)
  	targetInlines:insert(pandoc.RawInline("typst", " ])<" .. label .. ">"))
  	else

Expected:

---
format:
  typst:
    keep-typ: true
---

$$
E = mc^2
$$

$$
E = mc^2
$$ {#eq-einstein alt="Einstein's mass-energy equivalence formula"}

...

$ E = m c^2 $

#math.equation(block: true, alt: "Einstein's mass-energy equivalence formula", numbering: "(1)", [ $ E = m c^2 $ ])<eq-einstein>

[mcanouil]

This is actually less trivial than anticipated.

Equations labels are "strings" which would lead to a nightmare (still doable) of a regex to handle:

$$
E = mc^2
$$ {#eq-einstein alt="Einstein's mass-energy equivalence formula"}

I wonder, the div syntax could be used, note that it is actually not supported at all for equations:

::: {#eq-einstein alt="Einstein's mass-energy equivalence formula"}
$$
E = mc^2
$$
:::

[mcanouil]

Adding a Div handler in the equations.lua could allow to use the div syntax and easily get alt-text for equations.

Below is a standalone code to be integrated, but the internals should be shared to reduce code duplication.

-- Process equation divs with alt-text support for Typst accessibility
function process_equation_div(divEl)
  -- Check if this is an equation div (identifier starts with eq-)
  local label = divEl.attr.identifier
  if not label or not label:match("^eq%-") then
    return nil
  end

  -- Find the display math inside the div
  local eq = nil
  _quarto.ast.walk(divEl, {
    Math = function(el)
      if el.mathtype == "DisplayMath" then
        eq = el
      end
    end
  })

  if not eq then
    return nil
  end

  -- Add to the index
  local order = indexNextOrder("eq")
  indexAddEntry(label, nil, order)

  -- Get alt attribute for Typst accessibility
  local alt = divEl.attr.attributes["alt"]

  -- Generate output based on format
  if _quarto.format.isLatexOutput() then
    return pandoc.Para({
      pandoc.RawInline("latex", "\\begin{equation}"),
      pandoc.Span(pandoc.RawInline("latex", eq.text), pandoc.Attr(label)),
      pandoc.RawInline("latex", "\\end{equation}")
    })
  elseif _quarto.format.isTypstOutput() then
    local is_block = "true"
    local alt_param = ""
    if alt then
      alt_param = ", alt: \"" .. alt .. "\""
    end
    return pandoc.Para({
      pandoc.RawInline("typst",
        "#math.equation(block: " .. is_block .. ", numbering: \"(1)\"" .. alt_param .. ", [ "),
      eq,
      pandoc.RawInline("typst", " ])<" .. label .. ">")
    })
  else
    local eqNumber = eqQquad
    local mathMethod = param("html-math-method", nil)
    if type(mathMethod) == "table" and mathMethod["method"] then
      mathMethod = mathMethod["method"]
    end
    if _quarto.format.isHtmlOutput() and (mathMethod == "mathjax" or mathMethod == "katex") then
      eqNumber = eqTag
    end
    eq.text = eq.text .. " " .. eqNumber(inlinesToString(numberOption("eq", order)))
    return pandoc.Para({pandoc.Span(eq, pandoc.Attr(label))})
  end
end

[mcanouil]

I have something but it won't work on CI/CD before Typst 0.14 is embedded.

[mcanouil]

Ongoing PR:

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