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
- 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.
- Installa Pandoc seguendo le istruzioni del sito ufficiale.
- Converti il file. Apri il terminale nella cartella del documento ed esegui il comando riportato qui sotto, dove
input.texè il file di partenza eoutput.htmlquello che verrà creato. - Apri il risultato nel browser. Le versioni recenti di Chrome, Edge, Firefox e Safari mostrano il MathML senza bisogno di altro.
- 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
- Manuale di Pandoc (in inglese)
- MathJax (in inglese)
- Trasformare documenti LaTeX o Markdown in HTML accessibile, la variante con MathJax
- Tutte le guide di Università Inclusiva
