Compilare un atto telematico in markdown con Pandoc
Negli scorsi articoli abbiamo visto come creare il nostro atto telematico avanzato usando markdown e LaTeX. In questo articolo vedremo come creare il PDF finale usando Pandoc.
4. Compilare con Pandoc
Ora che conosciamo i comandi principali per creare il nostro atto telematico avanzato non ci resta che scrivere e, poi, compilare il tutto utilizzando Pandoc.
Scriverò in futuro un articolo dettagliato su come installare Pandoc e LaTeX. Non mi dilungherò qui nel procedimento (che comunque non è particolarmente difficile). Il mio suggerimento personale è quello di installare Pandoc attraverso Homebrew e scaricare MacTeX (la versione completa - che pesa circa 3,2 Gb) da qui.
AGGIORNAMENTO: alla fine ho fatto un video … lo vedete qui sotto.
4.1 Aprire il terminale ed entrare nella cartella del documento
Installato il tutto dovete solo aprire il Terminale.
Finestra del Terminale
Se non volete avere a che fare con il Terminale ed avete acquistato > Keyboard Maestro> , in > questo articolo> trovate una macro per convertire automaticamente un file .md in PDF direttamente dal > Finder> .
Segnalo, perché me ne sono accorto mentre preparavo l’articolo, che la macro ha un > bug> per cui non carica correttamente le immagini nel PDF. Appena ho un attimo di tempo cercherò di risolvere il problema.
Una volta aperto il Terminale vi troverete nella cartella home del vostro utente. Personalmente vi consiglio caldamente di andare nella sotto-cartella in cui avete salvato il vostro file .MD (vedremo più avanti il perché, per ora fidatevi). Per fare ciò avete due modi, uno lungo e tedioso e l’altro veloce.
Il primo metodo è quello di cambiare cartella con il comando cd indicando il percorso completo della sotto-cartella da raggiungere, ad esempio:
cd documenti/test/
L’operazione diventa complessa se il vostro documento è in una cartella vari livelli sotto quella principale.
Il secondo metodo vi permette di evitare la digitazione di tutto il percorso. Per fare ciò aprite nel Finder la cartella in cui volete andare; e tenete a fianco il Terminale dove avrete già digitato il comando “cd” ed uno spazio vuoto, con il mouse andate sulla finestra del Finder sul simbolo della cartella in alto al centro della finestra, trascinate l’icona all’interno della cartella del Terminale. “Magicamente” comparirà l’intero percorso e voi non dovrete far altro che premere invio per spostarvi dentro la sotto-cartella.
Nella GIF animata che segue vedete i vari passaggi sopra descritti.
Come accedere rapidamente ad una sottocartella in Terminale
4.2 Il comando base di Pandoc
Per far convertire un documento da markdown in PDF il comando a terminale è relativamente semplice:
pandoc input.md -o output.pdf
Dove input.md va sostituito con il nome del vostro file in markdown che volete convertire in PDF e output.pdf va sostituito con il nome che vorrete dare al documento PDF finale.
4.3 Alcuni parametri utili: impostare la lingua italiana, abilitare la visualizzazione dei link
Ci sono molti parametri aggiuntivi per personalizzare in svariati modi la creazione del PDF finale di seguito tuttavia vi specifico quelli che per me sono essenziali.
pandoc input.md --pdf-engine=xelatex -V lang=it -V colorlinks -o output.pdf
Il parametro --pdf-engine=xelatex serve per utilizzare come motore di conversione quello di xelatex. Questa scelta rispetto al motore pre-impostato, pdflatex, deriva dal fatto che con xelatex è possibile creare PDF anche da documenti che hanno caratteri speciali in formato Unicode. Non voglio entrare nel dettaglio, ma fidatevi è meglio impostare questa opzione se non volete avere grattacapi con testo taglia-incollato da altri documenti in LaTeX.
Con il parametro -V si introduce una variabile in Pandoc. Nel nostro caso introduciamo due variabili opzionali, in particolare:
lang=it: serve per comunicare a LaTeX di utilizzare la sintassi italiana (per la sillabazione delle parole e per i nomi di alcune parti auto generate, tipo l'indice);colorlinks: serve per rendere i link colorati, utile in un PDF visualizzato a schermo (meno se stampato e dove i links ovviamente non funzionano più).
4.4 Aprire automaticamente il PDF creato
Siccome una volta che avete generato il PDF, immagino, lo vorrete controllare, vi suggerisco di aggiungere l’ulteriore comando (come si vede nel codice qui sotto) che permetterà di aprire con Anteprima il PDF appena creato.
pandoc input.md pdf-engine=xelatex -V lang=it -V colorlinks -o output.pdf && open output.pdf
4.5 La funzione di auto-completamento dei nomi dei file in Terminale
Fin qui abbiamo fatto solo esempi teorici, più complicato diventa se il nome del vostro file non è “input.md” ma “questo è il mio bellissimo file.md”.
Inserire a Termiale questo nome pone due problemi:
- Digitare l’interno nome del documento;
- Aggiungere la barra rovesciata ad ogni spazio (altrimenti il Terminale leggerà il primo spazio come la conclusione del nome del file e, non trovandolo, vi restituirà un errore).
Per risolvere il problema vi insegnerò un semplice trucco da Terminale che però vi cambierà la vita in termini di utilizzo.
Questo trucco è utile sia per completare il percorso per raggiungere una sotto-cartella (come visto al punto 4.1) sia per completare il nome di un file.
Quando siete nella finestra del Terminale iniziate a digitare il nome del documento che volete inserire nella riga di comando, dopo aver digitato le prime lettere premete il tasto TAB.
Se non ci sono altri documenti con lo stesso nome il nome verrà completato integralmente. In difetto (se ci sono due o più documenti che iniziano con le medesime lettere) completerà il nome fino a dove non ci sono scelte alternative. A questo punto se volete ulteriormente completare dovrete aggiungere qualche lettera per rendere la scelta del documento univoca. Altrimenti premendo nuovamente due volte in rapida successione il TAB vi comparirà a schermo i possibili nomi dei documenti tra cui scegliere.
Nella GIF animata che segue (in cui mostro anche i tasti che utilizzo) vedete un esempio di questo metodo.
Esempio di auto-completamento nel Terminale con il tasto TAB
Questo è molto utile anche quando si sta indicando un percorso delle cartelle e non ci si ricorda a modo in che sotto-cartella si trova cosa.
5. Un esempio con cui poter “giocare”
Qui potere scaricare un file .ZIP in cui sono contenuti un file in markdown con già tutte le parti di cui abbiamo parlato, un PDF generato con Pandoc e degli allegati di prova con cui testare il sistema dei link relativi nonché qualche immagine da inserire nel PDF finale.
Ho usato questo materiale per creare le immagini di questo articolo e di quello precedente.
5.1 Alcune precisazioni: uso del pacchetto lipsum
Se andrete ad aprire il file .MD Esempio di atto telematico avanzato in markdown.mdche troverete all'interno del file ZIP vi accorgerete di due cose:
- rispetto all’articolo precedente ho inserito un pacchetto aggiuntivo inserendo nell’intestazione YAML :
\usepackage{lipsum}; questo pacchetto fa una cosa semplicissima: aggiunge del testo in latino (un'orazione di Cicerone il c.d lorem ipsum) per riempire la pagina; - Al posto di alcune parti del testo c'è un comando in LaTeX di questo tipo:
lipsum[]; all'interno delle parentesi quadre è possibile specificare un intervallo di paragrafi del lorem ipsum da inserire nel documento.
Questo mi ha permesso di generare velocemente un PDF di qualche pagina senza dovermi inventare del testo a caso. Ovviamente per i vostri scopi pratici potete cancellare si i comandi che il pacchetto nell’intestazione YAML.
In conclusione
Siamo alla fine della serie degli articoli su come scrivere atti telematici avanzati in markdown. L’articolo originale, che poi ho suddiviso nei quattro articoli avrebbe superato le 4000 parole e credo che la suddivisione in parti ne abbia reso più facile la fruizione. Seppure di argomenti in questa serie ne siano stati trattati tanti (a volte molto sommariamente per necessità di spazio) credo e spero che seguendo questa guida introduttiva anche chi è a zero con le conoscenze del Terminale e nell’uso del markdown possa creare compiutamente un atto telematico avanzato senza troppe difficoltà.
Un particolare ringraziamento va ai miei lettori beta (voi sapete chi siete!) che mi hanno permesso di raffinare questa corposa serie.
Come sempre se avete domande o commenti li potete lasciare qui sotto.
Gli altri articoli della serie: