Automatizzare la creazione di link ai documenti in LaTeX

Scrivo questo articolo il giorno dopo aver finito un webinar di 3 ore su Overleaf e LaTeX.

1. Comunicazione di servizio: ho creato i capitoli per il video

Anzitutto volevo comunicarti che ho inserito i capitoli per le 3 ore di video del webinar così da porter fruire meglio e più velocemente dei contenuti.

2. Automatizzazione creazione link ai documenti in LaTeX

Se frequenti Avvocati e Mac sai che ho creato (e documentato) un sistema di Comandi Rapidi per creare in modo rapido i link ai documenti allegati in un atto telematico (scritto in markdown ovviamente).

Uno dei motivi per cui non mi sono mai deciso a passare a scrivere completamente in LaTeX i miei atti era proprio la mancanza di un flusso di lavoro simile che mi permettesse, in poco tempo, di creare i link ai documenti.

Nella sostanza infatti per creare un link ad un documento o ad una pagina web occorre digitare il seguente comando:

\href{nome del file.estensione}{testo da mostrare come link}

L’automazione che implemento in markdown si basa su due trucchi:

1. In markdown è possibile creare un link puntando ad un c.d. segnaposto; posso quindi creare l’elenco completo dei documenti e poi collegarli ad uno specifico segnaposto.
2. Una regex (regular expression) che cerca nel documento il modello “doc. numero” e sostituisce a tale modello il link al segnaposto.

Qui sotto l’esempio pratico del sistema di segnaposto / link markdown.

Questo è del testo e questo è un link al [doc. 1][doc01]
[doc01]: doc-01_nome_del_documento.estensione

Tutto funziona perché link e segnaposto sono legati ai numeri e, una volta che si conosce come fare, è semplice creare una regex che fa la permutazione del modello “doc. numero”.

Il problema è che questa modalità di creare i link in LaTeX non esiste.

Mentre preparavo le slides per i convegno tuttavia mi è venuta in mente un modo per risolvere il problema.

2.1 Le variabili di LaTeX

Ne ho parlato più dettagliatamente nel corso ed ha scritto un ottimo articolo Franco Pasut sull’argomento variabili in LaTeX, qui basti segnalare che in LaTeX c’è un interessante trucco per creare delle variabili da inserire nel nostro documento: la creazione di un nuovo comando.

Grazie infatti al comando \newcommand è possibile creare un nuovo comando, comando che si può inserire a piacimento nell’atto e che non farà altro che sostituire al nome del comando il contenuto attribuitogli.

Faccio un veloce esempio:

\newcommand{\avvocato}{avv. Filippo Strozzi}

Ogni volta che inserisco nel mio documento LaTeX il comando \avvocato nel documento finale comparirà il mio nome ovvero “avv. Filippo Strozzi”: la tua fantasia è il limite per l’utilizzo di questo trucco, ovviamente!

2.2 Il limite del creare un nuovo comando

Non mi sono documentato sul perché ma il grosso limite di questo sistema è che il comando da noi creato non può contenere al suo interno un numero: ad esempio se io creo il comando \avvocato01, casomai perché ci sono 2 avvocati nel mandato, questo comando non funzionerà e, unico escamotage per risolvere il problema è creare il comando \avvocatoUno in cui il numero è scritto in lettere. Avevo quindi il problema di come poter implementare il trucco che già usavo per il markdown con questo limite.

2.3 Convertire numeri arabi nel corrispettivo in lettere

Facendo un po' di ricerche online scopo che esiste un AppleScript che fa la conversione da numero a lettere.

La faccio breve ma dopo i primi test mi sono di nuovo trovato in un vicolo cieco perché (non ho scoperto come mai) il numero in lettere che viene restituito dallo script ha una strana formattazione e non funziona correttamente in LaTeX (o quantomeno in Overleaf dove lo avevo testato).

Stavo per cedere quando mi sono accorto che la funzione di conversione di numero in lettere è stata implementata da Actions: l’app che aggiunge nuove azioni a comandi rapidi, in particolare funzioni tipiche della programmazione Apple come appunto la conversione di numeri in lettere.

Ero finalmente in pista!

3. Comandi rapidi per creare i link ai documenti in LaTeX

Qui di seguito trovi i link per scaricare i due comandi rapidi per automatizzare la creazione dei link in LaTeX ai documenti e, come bonus, la versione riveduta e corretta dei 2 comandi per numerare e togliere la numerazione ai documenti:

1. Link per creare le variabili che puntano ai documenti;
2. ReGeX che crea i link ai documenti nel corpo dell’atto;
3. Numera documenti;
4. Togli numerazione ai documenti.

Oggi non è mia intenzione spiegare nel dettaglio come funzionano i comandi rapidi, ma voglio spiegarti come utilizzarli correttamente.

3.1 Creazione delle variabili che puntano ai documenti

Il primo comando rapido si occupa di creare le variabili che puntano ai documenti allegati.

Io consiglio di abilitarla come azione rapida, come si vede nell’immagine sottostante.

Esempio di file per cui creare le variabili con il comando rapido

Il risultato di questo comando sarà del testo salvato negli appunti opportunamente formattato, come mostrato nell’immagine sottostante.

Esempio nell’editor di Overleaf del testo salvato negli appunti dal comando rapido

3.2 Creazione dei link nel corpo del documento

Premetto che questo comando rapido l’ho creato appositamente per le mie esigenze in Overleaf. Potrebbe essere modificato con non troppa difficoltà per essere utilizzato su un file .TEX residente sul computer.

Per quel che ci riguarda richiede di copia/incollare negli appunti l’intero documento LaTeX (⌘+A nella finestra di Overleaf e poi ⌘+C) e poi lanciare il comando rapido.

Quest’ultimo modificherà il testo negli appunti aggiungendo i link ai documenti.

Esempio del secondo comando rapido e della regex di creazione dei link

Questo comando rapido è stato fatto un po' di fretta e la ReGeX andrebbe ottimizzata per LaTeX, quindi segnalo che per ora funziona bene quando i modello “doc. numero” è tra parentesi o separato. In altri casi la conversione potrebbe non avvenire correttamente.

Esempio di problemi nella conversione per cui stare attenti

In un futuro prossimo conto di ottimizzare la ReGeX, stay tuned.

3.3 Numerazione documenti e viceversa

Da ultimo allego anche i comandi rapidi per numerare i documenti (nell’ordine in cui sono stati selezionati su macOS) e togliere la numerazione fatta (nel caso di errori).

Mentre i precedenti comandi rapidi aggiungevano anche un underscore e rendevano il testo un tutt’uno, questi comandi rapidi antepongono solo doc ed il numero progressivo per poi togliere usando il medesimo patter o modello.

In conclusione

Gli approfondimenti dei miei vari webinar sono sempre un utile spunto per creare o ripensare a qualcosa. Negli ultimi mesi avevo attaccato il problema dei link ai documenti in LaTeX in varie maniere ma è solo alla fine della preparazione del webinar che mi è venuta in mente la possibile soluzione e, il giorno prima del webinar, ho messo in piedi i comandi rapidi che ho condiviso con te.

Probabilmente esistono sistemi migliori ma per ora i comandi in questione fanno qual che devono e risolvono il problema di fare i link manualmente.