Capitolo 242. LaTeX: riferimenti

LaTeX gestisce diversi tipi di riferimenti incrociati, di cui il più importante è l'indice generale, ottenuto attraverso il comando \tableofcontents. La gestione dei riferimenti incrociati avviene attraverso la creazione di file temporanei, adibiti ad accumulare le informazioni, da riutilizzare attraverso rielaborazioni successive. In pratica, è proprio la presenza di questi riferimenti incrociati che obbliga a ripetere il procedimento di composizione più volte.

242.1 Indice generale, indice delle tabelle e delle figure

La creazione dell'indice generale, dell'indice delle tabelle e dell'indice delle figure, parte dall'accumulo delle informazioni sulla collocazione di queste voci. Per la precisione, i comandi che definiscono la suddivisione del documento annotano il titolo, il numero della sezione e la pagina in un file con estensione .toc (Table of contents); i comandi \caption inseriti nell'involucro fluttuante di una tabella o di una figura, annotano il numero e la pagina in cui si trovano in file con estensione .lot (List of tables) e .lof (List of figures).

Nella rielaborazione successiva (quando il comando di composizione viene ripetuto), questi file possono essere incorporati attraverso i comandi \tableofcontents, \listoftables e \listoffigures, per ottenere rispettivamente l'indice generale, l'indice delle tabelle e delle figure.

Dal momento che l'inserzione modifica la lunghezza del testo, a meno che gli indici siano collocati alla fine del documento, si rende necessaria almeno una terza rielaborazione.

`\tableofcontents`	inserisce nella composizione l'indice generale, ottenuto dal file `.toc`, generato dalla composizione precedente;
`\listoftables`	inserisce nella composizione l'indice delle tabelle, ottenuto dal file `.lot`, generato dalla composizione precedente;
`\listoffigures`	inserisce nella composizione l'indice delle figure, ottenuto dal file `.lof`, generato dalla composizione precedente.

L'inserimento di voci in questi elenchi può avvenire anche in modo manuale, attraverso due comandi appositi:

`\addtocontents{toc\|lot\|lof}{testo}`	aggiunge il testo indicato nell'ultimo argomento, nell'indice corrispondente alla sigla del primo argomento (indice generale, indice delle tabelle o indice delle figure);
`\addcontentsline{toc\|lot\|lof}{livello}{testo}`	aggiunge la voce nell'indice corrispondente alla sigla del primo argomento.

Il funzionamento del comando \addtocontents è relativamente semplice, nel senso che ci si limita ad aggiungere del testo nell'indice prescelto:

\tableofcontents

\section{Prima}

Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla...

\addtocontents{toc}{Ciao a tutti\par}

Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla...

\section{Seconda}

Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla...

Si può osservare che nel testo inserito è stata aggiunta la richiesta esplicita di concludere il paragrafo; ciò si rende necessario per evitare problemi imprevisti nel momento dell'incorporazione del file .toc.

indici

L'uso di \addcontentsline è più complesso, perché richiede anche l'indicazione del «livello» della voce. Se si tratta dell'indice generale, il livello è rappresentato dalle parole chiave da part a subparagraph, mentre negli altri casi è ammesso l'uso di table o figure. Così si intende che la voce inserita sia da trattare allo stesso modo del livello corrispondente, per ciò che riguarda la composizione. Nell'esempio che segue, la voce si inserisce al livello di una sottosezione:

\tableofcontents

\section{Prima}

Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla...

\addcontentsline{toc}{subsection}{Ciao a tutti}

Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla...

\section{Seconda}

Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla...

Come si vede, in questo caso non c'è più bisogno di concludere il paragrafo nel testo, cosa che al contrario genererebbe qui solo un errore:

indici

Volendo, si può spiare il contenuto del file .toc generato, per scoprire come si può aggiungere una cifra davanti alla voce inserita manualmente:

\contentsline {section}{\numberline {1}Prima}{1}
\contentsline {section}{Ciao a tutti}{1}
\contentsline {section}{\numberline {2}Seconda}{1}

Intuitivamente si comprende l'uso del comando \numberline:

\tableofcontents

\section{Prima}

Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla...

