Organizzazione di un progetto

Per i documenti complessi è utile suddividere il documento in più file sorgente per migliorarne la gestione:

• file più piccoli facilitano l’editing dei contenuti e la concentrazione sulle singole unità,
• la struttura del documento si delinea con maggior chiarezza,
• in un gruppo di lavoro diverse persone lavorando su differenti sorgenti collaborano alla stesura di uno stesso documento,
• modificare l’ordine dei capitoli si riduce a spostare singoli comandi,
• i tempi di compilazione possono ridursi sensibilmente.

Con gli editor di testo moderni gli svantaggi sono invero ridotti al minimo. Si possono tenere aperti molti file allo stesso tempo o fare ricerche su tutti i file di una directory. I plug-in possono gestire nomi e riferimenti presenti in altri file.

Struttura dell’archivio

I sorgenti assumono una struttura nidificata che rispecchia quella del documento: con un livello la suddivisione è in capitoli o in sezioni. Con due livelli la suddivisione è in parti e sotto-parti.

Ogni unità può essere un singolo file sorgente oppure più file sorgente in una directory assieme a risorse locali come immagini, grafici, o bibliografie.

L’importante è che il progetto resti ordinato mano a mano che evolve e che si possa riconoscere il ruolo di un dato file semplicemente leggendone nome e posizione.

Assemblare file sorgente

Ogni documento ha un unico sorgente principale detto main file. All’interno del main possono essere inclusi altri file tramite i comandi \input{} o \include{}.

Quando il compositore compila il main file processerà i file esterni inclusi in un dato punto come se fossero stati digitati in quella posizione.

Questo ha una conseguenza importante perché nei file secondari i percorsi dei file di immagini devono riferirsi alla posizione dove si trova il file principale e non a quella del file secondario.

La cartella dove risiede il file principale è detta root o home del progetto.

Il comando \input{}

Questo comando come argomento accetta il percorso del file da inserire.

Nel percorso i nomi dei file possono essere separati da caratteri / (slash) indipendentemente dal sistema operativo, partendo dalla cartella di root del progetto. L’estensione .tex può essere omessa.

Qui un esempio di main file per una ipotetica biografia di un poeta (i sei file dei capitoli si trovano in una sotto cartella chapter):

% main file
\documentclass{book}

\begin{document}
\input{chapter/00-introduzione}
\input{chapter/01-infanzia}
\input{chapter/02-primo-amore}
\input{chapter/03-il-capolavoro}
\input{chapter/04-anni-guerra}
\input{chapter/99-conclusioni}
\end{document}

e questa la corrispondente struttura dei file:

home-progetto/
├── main.tex                   # Sorgente principale
├── chapter/
│   ├── 00-introduzione.tex    # sorgente di capitolo
│   ├── 01-infanzia.tex        # sorgente di capitolo
│   ├── 02-primo-amore.tex     # sorgente di capitolo
│   ├── 03-il-capolavoro.tex   # sorgente di capitolo
│   ├── 04-anni-guerra.tex     # sorgente di capitolo
│   └── 99-conclusioni.tex     # sorgente di capitolo
├── main.pdf                   # documento finale compilato
├── main.aux                   # file ausiliario della compilazione
├── main.log                   # file di log della compilazione
├── main.toc                   # dati ausiliari del sommario
└── README.md                  # eventuale file di testo per note varie

Note

Dare buoni nomi ai file e alle cartelle è un’utile arte. Evita di usare caratteri spazio o accentati. Se iniziano con una numerazione saranno mostrati nell’ordine numerico assegnato e non con quello alfabetico dei semplici nomi.

Il comando \include{}

In LaTeX esiste anche il comando \include{} pensato per compilare documenti complessi suddivisi in capitoli. Con questo comando è possibile compilare in modo selettivo i capitoli così da limitare il tempo di compilazione mantenendo riferimenti corretti alle parti escluse.

Lo scenario è quindi quello di un documento complesso, come una tesi per esempio, che richiede compilazioni frequenti ogni volta che si desidera controllare il risultato. A mano a mano che si inserisce contenuto i tempi si allungano.

Dunque è utile compilare solamente una selezione di capitoli, magari anche uno solo. Nel preambolo \includeonly{} imposta \include{} a inserire solo i file specificati. Ecco un esempio di codice:

% main file
\documentclass{book}

\includeonly{chapter/02-primo-amore,chapter/03-il-capolavoro} 

\begin{document}
\include{chapter/00-introduzione}
\include{chapter/01-infanzia}

% unici due capitoli effettivamente inseriti
\include{chapter/02-primo-amore}
\include{chapter/03-il-capolavoro}

\include{chapter/04-anni-guerra}
\include{chapter/99-conclusioni}
\end{document}

A differenza di \input{} e a conferma che \include{} è stato pensato per includere file di capitolo, quest’ultimo inserisce sia prima che dopo il contenuto del file un’interruzione di pagina, non può essere usato nel preambolo e non può essere annidato, ovvero non è possibile includere file che a sua volta contengono chiamate \include{}.