TeX e LaTeX

Ipertesti. Il pacchetto hyperref

Introduzione

Uno dei punti di forza dei documenti elettronici è la possibilità di avere dei collegamenti (link) tra le varie parti del documento o verso file o indirizzi esterni.

In LaTeX questo è possibile usando il pacchetto hyperref. Il nome deriva da hypertext (ipertesto) e ref (il comando LaTeX per i riferimenti interni al testo).

Caricando semplicemente il pacchetto senza alcuna opzione (\usepackage{hyperref}) tutti i riferimenti incrociati del testo diventeranno dei collegamenti cliccabili (indice, riferimenti tra parti del testo, riferimenti verso figure e tabelle, riferimenti verso la bibliografia).

Hyperref mette a disposizioni anche alcuni comandi per definire dei link verso indirizzi internet o file esterni oppure semplicemente aumentare le possibilità dei link interni. Tra questi \href{URL}{testo}, \url{URL}, \nolinkurl{URL}, \hyperbaseurl{URL}, \autoref{label}, \autopageref{label}, \ref*{label},\pageref*{label},\autoref*{label}, \autopageref*{label}. È inoltre molto comodo definire il comando \mail{indirizzo} in questo modo nel preambolo: \newcommand{\mail}[1]{\href{mailto:#1}{\texttt{#1}}}.

Le opzioni

Tra le opzioni figurano per primi i driver. Se non ne viene specificato alcuno, viene usato HyperTeX (non ho capito se compilando con PdfTeX hyperref capisce da solo oppure va specificato pdftex tra le opzioni). Invece le opzioni più utili sono:

Attenzione! Il driver, bookmarks e hyperfootnotes vanno specificati quando si richiama il pacchetto. Le altre opzioni invece sia quando si richiama il pacchetto sia usando hypersetup.

\usepackage[bookmarks=false,hyperfootnotes=false]{hyperref}
\hypersetup{
			colorlinks=true,
			linkcolor=black,
			anchorcolor=black,
			citecolor=black,
			urlcolor=black,
			pdftitle={Defects and Doping in Cu2O},
			pdfauthor={Francesco Biccari},
			pdfkeywords={cuprous oxide, Cu2O, doping, defects, metastability}
}

I segnalibri (bookmarks)

Con l'opzione bookmarks=true, attiva di default, hyperref genererà anche l'albero dei segnalibri che compare in un apposito menù del vostro programma per vedere i pdf (questa funzione è oramai supportata da qualunque lettore pdf). Di default i segnalibri rispecchieranno l'indice del vostro documento.

C'è però un problema riguardante i caratteri utilizzabili in questi segnalibri. Essendo puro testo, non possono contenere codice TeX. Hyperref però prende come testo per i bookmark il titolo della sezione a cui si riferiscono. Ad esempio \chapter{Introduzione} produrrà un bookmark dal nome Introduzione. Se però nel titolo compare del codice TeX, ad esempio \section{Equazioni di secondo grado: $ax^2+bx+c=0$}, il bookmark prodotto funzionerà (cioè punterà alla sezione corretta), ma avrà un nome come Equazioni di secondo grado: ax^2+bx+c=0. Fin qui poco male. Infatti hyperref cerca di ripulire il più possibile il codice TeX (La macro usata da hyperref per ripulire il codice è accessibile anche agli utenti e si chiama \pdfstringdef{macroname}{TEXstring}. Restituisce un comando che stampa il testo del codice TeX elaborato).

Se però nei titoli usate comandi di qualche pacchetto non contemplato da hyperref, verrano stampati una serie di caratteri strani anche se il bookmark continuerà a funzionare correttamente. Se vi trovate in questa situazione oppure non vi accontentate della ripulitura di hyperref potete usare il comando \texorpdfstring{TEXstring}{PDFstring}, che permette di specificare il testo che andrà usato da LaTeX e il testo che verrà usato da hyperref per comporre i bookmark.

L'utilità di questo comando sta nel fatto che può prendere come PDFstring tutti i caratteri della codifica PDFDocEncoding (abbreviata in PD1) che è la codifica di default per i bookmark. La PD1 contiene tutto l'iso-8859-1 più altri caratteri. Volendo si possono usare molti più caratteri grazie all'altra codifica disponibile, Unicode (abbreviata in PU), attivabile con l'opzione unicode=true. Per vedere quali caratteri si possono inserire (copiando e incollando oppure usando lo specifico comando \text... dove al posto dei puntini va messo il nome del carattere) si devono vedere i file pd1enc.def e puenc.def per la codifica PD1 e PU rispettivamente.

Cose da sapere

Quando si aggiunge manualmente una voce all'indice (\tableofcontents) si usa solitamente il comando \addcontentsline{toc}{<tipo sezione>}{<nome sezione>}. Ad esempio per aggiungere la Bibliografia nell'indice si scrive \addcontentsline{toc}{chapter}{\bibname}.
Purtroppo quando si usa hyperref quest'aggiunta manuale di voci nell'indice crea dei problemi nei link interni al documento (cliccando su una voce dell'indice si viene rimandati ad una pagina sbagliata). Per ovviare a questo inconveniente (per capire come funziona consultate il manuale di hyperref) bisogna usare il comando \phantomsection.
Ecco un esempio: il tipico codice per inserire la bibligrafia con BibTeX.

\cleardoublepage
\phantomsection % notare l'uso di phantomsection se si usa hyperref
\addcontentsline{toc}{chapter}{\bibname}
\bibliographystyle{abbrv}
\bibliography{bibliodata}