\addcontentsline{toc}{subsection}{\numberline{1.1}Ciao a tutti}

Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla...

\section{Seconda}

Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla...

indici

242.2 Riferimenti liberi

LaTeX mette a disposizione pochi comandi per la creazione di riferimenti incrociati all'interno del testo. Attraverso il comando \label è possibile definire un'etichetta alla quale si può fare riferimento con i comandi \ref o \pageref:

`\label{stringa_identificativa}`	mette un punto di riferimento invisibile, identificato dalla stringa contenuta nell'argomento;
`\ref{stringa_identificativa}`	inserisce nella composizione il numero corrispondente alla stringa di identificazione indicata, secondo il contesto;
`\pageref{stringa_identificativa}`	inserisce nella composizione il numero della pagina corrispondente alla stringa di identificazione indicata.

La posizione in cui viene collocato il comando \label è importante, in quanto sarà diverso il comportamento di \ref nel momento in cui dovesse servire. Se l'etichetta viene dichiarata all'interno di testo normale, il riferimento generico a questa restituisce un numero, più o meno articolato, che indica la sezione o il capitolo in cui si trova; se invece l'etichetta viene dichiarata all'interno di un ambiente numerato, come una tabella, una figura, un'equazione o altro, il riferimento a questa genera il numero corrispondente a tale elemento.

A titolo di esempio, viene mostrato come si potrebbe procedere per la costruzione manuale di un indice generale, senza l'ausilio del comando \tableofcontents:

\section*{Indice}

\noindent\ref{sec:Prima} Prima, pag. \pageref{sec:Prima}

\noindent\ref{sec:Seconda} Seconda, pag. \pageref{sec:Seconda}

\section{Prima} \label{sec:Prima}

Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla...

\section{Seconda} \label{sec:Seconda}

Bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla...

riferimenti

È bene ribadire che LaTeX inserisce implicitamente le etichette generate con il comando \label in un contesto particolare, per cui il risultato del comando \ref cambia di conseguenza. Tuttavia, il numero che viene mostrato da \ref non è accompagnato dal contesto in fase di composizione, pertanto è compito dell'autore scrivere di cosa si tratta (capitolo, sezione, tabella, figura o altro). In questo senso, diventa importante ricordare a cosa si riferisce una certa stringa di identificazione, pertanto, la stessa documentazione originale di LaTeX propone di usare un prefisso diverso in base al contesto:

`\label{cha:stringa_successiva}`	etichetta di identificazione di un capitolo;
`\label{sec:stringa_successiva}`	etichetta di identificazione di una sezione di livello inferiore al capitolo;
`\label{tab:stringa_successiva}`	etichetta di identificazione di una tabella;
`\label{fig:stringa_successiva}`	etichetta di identificazione di una figura;
`\label{eq:stringa_successiva}`	etichetta di identificazione di un'equazione.

Le stringhe di identificazione generate dal comando \label, sono annotate in un file con estensione .aux (assieme ad altre informazioni estranee). Quando LaTeX viene riavviato in una fase di composizione successiva, carica in memoria i dati contenuti nel file .aux e lo utilizza per risolvere i riferimenti con i comandi \ref e \pageref.

242.3 Indice analitico

La realizzazione di un indice analitico, ovvero un indice che raccoglie una serie ordinata di voci che possono essere inserite in varie parti del documento, è più complessa rispetto a quella dell'indice generale. In special modo, in questo caso è necessario provvedere a riordinare e riorganizzare i dati nel modo corretto. I comandi coinvolti per la realizzazione dell'indice analitico, sono riassunti brevemente nell'elenco seguente:

`\usepackage{makeidx}`	si usa questo comando nel preambolo per importare il codice necessario alla gestione dell'indice analitico;
`\makeindex`	si usa questo comando, sempre nel preambolo, per attivare la gestione dell'indice analitico;
`\index{voce}`	inserisce la voce indicata nel file `.idx`, dal quale si otterrà poi l'indice analitico;
`\printindex`	inserisce l'indice analitico contenuto nel file `.ind`, ottenuto attraverso un'elaborazione esterna a LaTeX.

