Benvenuti a questa seconda parte, che riassumono i problemi incontrati per creare un libro con molte formule matematiche. La prima parte, con le scelte di partenza, la trovate qui:
Quindi, riassumo i punti ottenuti:
- abbandonato in questo caso LaTeX, non per problemi non risolvibili, ma perché le piattaforme di pubblicazione (e gli utenti) preferiscono il formato ePUB, per i lettori tipo Kindle e altri, mentre i pdf, anche se più belli a vedersi, sono statici, non potendosi adattare a una finestra qualunque;
- il passaggio da LaTeX ad ePUB non è una trasformazione così semplice e può convenire, anche se con un certo lavoro, a chi ha già una certa mole di roba scritta in LaTeX;
- ho scelto Quarto, un software basato sul markdown, che accetta le formule in LaTeX; l'uscita può avvenire in contemporanea in più formati dagli stessi file;
- le formule vengono trasformate in ePUB (html) usando mathml e questo soddisfa le richieste di Apple Books; ma con altri reader più datati, bisogna sostituirle con immagini SVG;
- a quanto sembra, solo passando da LaTeX si possono ottenere gli SVG, ma non voglio un'intera installazione LaTeX solo per quello, per cui andiamo su un contenitore docker, che contiene tutto il necessario.
Il contenitore
Partiamo col costruire un file chiamato dockerfile che crei una macchina minimale contenente le parti necessarie di LaTeX, per le nostre formule; evitiamo la TeXLive completa, inserendo quello che potrebbe servire. Parto da un Ubuntu:
Ora introduciamo le sezione di LateX che supponiamo utili (possiamo fidarci di quanto ci fornisce il package manager di Ubuntu):
Una volta che tutto funzionerà, si potrà provare a togliere qualcosa, per ottenere l'installazione minima. Però mancano ancora due pezzi: il primo è dvisvgm che è il nucleo della trasformazione in SVG e poi gladtex, un pre-processore che fa il passaggio intermedio, evidenziando con il tag <eq> le formule da trasformare e poi le sostituisce con le immagini tornate. Entrambi sono disponibili dal package manager, per cui alla fine il nostro dockerfile è
La configurazione
La costruzione del container è stata la parte più semplice. Ora però dobbiamo riprendere i file markdown e metterli assieme usando la configurazione del libro, che per Quarto significa costruire il file _quarto.yml (la sottolineatura iniziale è voluta):
Questa parte indica che si tratta di un libro, con il suo titolo, autore, copertina, ecc... Bisogna notare che il file .yml prevede che ogni rientro sia esattamente di 2 spazi e che non vuole i tabulatori.
Segue poi la struttura del libro, suddiviso in capitoli e, volendo, anche parti (la faccio semplice):
dove la parola chiave chapter è al livello di language: it.
Ora c'è il bello di Quarto: dopo la parola chiave format: possiamo inserire informazioni relativi ai formati che vogliamo in uscita; l'uscita html è utile per avere un preview rapido praticamente identico all'ePUB (che, abbiamo detto, è in sostanza un html):
Il formato html è utile per avere un aggiornamento a colpo d'occhio; in VS Code è possibile tenerlo aperto affiancato al file che sto modificando e si aggiorna ogni volta che viene salvato il file. Se volessimo mostrare il libro su un sito apposito, non dobbiamo preoccuparci dei comandi html: l'uscita è completa di tutto, anche del javascript per l'indice, i passaggi da una sezione all'altra e persino per la ricerca all'interno del sito. Stiamo usando il formato Mathml per le formule perché riconosciuto normalmente da tutti i browser moderni; il più comodo MathJax, che accetterebbe direttamente il LaTeX, avrebbe bisogno di una libreria aggiuntiva.
Potremmo anche volere in uscita un pdf, dove la chiave (al posto di html) è typst: come detto nella prima parte, typst può creare un pdf da solo, usando però un linguaggio diverso da LaTeX, ma pandoc si occupa di tutto. Un pdf può essere utile quando vogliamo rileggere il documento, inserendo annotazioni, sottolineature e altro (sul computer o su un tablet un pdf è più semplice da annotare); è possibile inserire in questo formato anche un eventuale file di preambolo. Ma andiamo a quello che ci serve: passiamo al formato ePUB per i lettori tipo Apple Books o che comunque supportano la matematica con Mathml nativo:
Ho inserito gli stessi comandi di prima, così html e ePUB dovrebbero essere molto simili e mi basta vedere il primo mentre scrivo. Questa uscita porta ad un ePUB che, su un Mac, è facilmente controllabile caricandolo su Apple Book oppure su Calibre. Come scritto nella configurazione, ci affidiamo alle formule trasformate da Quarto (in realtà è pandoc a farlo) in formato Mathml e l'e-reader, basandosi su un motore web (WebKit per Apple Books), ci mostra le formule con un buon risultato visivo.
Ora passiamo invece al formato che dobbiamo usare per poter essere letti anche su Kindle piuttosto vecchi, cioè usando immagini SVG delle formule; definiamo un formato apposito, che chiamo epub+kindle cominciando ad inserire i soliti dati comuni:
Ho aggiunto le ultime tre righe commentate perché sono quelle consigliate un po' dappertutto, che però non raggiungono il risultato: in pratica, dicono di non usare alcun metodo per le formule e passare l'argomento --gladtex a pandoc, quando viene chiamato da Quarto. In realtà, questo argomento non fa eseguire gladtex: si limita a racchiudere le formule in tag XML del tipo <eq env="math"> o <eq env="displaymath">, a seconda che si tratti di una formula all'interno di una riga di testo o sia una formula centrata sulla propria riga; tutto questo viene inserito nell'output html, lasciando la compilazione vera e propria ad un successivo passaggio.
In teoria, dovremmo ora fare una chiamata al compilatore LaTeX per ogni formula, che tramite dvisvgm ci ritorna la figura in SVG, da richiamare nel codice html. Chiaro che non possiamo farlo a mano per ogni formula! Ecco allora che useremo un filtro scritto in Lua che faccia tutto quello che serve da solo e per tutte le formule. Quindi aggiungiamo la chiamata al filtro nel file di configurazione di Quarto e inseriamo alcune cose utili per tutti i formati:
Ma non voglio far diventare troppo lungo questo post: il finale alla prossima puntata, in cui vedremo il filtro da applicare e come chiamare la macchina dentro il contenitore docker, facendogli compilare la formula e trasformandola in SVG.
Alla prossima!