Cette série d'articles a pour but de démontrer que LaTeX est accessible au plus grand nombre, que LaTeX n'est pas élitiste et qu'avec un peu de bonne volonté et un coup de pouce, tout le monde peut s'en sortir. Ces articles assurent le coup de pouce aux débutants, à vous de fournir la volonté.
Ce mois-ci nous allons apprendre comment faire des références dans un document LaTeX.
La dernière fois j'avais annoncé les notes de bas de page et la table des matières au programme de ce présent article.
Une fois de plus je me suis fait submerger par la richesse de LaTeX.
Ce deux sujets sont donc reportés au mois prochain.
Promis, je vais faire des efforts de lucidité à l'avenir :).
Un peu de promotion pour débuter (une fois n'est pas coutume). Le 6 juillet dernier a eu lieu une install-party sur le campus d'Orsay (dans l'Essonne, en Ile-de-France) organisée par l'association Parinux. L'occasion a même permis la réalisation de conférences. L'une d'entre elles nous concerne car elle portait sur les formats de fichiers ouverts et sur la philosophie de TeX/LaTeX. Elle était animée par Thierry Stoehr de l'AFUL. Le tout a été filmé par Lionel Allorge (déjà présent avec sa caméra devant Richard Stallman à la dernière Linux-Expo) et un enregistrement audio se trouve sur son site FilmLibre.org. Les liens se trouve à la fin de l'article.
Lorsque vous lisez un ouvrage autre qu'un roman il arrive souvent de croiser au détour d'une ligne quelque chose comme "cf. chapitre 4 page 38". Pensez-vous que l'auteur ait écrit littéralement ces mots dans son document ? Imaginons que cette phrase se trouve dans le chapitre 2. Il décide de rajouter un nouveau chapitre à la suite du deuxième. Le chapitre 4 devient donc le 5. La référence écrite littéralement est devenue fausse. Comment faire alors ? Heureusement LaTeX est là pour s'en occuper à notre place.
Le principe est simple. Vous devez d'abord baliser le point que vous souhaitez référencer dans votre document. On va dire que vous "collez une étiquette" avec un nom dessus. Ensuite, quand vous aurez besoin d'y faire référence, plus loin dans le texte vous n'aurez qu'à citer "le numéro de section ou tout autre élément de division du document où se trouve mon étiquette unetelle" ou encore "le numéro de la page où se trouve l'étiquette".
Que demander de plus ? Comment fait-on techniquement ? J'y viens.
Placer une étiquette se fait au moyen de la commande \label{}.
Comme ceci :
\subsection{Références}
Je veux mettre une étiquette ici. \label{toto}
Et quand vous avez besoin de faire référence au numéro de section où se trouve l'étiquette toto, il faut utiliser la commande \ref{} :
Vous vous souvenez, je vous parlais de références (cf. section \ref{toto}).
Afin d'éviter au lecteur de refaire un tour par la table des matières pour retrouver la page où se trouve ladite section, il est de coutume d'indiquer le numéro de la page en même temps.
Cela se fait avec la commande \pageref{} qui fonctionne comme \ref{}.
Vous vous souvenez, je vous parlais de références
(cf. \ref{toto} page \pageref{toto}).
Notez bien que lorsque je parle de "section" cela est valable aussi pour les sous-sections, sous-sous-sections, paragraphes, chapitres, etc.
Il est intéressant de voir comment LaTeX fonctionne pour afficher correctement ces données. Lorsque vous compilez, LaTeX analyse votre source et, lorqu'il rencontre la commande \label{} il note dans un fichier le numéro de section et la page (les résultats que devront donner les commandes \ref{} et pageref{}) comme ceci par exemple :
\newlabel{toto}{{2.1}{3}}
Ce qui signifie : l'étiquette "toto" se trouve à la section 2.1 page 3. Ce fichier porte le même nom que votre source hormis l'extension qui est "aux" au lieu de "tex". C'est le fichier auxiliaire, en quelque sorte le carnet où LaTeX prend ses notes concernant votre document (pas seulement pour les références).
Lorsque LaTeX croise une commande \ref{} ou \pageref{} il consulte ce même fichier pour afficher la bonne information.
Mais que se passe-t-il si l'on fait référence à l'étiquette "toto" avant (sous-entendu en parcourant séquentiellement le document) de déclarer la fameuse étiquette ?
Et bien, ça coince.
Incapable de deviner l'information, LaTeX affiche deux points d'interrogation.
Par contre, une chose dont on peut être sûr, c'est qu'à la fin de l'analyse du source, LaTeX aura correctement informé le fichier auxiliaire.
Il ne reste plus qu'à lancer une deuxième analyse (compilation) pour que LaTeX produise un document complet.
Votre seule contrainte sera de veuiller à ne pas donner le même nom à deux étiquettes. Sinon LaTeX vous rappellera à l'ordre avec ce message d'erreur :
LaTeX Warning: There were multiply-defined labels.
Les noms des étiquettes peuvent contenir des lettres, des chiffres et des signes de ponctuation.
Ceci est la base. Voyons maintenant comment agrémenter le quotidien.
Les étiquettes ne sont normalement pas visibles dans le document produit. Mais il peut être utile de les afficher par souci de vérification (surtout pour retrouver d'éventuels doublons). Deux modules d'extension à LaTeX permettent cette tâche.
D'abord showlabels.
Le simple fait de l'inclure à votre source produit le résultat demandé :
cela signifie qu'il n'y a aucune commande à appeler et non que vous êtes dispensés de compilation.
Une fois inclus donc, showlabels affiche dans la marge de droite, au niveau de l'endroit où vous utilisez la commande \label{}, le nom de votre étiquette entouré d'une paire d'accolades et en police de type machine à écrire.
Ensuite showkeys. De même que showlabels, il ne nécessite pas d'autre action que d'être inclus au source. De même que showlabels, il affiche le nom des étiquettes, mais il le fait dans la marge gauche, entouré d'un cadre.
Et de plus, il rajoute le nom de l'étiquette au niveau des appels à \ref et \pageref, juste au-dessus du texte.
Le module showkeys accepte plusieurs options, parmi lesquelles notref.
Dans le cas où vous trouviez que l'affichage de l'étiquette au moment de l'appel de \ref et \pageref alourdit l'écriture ou tout simplement que cela vous dérange plus que cela ne vous arrange,
l'option notref permet justement de ne pas afficher le nom de l'étiquette dans ce cas-là.
De toute façon, ne perdez pas de vue que ce ne sont là que des outils de travail que vous ne laisserez pas dans la version finale.
Même si cela ne restera pas dans la version finale du document, cela ne doit pas vous empêcher d'en améliorer l'aspect visuel avec de la couleur. Pour cela, rajoutez l'option color à l'inclusion du module. Deux couleurs sont utilisables, labelkey pour les étiquettes en marge et refkey pour les références dans le texte. Avec LaTeX, les couleurs sont définies par des valeurs comprises entre 0 (noir) et 1 (couleur). Par défaut, ces deux couleurs sont du gris de valeur 0,75 (uniquement en utilisant l'option color, sinon, c'est du noir). Voici ces définitions par défaut :
\definecolor{refkey}{gray}{0.75}
\definecolor{labelkey}{gray}{0.75}
Mais vous pouvez les redéfinir et même employer de la couleur de type rgb, c'est à dire, définie par trois composantes : rouge, vert et bleu (dans cet ordre et séparées par des virgules). Les lignes suivantes définissent refkey comme du bleu pur et labelkey en rouge assombris, telles que vous pouvez les voir sur les captures précédentes.
\definecolor{refkey}{rgb}{0,0,1}
\definecolor{labelkey}{rgb}{0.6,0,0}
Mais le propos n'est pas aux couleurs et j'y reviendrai plus en profondeur dans un article ultérieur.
Et pour en terminer avec showkeys, l'option final.
Passée à l'inclusion de showkeys elle a pour but d'annuler son action.
Quel intérêt y a-t-il ?
On pourrait tout simplement supprimer la ligne.
Cela devient utile si l'on passe l'option final à la déclaration de type de document \documentclass (la première ligne de votre source).
En effet, certains modules ont en commun des options avec des classes de document.
Si une option est donnée pour une classe, alors elle est transmise aux modules inclus dans le source.
Si un module reconnaît l'option, il la considère.
Il est inutile d'utiliser à la fois showlabels et showkeys. Il faut donc choisir celui qui vous convient le mieux.
Le module lastpage a pour fonction de placer une étiquette sur la dernière page du document.
Pourquoi ne pas le faire soi-même en plaçant la commande \label{} juste avant le \end{document} ?
Certains modules peuvent produire de nouvelles pages en fin de document et vous n'avez aucun contrôle dessus.
C'est le cas du module endnotes que nous étudierons le mois prochain ; sa fonction est de créer des notes de fin de document.
Dans ce cas pas moyen de faire référence à la dernière page.
A moins d'utiliser l'étiquette placée par lastpage à la fin du traitement du source par LaTeX.
L'étiquette à laquelle faire référence porte le nom de LastPage (attention aux majuscules).
\pageref{LastPage}
Des conflits peuvent survenir entre plusieurs modules travaillant sur la fin du document. En effet, chacun peut considérer qu'après lui plus rien ne se passe. LaTeX exécutant les commandes dans l'ordre dans lequel elles lui sont données (c'est valable aussi pour les déclarations de modules), la solution consiste souvent à changer cet ordre.
Imaginons que vous fassiez référence à une étiquette se trouvant sur la même page. Attention, vous n'avez aucun moyen de savoir à l'avance que l'étiquette et la référence se trouveront sur la même page. Mais une fois le rendu effectué, c'est le cas. Peut-être auriez-vous aimé voir apparaître "voir sur cette même page" plutôt que "voir page 10" alors que l'on s'y trouve. De même si la page est la suivante ou la précédente.
Ce rêve est réalisable avec le module varioref.
Deux nouvelles commandes remplacent celles que nous connaissons déjà : \vref et \vpageref.
Ces commandes étant amenées à afficher du texte, dans quelle langue va-t-il sortir ?
C'est à vous de le choisir en donnant l'option qui va bien au module.
En l'occurence french ou francais (sans cédille) pour la langue française.
Suivant le cas de figure, la fonction \vref affiche :
\ref) ;
\ref puis \pageref séparés par le mot "page".
Attention, l'utilisation de la commande \vref est incompatible avec le module showkeys.
Nous verrons dans un prochain article, consacré à la mise en page, comment réaliser des documents à mise en page recto-verso.
Si vous ne souhaitez afficher que l'information de page, il faut utiliser la commande \vpageref.
Elle agit comme la commande précédente, sauf qu'elle n'imprime pas le numéro de section, et dans le cas où l'étiquette et la référence sont sur la même page, elle écrit les mots "de la présente page".
Notez que dans le cas où l'étiquette se trouve à plus de deux pages, \vpageref affiche logiquement le mot "page" devant le numéro de la page, contrairement à son homologue \pageref.
Le module varioref propose également de faire référence à une plage d'étiquettes.
Ceci afin d'obtenir une phrase du genre "voir les sections 2.2 à 2.4 pages 5-7".
Pour cela utilisez la commande \vrefrange{}{} qui prend deux paramètres : l'étiquette de début et celle de fin.
... voir les sections \vrefrange{toto1}{toto4}.
Où toto1 et toto4 sont des étiquettes.
Bien sûr, comme \vref, \vrefrange remplace les numéros de pages par du texte explicite si le besoin s'en fait sentir.
Uniquement, si les deux étiquettes se trouvent sur la même page (pas forcément la même que la référence).
Ainsi on aura : "voir les sections 2.2 à 2.4 page précédente / de la présente page / page suivante / page ci-contre".
Naturellement on dispose de la commande \vpagerefrange.
Cette commande est identique à la précédente hormis qu'elle ne donne pas le ou les numéros de section.
On arrive maintenant à la partie personnalisation. Et oui, vous pouvez changer les textes retournés par varioref. Chaque texte est tributaire d'une commande. Redéfinissons les commandes.
Par exemple, la commande \reftextcurrent qui est appelée lorsque vous faites référence à une étiquette située sur la page précédente.
Redéfinissons.
\renewcommand{\reftextcurrent}{sur cette même page}
"de la présente page" devient donc "sur cette même page".
Voici la liste des autres commandes :
\renewcommand{\reftextfaraway}[1]
{à la page~\pageref{#1}}
Lorsque varioref appelle cette commande, il lui donne le nom de l'étiquette.
Ce nom est ensuite passé à \pageref qui renvoie le numéro de la page.
Le symbole tilde "~" représente un espace insécable.
De ce fait, le mot "page" et le numéro ne seront jamais séparés par une fin de ligne.
Nous y reviendrons dans un article consacré aux espaces et mesures.
\reftextfaraway elle prend donc deux paramètres.
Voici un exemple :
\renewcommand{\reftextpagerange}[2]
{pages~\pageref{#1} jusqu'à~\pageref{#2}}
\renewcommand{\reftextlabelrange}[2]
{\ref{#1} jusqu'à~\ref{#2}}
Et pour aller encore plus loin, on peut rajouter une variation à l'intérieur d'une même commande.
Par exemple, je voudrais que la commande \reftextcurrent me donne tantôt "sur cette même page" et tantôt "de la présente page".
La commande \reftextvario propose ce choix et vous pourrez écrire ceci :
\renewcommand{\reftextcurrent}
{\reftextvario{sur cette même page}{de la présente page}}
Vous ne pouvez avoir que deux possibilités.
Le choix est fait en fonction du nombre d'appels qui ont été fait à la commande \ref précédemment.
Si ce nombre est impair, le premier paramètre est choisi, sinon c'est l'autre.
Encore un détail : la commande \vref, à chaque fois qu'elle est utilisée, crée en interne deux macros avec à chaque fois des noms différents.
Si vous faites un usage massif de cette commande, vous pouvez épuiser l'espace de noms en mémoire.
Aussi, dans les cas où vous êtes sûrs que l'étiquette se trouve loin de la référence, vous pouvez utiliser la commande \fullref à la place.
Elle est équivalente à \vref dans le cas d'éloignement des deux protagonistes.
Et elle ne crée aucune macro.
Pour information sa définition est la suivante :
\newcommand{\fullref}[1]
{\ref{#1} \reftextfaraway{#1}}
Un dernier petit module pour la route avant de se quitter pour un mois. Le module xr (pour eXternal Reference) permet de faire référence à une étiquette déclarée dans un autre document (ou même plusieurs).
Après avoir déclaré xr dans le préambule de votre source, il faut déclarer le ou les documents auxquels vous voulez faire référence.
Cela se fait avec la commande \externaldocument.
Les noms de fichier doivent être écrits sans l'extension ".tex".
Si je veux faire référence à une étiquette placée dans mon article sur les tableaux, j'écrirai :
\externaldocument{../tableaux/latex}
Le document, "latex.tex" se trouve dans le répertoire "tableaux", au même niveau que le répertoire courant. Dans ce document, j'y ai placé une étiquette "toto" (une vieille habitude de programmeur fait que j'en mets de partout) à laquelle je veux faire référence ici.
Je tape donc dans le présent article :
La base des tableaux : section \ref{toto} page \pageref{toto}
Que va-t-il se passer ? Sachant que par abondance d'inspiration, j'ai déjà placé une étiquette "toto" dans le présent document, j'obtiens un joli message d'alerte me disant que l'étiquette est déclarée plusieurs fois. Et cela peut aussi vous arriver à vous qui n'appelez pas toutes vos étiquettes "toto".
Que faire ? Modifier le nom de l'étiquette dans le fichier externe ? Et si j'y fais référence ailleurs dans ce même fichier externe.
Non, la solution est donnée par la commande \externaldocument qui accepte un paramètre optionnel.
Ce paramètre est un préfixe servant à renommer l'étiquette pour le document faisant référence.
Nous déclarons dans le présent document vouloir faire références aux étiquettes de l'article sur les tableaux :
\externaldocument[4-]{../tableaux/latex}
Cela signifie que toutes les étiquettes du document externe ("les tableaux") devront être préfixées par "4-" lorsqu'elles sont référencées dans le présent document ("les références"). Aucune modification n'est faite dans le document externe.
Reprenons la référence faite précédemment, cette fois-ci n'engendrant pas d'erreur :
La base des tableaux : section \ref{4-toto} page \pageref{4-toto}
Ce qui donne : "La base des tableaux : section 1 page 1".
Lors du prochain épisode nous traiterons les notes de bas de page, et on essaiera de parler de table des matières.
N'hésitez pas à me faire part de vos remarques, reproches, conseils par e-mail.
.tex) regroupant votre texte ainsi que les commandes de mise en forme. Le fichier est donc dénommé "fichier source".
\usepackage[option(s)_facultative(s)]{nom(s)_module(s)}
Si plusieurs noms ou plusieurs options sont donnés, ils sont séparés par des virgules.