Scrivere atti telematici avanzati in LaTeX (parte II): convertire l’intestazione YAML

Questo articolo fa parte di una serie di articoli su come creare un flusso di lavoro (identico per iPad e Mac) grazie a LaTeX per creare atti telematici avanzati.

1. Convertire l’intestazione YAML in una intestazione LaTeX

Se avete letto i miei precedenti articoli su come creare un atto telematico avanzato con Pandoc usando Markdown e LaTeX, saprete che il “trucco” per creare un PDF avanzato è quello di inserire prima del testo vero e proprio una c.d. intestazione YAML.

Questa intestazione può essere molto semplice (indicando solo il nome dell’autore ed altre semplici informazioni) oppure complesso.

La complessità dell’intestazione YAML è dovuta prevalentemente alle impostazioni da dare a Pandoc per LaTeX. Bene, se vi siete già sporcati le mani con la fase uno, vi troverete molto avvantaggiati in questo passaggio “naturale”.

Altrimenti non preoccupatevi … vi guiderò passo passo.

1.1 La classe del documento

LaTeX è una via di mezzo tra linguaggio di programmazione ed uno di markup, ha varie “classi” di documenti che può tipo-comporre. A noi qui non interessa entrare nel dettaglio perché utilizzeremo solo una classe (quella dell’articolo) ma sapere il perché utilizziamo il comando che segue credo sia utile:

\documentclass[a4paper, 11pt]{article}

Anzitutto un comando in LaTeX viene introdotto dalla barra rovesciata o backslash, a questa segue il nome del comando, nel nostro caso documentclass ovvero classe del documento e a cui possono seguire (opzionalmente) dei parametri o per chi non mastica l’informatica delle caratteristiche o opzioni del comando racchiuse tra parentesi quadre. Nel nostro esempio [a4paper, 11pt] che, indovinate un po', specificano che il nostro documento deve essere impaginato all’interno di un foglio A4 e che il font deve essere di 11 punti. A seguire poi ci sono le parentesi graffe all’interno delle quali va inserita, nel nostro esempio, il tipo di classe del documento, ovvero nel nostro caso l’articolo (article in inglese). Mentre i parametri tra parentesi quadre sono obbligatori e, in loro assenza, viene dato un errore perché LaTeX non sa come comportarsi.

1.2 I pacchetti di espansione di LaTeX ed il loro parametri

LaTeX ha una serie di comandi di base che vedremo più avanti, ma spesso vi troverete a voler fare qualcosa che la versione c.d. vanilla, ovvero originale, di LaTeX non può fare. Nel corso del lungo tempo in cui esiste LaTeX gli utilizzatore hanno creato una infinità di estensioni, denominate pacchetti in inglese package, che permettono di espandere le funzioni di LaTeX.

Se avete bisogno di qualcosa, quasi certamente, esiste un pacchetto che lo può fare.

Ovviamente approfondire uno ad uno i pacchetti sarebbe oltre lo scopo di questo breve articolo, ma è importante che ne comprendiate l’esistenza, quello che segue è l’intestazione che utilizzo per formattare i miei atti all’interno della quale ho inserito i pacchetti che ritengo utili per scrivere un atto.

Prima di esaminare l’intestazione ritengo comunque utile ricordare che se siete incuriositi su come funziona un pacchetto potete trovare tutti i pacchetti per LaTeX qui. Piccola avvertenza la maggior parte dei pacchetti ha i manuali scritti in inglese (la lingua franca della programmazione) e, spesso, è relativamente tecnica. Ciò detto spesso si trovano guide ed approfondimenti anche in lingua italiana, basta cercare un po'.

1.3 Esempio di intestazione LaTeX

Di seguito trovate quella che è la mia attuale configurazione di pacchetti e loro personalizzazioni. Ho commentato (vedremo come si commenta in LaTeX a breve) il tutto, mi soffermerò quindi solo su alcuni aspetti che ritengo interessanti / utili da approfondire.

