Mini guida: da LaTeX a HTML accessibile con MathML

Questa guida spiega come trasformare un documento LaTeX in una pagina HTML in cui le formule sono scritte in MathML, il linguaggio con cui il web descrive la matematica e che gli screen reader sanno leggere. Serve un solo programma gratuito, Pandoc.

I passaggi

  1. Prepara il documento. Controlla che il file LaTeX usi i comandi standard per titoli e formule, e che figure e tabelle abbiano una didascalia. Se devi ancora scriverlo, parti dalla guida alla scrittura di formule in LaTeX.
  2. Installa Pandoc seguendo le istruzioni del sito ufficiale.
  3. Converti il file. Apri il terminale nella cartella del documento ed esegui il comando riportato qui sotto, dove input.tex è il file di partenza e output.html quello che verrà creato.
  4. Apri il risultato nel browser. Le versioni recenti di Chrome, Edge, Firefox e Safari mostrano il MathML senza bisogno di altro.
  5. Verifica con uno screen reader. Controlla che le formule vengano lette come matematica e che ogni immagine abbia un testo alternativo.
pandoc -s --mathml -o output.html input.tex

L’opzione -s produce una pagina completa, con intestazione e titolo, e --mathml chiede di scrivere le formule in MathML.

Un esempio

Il documento di partenza, esempio.tex:

\documentclass{article}
\usepackage{amsmath}
\title{Esempio di documento}
\author{Autore}
\begin{document}
\maketitle
Questo è un esempio di formula: \(\varphi = \frac{1 + \sqrt{5}}{2}\)
\end{document}

Il comando:

pandoc -s --mathml -o esempio.html esempio.tex

La formula, nella pagina prodotta, diventa:

<math xmlns="http://www.w3.org/1998/Math/MathML">
  <mi>φ</mi>
  <mo>=</mo>
  <mfrac>
    <mrow>
      <mn>1</mn>
      <mo>+</mo>
      <msqrt><mn>5</mn></msqrt>
    </mrow>
    <mn>2</mn>
  </mfrac>
</math>

Come viene letta la formula

  • NVDA legge il MathML dopo aver installato il componente aggiuntivo MathCAT.
  • JAWS e VoiceOver leggono il MathML senza componenti aggiuntivi.

Se vuoi usare anche MathJax

MathJax è una libreria che disegna le formule allo stesso modo in tutti i browser e aggiunge un menu con funzioni di accessibilità. Non è indispensabile, ma se vuoi usarla aggiungi questa riga dentro l’elemento <head> della pagina:

<script id="MathJax-script" async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/mml-chtml.js"></script>

Le versioni precedenti di questa guida indicavano anche uno script caricato da polyfill.io. Va tolto dalle pagine in cui è rimasto: non serve più, e nel 2024 quel dominio è stato usato per distribuire codice malevolo.

Cura la struttura della pagina

Lo screen reader si muove nella pagina saltando da un titolo all’altro, da un elenco all’altro, da una tabella all’altra. Pandoc ricava questi elementi dal sorgente, e quindi una pagina ben strutturata nasce da un documento LaTeX in cui titoli, elenchi e tabelle sono scritti con i comandi previsti.

Risorse utili

Creative Commons License
Except where otherwise noted, the content on this site is licensed under a Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International License.