Quando scrivere documenti diventa un’attività quotidiana, un po’ di automazione può veramente salvarti la vita.

Report e presentazioni

Pandoc è un convertitore universale di documenti. Supporta moltissimi formati, sia in ingresso che in uscita, ma io uso soprattutto file Markdown che converto in PDF.

In realtà Pandoc effettua una conversione intermedia in LaTeX, quindi è necessario installare una distribuzione come TeXLive o MiKTeX. Il vantaggio è che posso scrivere i miei documenti in Markdown e usare i comandi LaTeX solo quando necessario: quindi ottengo file più leggeri e leggibili.

Inoltre ho un unico workflow per documenti e presentazioni: Pandoc ha un’ottima interfaccia per realizzare slide mediante beamer.

Citazioni e Mendeley

Pandoc supporta i file di bibliografia BibTeX. Anziché crearli a mano, come ho fatto ai tempi della tesi triennale, vale la pena imparare a usare Mendeley o Zotero, che sono in grado di recuperare automaticamente i metadati di un PDF e generare file BibTeX.

Panzer

Pandoc supporta l’aggiunta di metadati sotto forma di un “frontespizio” in formato YAML all’inizio del file. Ciò permette anche di personalizzare, entro certi limiti, l’aspetto del PDF finale; molte altre preferenze, tuttavia, sono accessibili solo attraverso parametri dalla linea di comando. Purtroppo alcuni parametri sono necessari solo in alcune circostanze e vanno evitati in altre, quindi le prime soluzioni che ho provato (shell scripts e alias) non erano abbastanza flessibili.

Fortunatamente qualcuno ha avuto il mio stesso problema e l’ha risolto creando Panzer, una specie di wrapper attorno a Pandoc che aggiunge il concetto di “stili”.

Grazie a Panzer, è possibile impostare tra i metadati del documento uno o più stili, che definiscono nel dettaglio come il documento deve essere processato da Pandoc:

• template
• opzioni da linea di comando
• Filtri prima e dopo la conversione

Gli stili riducono notevolmente la quantità di metadati che devo inserire in ciascun documento e danno una maggiore uniformità ai miei PDF.

Sublime + Skim/Sumatra

Sublime Text è il mio editor di riferimento, anche se non supporta nativamente la sintassi Markdown: basta installare il plugin Markdown Extended.

Uno dei pregi di Sublime è la possibilità di definire un build system: un comando personalizzato che viene eseguito direttamente dall’editor quando l’utente schiaccia un tasto (F7, di default).

Nel mio caso ho creato un build system che converte il mio file Markdown con Panzer per poi aprire il PDF appena generato.

Uso Skim su Mac e SumatraPDF su Windows: entrambi hanno il vantaggio di non “bloccare” il PDF, il che mi permette di correggere i miei errori e rigenerare il PDF (che verrà automaticamente visualizzato nella sua nuova versione).

Esempi

Sto allestendo un repository GitHub dove pubblicare report e slide che sto producendo mentre studio per il mio dottorato. Al momento non ho caricato molti file, e temo di non poter garantire che saranno compilabili su qualsiasi PC, ma dovrebbero rendere più o meno l’idea!

Questo sito

Il sito (che dovrei aggiornare più spesso 😅) esiste grazie a Hugo, uno static site generator scritto in Go.

Come tutti i software del suo tipo, Hugo genera pagine HTML a partire da un insieme di file Markdown.

Per alcune pagine “procedurali”, come quella del CV, non ho nemmeno un documento Markdown: tutte le informazioni sono contenute in diversi file YAML, e ho scritto dei template per visualizzarle nelle rispettive pagine del sito. Il procedimento è descritto qui.

Per i commenti mi appoggio a Disqus: molti temi di Hugo permettono di integrarlo inserendo solo il proprio shortname nel file di configurazione del sito.

Uso GitHub Pages per l’hosting: ho creato un repsitory privato per l’intera cartella Hugo (quindi anche bozze, temi e altro materiale che non appare sul sito), mentre la cartella public è un submodule pubblico. In questo modo, se il risultato mi soddisfa, posso aggiornare tutto con un singolo git push.

Conclusioni

Al momento credo che continuerò a scrivere LaTeX “manualmente” solo se il lavoro finale deve essere pubblicato o sottoposto a peer-review. Per il resto, sono veramente convinto che lavorare in Markdown mi permetta di limitare al massimo le distrazioni e di concentrarmi su ciò che sto scrivendo.