% Lingua italiana
\usepackage[french,italian]{babel} % Adatta LaTeX alle convenzioni tipografiche italiane,
% e ridefinisce alcuni titoli in italiano, come "Capitolo" al posto di "Chapter",
% se il vostro documento è in italiano
% l'opzione  linguistica 'french' è necessaria per l'abilitazione della
% successiva istruzione <<\frenchspacing>> 
\frenchspacing 
% forza LaTeX ad una spaziatura uniforme, invece di lasciare più spazio alla fine dei punti fermi come da convenzione inglese: richiede opzione linguistica 'french'
% link a file e web
\usepackage{hyperref}
\hypersetup{
    colorlinks=true,
    linkcolor=blue,
    filecolor=magenta,
    urlcolor=blue,
    pdftitle={Il titolo del PDF da mostrare},
    pdfpagemode=UseOutlines, % mostra i segnalibri sulla sinistra del PDF
    unicode=true,    % permette la visualizzazione di caratteri non-Latini nei segnalibri di Acrobat
    pdftoolbar=true,    % mostra Acrobat’s toolbar - sono i valori di base quindi non è necessario
    pdfmenubar=true      % mostra Acrobat’s menu - sono i valori di base quindi non è necessario
    }
\setlength\parindent{0pt} % Toglie indentazione ad inizio dei paragrafi (parametro generale)
\usepackage{lastpage} % Individua il numero dell’ultima pagina del documento
\usepackage{advdate} % permette di calcolare le date in modo relavito
\usepackage{tcolorbox} % Pacchetto per creare delle cornici intorno al testo
\usepackage{spreadtab} % permette di avere in LaTeX una sorta di foglio eletronico (ma non ne parlerò qui)
\usepackage{xstring}
\usepackage{nicefrac} % Rende le frazioni in modo graficamente piacevole
\usepackage{fancyhdr} % Configurazione personalizzata di piè di pagina e testatina
\pagestyle{fancy} % Personlizzazione della testatina e del piè di pagina
    \lhead{R.G. }
    \chead{}
    \rhead{}
    \lfoot{}
    \cfoot{\thepage\ di \pageref{LastPage}} % Usa LastPage per avere 1 di N pagine
    \rfoot{}

1.4 Impostazione della lingua italiana

LaTeX, come molti altri “programmi”, nasce per la lingua inglese. Per adattarlo alla lingua italiana occorre utilizza un pacchetto per interpretare opportunamente la lingua italiana, in particolare la sillabazione della parole.

Per fare ciò esistono due differenti pacchetti: babel e polyglossia.

Per quel che ci interessa noi useremo babel che, da quel che ho potuto capire, è il più semplice dei due ma che, se non dovete scrivere il vostro atto in lingue differenti e con differenti idiomi, dovrebbe essere più che sufficiente come soluzione.

\usepackage[french,italian]{babel}

La regola è la solita all’interno delle parentesi graffe va il pacchetto (babel) nel nostro caso e, tra le parentesi quadre, la lingua che si vuole utilizzare nel documento. Come potrete notare oltre che l’italiano (italian in inglese) ho inserito il francese (french in inglese). Questo perché, da dove ho copiato il tutto, si specifica che per evitare delle tipiche caratteristiche della scrittura inglese (i doppi spazi alla fine di una frase dopo il punto) è necessario inserire il comando \frenchspacing che può essere tradotto sommariamente come spaziatura francese.

1.5 Personalizzazione dei Link (a documenti ed a pagine web)

Una delle comodità maggior in atto telematico avanzato sono i link ai documenti allegati. In markdown i link sono generati in maniera automatica, con LaTeX bisogna sforzarsi un pelino di più.

Per inserire link, non solo a documenti e pagine web, in un documento di LaTeX si utilizza il pacchetto hyperref. Questo pacchetto (la qui guida completa trovate qui) fa molto di più di quel che vi illustrerò in questa parte.

Ora vedremo alcune configurazioni di base del pacchetto, nei prossimi articoli, invece, vedremo come utilizzarlo per i nostri documenti.

\usepackage{hyperref}
\hypersetup{
    colorlinks=true,
    linkcolor=blue,
    filecolor=magenta,
    urlcolor=blue
}

Quella che precede è una configurazione di base per avere i link colorati (utili per documenti che non devono essere stampati come i PDF dei depositi telematici) ed una configurazione di base dei link: blu per i link e gli url (come è prassi su internet) e magenta per i documenti. Quest’ultima è una mia scelta personale ma credo sia utile per rendere visibilmente differente il link al documento ed un modo per renderli maggiormente visibili nell’atto, visto che dalla mia esperienza sono poco conosciuti da magistrati e colleghi.

