Trasformare documenti LaTeX o Markdown in HTML accessibile

Questa guida mostra come ottenere, da un documento scritto in LaTeX o in Markdown, una pagina web in cui le formule sono disegnate da MathJax e restano leggibili con lo screen reader e con la barra Braille.

Gli strumenti

  • LaTeX, il linguaggio con cui si scrivono i documenti scientifici.
  • Markdown, un linguaggio più leggero, in cui le formule si scrivono con la stessa sintassi di LaTeX.
  • Pandoc, il programma gratuito che converte l’uno e l’altro in HTML.
  • MathJax, la libreria che mostra le formule nella pagina e le rende disponibili alle tecnologie assistive.

Che cosa ti serve

  • Un editor di testo, per esempio Visual Studio Code o il Blocco note.
  • Un browser aggiornato.
  • Una conoscenza di base di LaTeX o di Markdown: per LaTeX c’è la guida alla scrittura di formule.

La conversione

  1. Installa Pandoc dal sito ufficiale, seguendo le istruzioni per il tuo sistema operativo.
  2. Prepara il file. In LaTeX usa i comandi standard per le formule. In Markdown scrivi le formule fra dollari, come nell’esempio qui sotto.
  3. Esegui il comando dal terminale, nella cartella in cui si trova il file.

Un esempio di testo in Markdown, con una formula nella riga e una in evidenza:

Questa è una formula nel testo: $E = mc^2$.

Questa è una formula in evidenza:

$$
\int_0^\infty e^{-x} \, dx = 1
$$

Il comando per un file LaTeX:

pandoc -s --mathjax -o output.html input.tex

Il comando per un file Markdown:

pandoc -s --mathjax -o output.html input.md

In tutti e due i casi Pandoc crea una pagina HTML completa, che contiene già la riga con cui viene caricato MathJax.

Configurare MathJax per l’accessibilità

Apri il file HTML con l’editor e, dentro l’elemento <head>, inserisci questo blocco prima della riga che carica MathJax:

<script>
window.MathJax = {
  tex: { inlineMath: [['\\(','\\)']], displayMath: [['\\[','\\]']] },
  options: {
    menuOptions: {
      settings: {
        assistiveMml: true,
        explorer: true
      }
    },
    sre: { locale: 'it' }
  }
};
</script>

Con assistiveMml ogni formula è accompagnata da una versione in MathML, nascosta alla vista, che è quella letta dallo screen reader e mandata alla barra Braille. Con explorer si può entrare nella formula e percorrerla un pezzo alla volta con i tasti freccia. La riga sre: { locale: 'it' } chiede che la lettura a voce segua le regole dell’italiano.

Verifica il risultato

  • Con uno screen reader: NVDA è gratuito per Windows, VoiceOver è già presente su Mac e iPhone.
  • Con WAVE, che controlla la struttura della pagina, i testi alternativi e i contrasti.

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.