Come si vede, è necessario utilizzare un pacchetto esterno, denominato makeidx, quindi si deve attivare la costruzione dell'indice, con il comando \makeindex. Pertanto, si troveranno le istruzioni seguenti nel preambolo:

\usepackage{makeidx}
\makeindex

Lo scopo particolare di \makeindex è quello di aprire un file con estensione .idx, in cui il comando \index può poi annotare le sue voci. Si osservi l'esempio seguente:

...
\usepackage{makeidx}
\makeindex
...
\begin{document}

\section{Prima} \index{resistenza}\index{induttanza}

Qui si parla di resistenze e di induttanze, bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla...

\section{Seconda} \index{capacità}

Qui si parla di capacità e simili, bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla...

\end{document}

Nella composizione finale, i comandi \index non producono alcun risultato e si comportano in modo simile al comando \label:

riferimenti

Dopo l'elaborazione normale con LaTeX si ottiene un file con estensione .idx, con il contenuto seguente:

\indexentry{resistenza}{1}
\indexentry{induttanza}{1}
\indexentry{capacit\`a}{1}
\indexentry{resistenza}{1}

Si può osservare che le voci sono state inserite nella sequenza in cui appaiono nel sorgente LaTeX, senza tenere conto di eventuali ripetizioni. Ma LaTeX non è nelle condizioni di usare questo file direttamente nell'elaborazione successiva; prima occorre riordinare e riorganizzare le voci attraverso il programma makeindex:

makeindex�nome_file_senza_estensione

Per esempio, se si sta facendo la composizione del file prova.tex, è sufficiente il comando:

$ makeindex prova

In questo modo, makeindex cercherà di leggere il file prova.idx (quello generato dall'elaborazione di LaTeX) e produrrà il file prova.ind, che, seguendo l'esempio, dovrebbe contenere quanto segue:

\begin{theindex}

  \item capacit\`a, 1

  \indexspace

  \item induttanza, 1

  \indexspace

  \item resistenza, 1

\end{theindex}

Come si può vedere, la voce resistenza contiene un riferimento unico, dal momento che si trovava due volte, ma nella stessa pagina finale.⁽¹⁾

Se il sorgente LaTeX contiene il comando \printindex, in quel punto viene inserito il contenuto del file con estensione .ind, a partire da una pagina nuova, con l'aggiunta di un titolo adeguato:

...
\usepackage{makeidx}
\makeindex
...
\begin{document}

\section{Prima} \index{resistenza}\index{induttanza}

Qui si parla di resistenze e di induttanze, bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla...

\section{Seconda} \index{capacità}

Qui si parla di capacità e simili, bla bla bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla...

\printindex

\end{document}

riferimenti

È da osservare che la voce indicata come argomento del comando \index può essere più articolata, in base alle capacità elaborative di makeindex. In pratica, si utilizzano dei simboli per separare la voce in più parti. L'elenco seguente dovrebbe aiutare a comprendere il meccanismo:

`\index{voce}`	questa è la situazione normale, in cui si inserisce la voce indicata, così come inserita, nell'indice;
`\index{voce_principale!voce_secondaria}`	il punto esclamativo permette di separare una voce principale da una parte secondaria, che poi può essere mostrata con un leggero rientro rispetto alla prima parte;
`\index{voce_principale@voce_abbellita}`	la chiocciola separa una prima parte, da prendere in considerazione ai fini dell'ordinamento, dalla seconda parte che invece viene mostrata nell'indice, consentendo l'uso di comandi che modificano l'aspetto del carattere;
`\index{voce\|comandi_per_il_numero_della_pagina}`	la barra verticale separa la voce dell'indice dai comandi per controllare l'aspetto del numero della pagina (comandi da usare senza la barra obliqua inversa iniziale).

L'esempio seguente è una variante di quanto già visto, per mostrare l'uso del comando \index con questi simboli particolari:

\section{Prima} \index{resistenza}\index{resistenza!induttiva|textit}

Qui si parla di resistenze e di induttanze, bla bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla...

\section{Seconda} \index{resistenza!capacitiva|textit}
\index{resistenza@\texttt{resistenza}}

Qui si parla di capacità e ancora di resistenza, bla bla bla bla bla bla
bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla bla
bla bla bla...

Ecco come si presenta l'indice; si può osservare che la voce resistenza appare due volte, perché il tipo di carattere è stato modificato:

riferimenti

242.4 Bibliografie

LaTeX offre una gestione molto semplice delle bibliografie attraverso l'uso dell'ambiente thebibliography. I comandi coinvolti sono descritti brevemente nell'elenco seguente:

`\begin{thebibliography}{stringa_di_esempio}...`_<-' ^`->`\end{thebibliography}`	dichiara l'ambiente che contiene le informazioni bibliografiche;
`\bibitem[sigla]{stringa_identificativa_della_voce}`	all'interno dell'ambiente `thebibliography` dichiara l'inizio di una voce bibliografica;
`\cite[testo_aggiuntivo{stringa_identificativa_della_voce}}`	si usa al di fuori dell'ambiente `thebibliography`, per richiamare il riferimento a una voce bibliografica.

In pratica, l'ambiente thebibliography serve a raccogliere le voci bibliografiche, ognuna dichiarata attraverso il comando \bibitem. Nel risultato della composizione, le voci vengono precedute da una sigla, come indicato dal comando \bibitem, oppure da un numero gestito in modo automatico; pertanto, per garantire un allineamento corretto, la dichiarazione dell'ambiente richiede un argomento composto da una stringa di esempio, che rappresenti l'ampiezza massima di questa sigla, sia gestita manualmente, sia automatica.

Al di fuori dell'ambiente thebibliography, di solito prima di questo, si usa il comando \cite per fare riferimento a una voce bibliografica, attraverso la stringa identificativa che usa lo stesso comando \bibitem. Se viene usato l'argomento opzionale di \cite, si ottiene l'aggiunta di quella stringa dopo la sigla usata per identificarlo.

Per cominciare conviene mostrare un esempio molto semplice, in cui non si usano argomenti opzionali:

\section{Resistenze e condensatori}

Qui si parla di resistenze \cite{res} e di condensatori \cite{con}, bla
bla bla bla bla bla bla bla bla...

\begin{thebibliography}{99}
\bibitem{res} Tizio Tizi, \textit{Resistenze elettriche}, 2002
\bibitem{con} Caio Cai, \textit{Condensatori e correnti alternate}, 2001
\end{thebibliography}

Come si vede, l'argomento della dichiarazione dell'ambiente thebibliography contiene la stringa 99, perché si sa che la sigla usata per distinguere le voci non sarà mai più lunga di un numero di due cifre:

bibliografie

Volendo aggiungere un riferimento a una certa pagina del primo libro citato, basta sfruttare l'argomento opzionale di \cite:

Qui si parla di resistenze \cite[pag. 1]{res} e di condensatori
\cite{con}, bla bla bla bla bla bla bla bla bla...

bibliografie

Infine, per usare delle sigle più significative, si può sfruttare l'argomento opzionale del comando \bibitem, ma in questo caso occorre intervenire anche nella dichiarazione dell'ampiezza massima di queste stringhe:

\begin{thebibliography}{ZZZZZ}
\bibitem[TIZ]{res} Tizio Tizi, \textit{Resistenze elettriche}, 2002
\bibitem[COND]{con} Caio Cai, \textit{Condensatori e correnti alternate}, 2001
\end{thebibliography}

bibliografie

Come si intuisce, l'uso di riferimenti bibliografici di questo tipo richiede delle rielaborazioni successive, anche se in questo caso non intervengono programmi esterni.

Eventualmente, se questo tipo di gestione bibliografica si mostra insufficiente, è disponibile BibTeX, che consente di gestire una bibliografia molto dettagliata in un file esterno, dove solo le voci richieste espressamente vengono poi mostrate nella composizione finale.

1) Naturalmente, makeindex può essere usato anche specificando delle opzioni; in tal caso si può consultare la pagina di manuale makeindex(1).

Dovrebbe essere possibile fare riferimento a questa pagina anche con il nome latex_riferimenti.html