Come potrete aver compreso questi parametri vengono inserite all’interno del comando \hypersetup{} (traducibile in italiano come configurazione di hyperref).

1.6 Personalizzazione della vista del PDF finale

Da ultimo, per quanto riguarda la configurazione del pacchetto hyperref, ho tenuto separati (ma nel mio modello di base è un unicum) i parametri per la visualizzazione del PDF finale.

\hypersetup{
    pdftitle={Il titolo del PDF da mostrare},
    pdfpagemode=UseOutlines, % mostra i segnalibri sulla sinistra del PDF
    unicode=true,    % permette la visualizzazione di caratteri non-Latini nei segnalibri di Acrobat
    pdftoolbar=true,    % mostra Acrobat’s toolbar - sono i valori di base quindi non è necessario
    pdfmenubar=true      % mostra Acrobat’s menu - sono i valori di base quindi non è necessario
    }

Oltre ai parametri che vi ho mostrato, ce ne sono altri, ad esempio un parametro per mostrare nel PDF finale il nome dell’autore o l’oggetto del documento, trovate l’elenco completo al punto 3.9 della guida di hyperref

1.7 Indentazione dei paragrafi del nostro atto.

Personalmente non amo gli atti con indentazione all’inizio di un nuovo paragrafo, le lettere della prima frase sono rientrate rispetto al corpo del paragrafo stesso, come si vede nell’immagine sottostante.

\setlength\parindent{0pt} % Toglie indentazione ad inizio dei paragrafi (parametro generale)

Io trovo più accattivante senza rientro ma con una spaziatura tra un paragrafo e l’altro.

Questa è una impostazione di gusto personale quindi potete tranquillamente toglierla.

1.8 Pagina 1 di N

Sono un profondo fautore di rendere esplicito al nostro lettore di quante pagine complessive è composto il nostro scritto. Questo, soprattutto, se si usa uno strumento digitale. Preannunciare infatti quanto è lungo un documento prepara (nel bene e nel male) il nostro lettore e, credo, lo preavverta quantomeno dello sforzo che dovrà fare.

LaTeX normalmente inserisce solo il numero della pagina, utilizzando il pacchetto LastPage (traducibile in italiano come ultima pagina) e inserendo l’opportuna configurazione all’interno del piè di pagina con fancyhdr che sta per Fancy Header ovvero intestazione aggraziata, mi permette di fare ciò senza alcuno sforzo.

\usepackage{lastpage} 
\pagestyle{fancy}
    \cfoot{\thepage\ di \pageref{LastPage}}

In particolare all’interno di \cfoot{} (che vedremo al punto successivo) viene inserito il costrutto \thepage\ di \pageref{LastPage} che può essere “tradotto” come segue:

• \thepage è il comando che stampa il numero della pagina in cui si trova il comando; dopo questo comando ho inserito la barra inversa perché altrimenti il testo “di” sarebbe risultato attaccato al numero di pagina (così ad esempio: 1di…);
• \pageref{LastPage} infine dice di fare riferimento, il comando \pageref{}, all’ultima pagina del documento (individuata grazie al pacchetto LastPage).

Piccola nota futura per la compilazione: il pacchetto LastPage è uno di quelle che richiede un doppio passaggio di compilazione. Questo perché LaTeX prima deve determinare il numero di pagine totali dopo la compilazione e, con una nuova compilazione, può poi inserirlo correttamente.

1.9 Personalizzazione della testatina e del piè di pagina

L’utilizzo attento di testatina (la parte alta della pagina) e del piè di pagina credo siano un ottimo strumento per condividere informazioni di base con il nostro lettore e per rendere riconoscibile il nostro documento.

Personalmente, se predispongo un atto giudiziario, nella parte sinistra della testatina inserisco il numero di registro della causa così da rendere semplice ovunque sia nel documento riconoscere questo dato fondamentale. Nella parte destra invece inserisco un oggetto sintetico del mio atto. Per documenti molto lunghi si potrebbe inserire il capitolo o la sezione dell’atto in cui ci si trova, ma abitualmente non scrivo atti giudiziari così lunghi da richiedere una simile composizione. Se però foste interessati a ciò potete usare il comando \thesection nella gestione della testatina o piè di pagina come vedremo a breve.

Invece nel piè di pagina abitualmente inserisco il numero della pagina e quello delle pagine complessive (al centro), come abbiamo già visto, e sulla destra il numero della pratica di modo da poter individuarla facilmente e poter utilizzare delle automazioni su tali documenti.

\usepackage{fancyhdr}
\pagestyle{fancy}
    \lhead{ R.G. 1/2021}
    \chead{}
    \rhead{Atto di prova}
    \lfoot{}
    \cfoot{\thepage\ di \pageref{LastPage}}
    \rfoot{100F}

Dopo aver detto a LaTeX che si vuole usare il pacchetto fancyhdr occorre passare il comando \pagestyle{} che specifica come impostare testatina e piè di pagina. Utilizzando l’opzione fancy è possibile personalizzare come vengono rappresentate testatina e piè di pagina.

In questo caso si può specificare cosa viene mostrato nei 3 quadranti rispettivamente della testatina e del piè di pagina. La composizione del sub-comando è relativamente semplice: l (per left ovvero sinistra), c (per center ovvero al centro) e r (per right ovvero destra) seguito da head (testa) per la testatina e foot (piede) per il piè di pagina con, all’interno delle parentesi graffe, cosa si vuole inserire nella testatina o piè di pagina.

Se siete super stilosi potreste differenziare testatina e piè di pagina per le pagine dispari e pari. Tuttavia credo sia eccessivo per le esigenze di un legale e, quindi, vi lascio eventualmente ad una ottima guida (in inglese).

2. I commenti in LaTeX

Visto che ho messo molta carne al fuoco in questo articolo ora procediamo con due argomenti relativamente semplici. Il primo è come inserire commenti all’interno nel nostro documento scritto in LaTeX.

Inserire un commento è veramente semplice, occorre inserire semplicemente il simbolo percento _%_ e tutto quello che si scriverà dopo sulla medesima linea di testo non verrà preso in considerazione da LaTeX.

Devo dire che questo modo di commentare è molto simile ai linguaggi di programmazione ed è una delle poche cose che mi manca quando scrivo in Markdown.

Inserire infatti i commenti in un documento LaTeX permette di lasciare a se stessi osservazioni o testo da riguardare e, per l’intestazione abilitare o disabilitare in un batter d’occhio un pacchetto o una specifica opzione che si vuole testare.

Il mio consiglio è di abusare dei commenti. Sempre meglio lasciare un nota a se stessi che sia un commento per una opzione usata o qualcosa che manca nel documento o un pensiero che si vuole ricordare, piuttosto che perdersi un’idea per strada.

I commenti non risulteranno del PDF finale e resteranno nascosti all’utente finale.

3. Il contenuto del documento

Chiudiamo infine con qualcosa di relativamente semplice ma essenziale, ovvero come si dice a LaTeX qual’è il testo del nostro documento.

\begin{document}
Contenuto del documento.
\end{document}

Quella che vedete qui sopra è la dichiarazione di inizio e fine del documento e, come potrete immaginare, dove sarà contenuto il testo vero e proprio del documento.

La cosa che mi interessa sottolineare è che questa modalità di dichiarare un contenuto (nel nostro caso dove si trova il testo del nostro documento) si ripresenterà più e più volte in LaTeX. Quindi tenete bene in mente i comandi \begin{} e \end{}.

Nel prossimo articolo vedremo come riempire di contenuti il nostro documento ma, soprattutto, come tipo-comporlo con LaTeX.

In conclusione

Spero di non avervi annoiato con i dettagli tecnici di come funziona una intestazione in LaTeX ma credo sia importante oltre a darvi una intestazione funzionante spiegarvi come e perché certe scelte sono state fatte e come poter modificare queste scelte.

Nel corso della serie di articoli vi allegherò anche una bozza di atto in LaTeX, quindi non preoccupatevi di ricopiare le parti che trovate riportate qui.

Tolta di mezzo la parte introduttiva, nel prossimo articolo vedremo come formattare il nostro documento in LaTeX.

Da ultimo, se siete incuriositi e volete approfondire con me l’argomento, sto organizzando per ottobre / novembre 2021 un workshop sull’argomento qui trovate maggiori informazioni.