> For the complete documentation index, see [llms.txt](https://overleaf-pro.ayaka.space/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://overleaf-pro.ayaka.space/latex/fr/base-de-connaissances/033-cross-referencing-with-the-xr-package-in-overleaf.md). # Références croisées avec le package xr dans Overleaf ## Présentation Le [`xr` package](https://ctan.org/pkg/xr?lang=en) vous permet de créer des références croisées vers des équations, des figures, des tableaux, etc. contenus dans des documents LaTeX externes, à condition que ces documents soient *autonomes.* Un document LaTeX autonome est un document qui peut être compilé parce qu’il contient une `\documentclass{...}` déclaration et la `\begin{document}`...`\end{document}` structure. ### Résumé d’utilisation 1. Écrivez `\usepackage{xr}` dans le préambule du fichier LaTeX qui doit faire des références croisées à du contenu contenu dans des fichiers LaTeX externes. 2. Utilisez la `xr` commande du package `\externaldocument{filename}` pour spécifier le ou les document(s) externes dont vous voulez référencer le contenu. Le `xr` Le package fonctionne en utilisant des étiquettes de références croisées contenues dans les fichiers `.aux` générés lorsque les documents LaTeX externes sont compilés. ### Comment fonctionnent les références croisées (résumé bref) Pour faire une référence croisée à un élément dans un document LaTeX, vous devez : 1. Lui donner un identifiant unique, `some_string`, en utilisant la `\label` commande : ```latex \label{some_string} ``` 3. À l’endroit où vous voulez faire référence à cet élément, vous devez écrire ```latex \ref{some_string} ``` En très bref, LaTeX gère les références croisées en écrivant des données dans un fichier appelé `filename.aux` où `filename` est le nom du `.tex` fichier principal en cours de compilation. Pour que le processus fonctionne, le document LaTeX doit être compilé au moins deux fois : la première compilation *génère* les données de référence — en les écrivant dans `filename.aux`. Lors de la deuxième compilation, LaTeX *lit* `filename.aux` pour résoudre les références, en fournissant des données pour remplacer les occurrences de `\ref{some_string}`. * Pour plus de détails sur les références croisées, voir l’article Overleaf [Référencer des sections, des équations et des flottants](/latex/fr/structure-du-document/03-cross-referencing-sections-equations-and-floats.md). ## Projets où le package xr n’est pas nécessaire Les grands projets LaTeX, comme les livres ou les longs rapports, sont souvent divisés en une série de `.tex` fichiers plus petits, un par chapitre, avec le `.tex` fichier de chaque chapitre ajouté au document LaTeX principal à l’aide de `\input` ou `\include`. En général, ces chapitres ne sont pas autonomes : vous ne pouvez pas compiler les chapitres individuellement parce qu’ils ne contiennent pas de `\documentclass{...}` déclaration ou la `\begin{document}...\end{document}` structure. Ces chapitres sont destinés à être *inclus* dans un document « conteneur » qui *peut* être compilé. Dans ces circonstances, les références croisées vers des éléments du document — dans n’importe quel fichier de chapitre individuel — peuvent se faire normalement : vous n’avez pas besoin d’utiliser le `xr` package. Pour explorer un exemple de grand projet, vous pouvez [ouvrir cet exemple dans Overleaf.](https://www.overleaf.com/project/new/template/20618?id=70769185\&templateName=Managing+a+large+project+on+Overleaf\&latexEngine=pdflatex\&texImage=texlive-full%3A2020.1\&mainFile=) ## Exemple d’un projet où le package xr est requis Supposons que vous ayez un ensemble de documents LaTeX autonomes, par exemple une collection de N articles : `article1.tex`, `article2.tex` ... `articleN.tex`. Chacun de ces articles peut être compilé séparément et il est probable qu’ils aient été écrits en utilisant विभिन्न classes de documents, packages, etc. Imaginez maintenant que vous vouliez utiliser LaTeX pour écrire une vue d’ensemble ou un résumé de ces articles — appelons notre fichier `summary.tex`. Notre résumé doit faire référence à des sections, des figures, des tableaux, des équations, etc. contenus dans ces articles individuels et autonomes, N. Comment faire ? Le `xr` Le package vous permet de faire cela : il permet `summary.tex` d’utiliser des étiquettes de référence générées par n’importe lequel des `articles*.tex` autonomes. ### Une remarque sur les fichiers .aux * Notez qu’ici nous utilisons un astérisque (`*`) comme espace réservé pour n’importe quel nombre de 1 à N. La compilation de n’importe lequel des fichiers autonomes `article1.tex`, `article2.tex` ... `articleN.tex` amène LaTeX à générer un `article*.aux` (\*\*`fichier`auxiliaire qui, entre autres, contient les données d’étiquettes nécessaires pour générer des références croisées. Si l’un quelconque des `articles*.tex` fichiers est modifié — par exemple pour changer, ajouter ou supprimer des étiquettes (`\label{...}`) — le ou les `articles*.tex` fichiers correspondants doivent être recompilés pour mettre à jour les `article*.aux` fichier(s). Détecter les changements apportés à `articles*.tex`et les recompiler ensuite peut être automatisé sur Overleaf à l’aide d’un `latexmkrc` fichier. ## Comment utiliser xr sur Overleaf Nous utiliserons une version simplifiée de notre exemple à plusieurs articles ; en particulier, nous montrons comment automatiser le processus de compilation via un `latexmkrc` modifiable [fourni à Overleaf par John Collins](#code-for-latexmkrc) ([mainteneur de `latexmk`](https://ctan.org/pkg/latexmk?lang=en)). ### Fichiers utilisés dans notre exemple Notre exemple utilise les fichiers suivants : * `**summary.tex**`: c’est notre document de synthèse. Nous en avons besoin pour faire référence au contenu contenu dans `article1.tex`, comme les figures et les sections. * `summary.tex` charge le `xr` package et utilise `\externaldocument{article1}` pour indiquer que les données de référence de `article1.aux` doivent être utilisées. * `**article1.tex**`: un seul article autonome contenant des références croisées internes. La compilation de `article1.tex` génère des données de références croisées contenues dans le fichier `article1.aux`. * Un fichier externe comme `article1.tex` qui aurait pu être écrit par quelqu’un d’autre — pour que vous puissiez l’utiliser « tel quel », c’est-à-dire sans le modifier. * `**latexmkrc**`: contient du code (Perl) pour automatiser la recompilation de `article1.tex` en raison de toute modification qui lui est apportée — afin de créer un `article1.aux` fichier. * Notre `latexmkrc` fichier était [fourni à Overleaf par John Collins](#code-for-latexmkrc) ([mainteneur de `latexmk`](https://ctan.org/pkg/latexmk?lang=en)). ### À propos de la commande \externaldocument Le `xr` package fournit la`\externaldocument` commande, dont la forme générale est ```latex \externaldocument[prefix]{external_file} ``` * **`prefix` (facultatif) :** Cet argument facultatif vous permet de définir un préfixe qui sera ajouté à toutes les étiquettes importées depuis le document externe. Cela est utile pour éviter les conflits si les mêmes noms d’étiquettes sont utilisés dans plusieurs documents. * **`external_file` (obligatoire) :** Cet argument obligatoire spécifie le nom du document LaTeX externe (sans l’ `.tex` extension) à partir duquel vous voulez importer des références. Le `xr` package cherchera le `.aux` fichier correspondant à `external_file` (par exemple, `external_file.aux`) pour récupérer les étiquettes. À titre d’exemple, si notre document principal `.tex` modifiable `summary.tex` et le fichier externe, `article1.tex` contiennent tous deux l’étiquette `\label{eq:1}` alors nous avons un conflit de noms d’étiquettes. Ce conflit peut être évité en écrivant ```latex \externaldocument[art1-]{article1} ``` dans ce cas, toutes les étiquettes créées en compilant `article1.tex` sont précédées de `art1-`. Vous pouvez maintenant accéder à `\label{eq:1}`, contenue dans `article1.tex`, en écrivant `\ref{art1-eq:1}` dans `summary.tex`. ### Les fichiers du projet #### article1.tex Le code suivant peut être ouvert dans Overleaf à l’aide du lien situé sous la liste. ```latex \documentclass{article} \title{Voici \texttt{article1.tex}} \begin{document} \section{Introduction} \label{introduction} Ceci est un document \LaTeX{} autonome avec des références que nous voulons utiliser dans \texttt{summary.tex}. \subsection{Math references} \label{mathrefs} Comme mentionné dans la section \ref{introduction}, différents éléments peuvent être référencés dans un document. \subsection{Powers series} \label{powers} \begin{equation} \label{eq:1} \sum_{i=0}^{\infty} a_i x^i \end{equation} L’équation \ref{eq:1} est une série de puissances typique. \end{document} ``` [Ouvrir `article1.tex` dans Overleaf](https://www.overleaf.com/docs?engine=%5B%5B%3ATemplate%3AEngine%5D%5D}\&snip_name\[]=readme.txt\&snip\[]=A+project+created+from+the+Overleaf+wiki\&snip_name\[]=article1.tex\&main_document=article1.tex\&snip\[]=%5Cdocumentclass%7Barticle%7D%0A%5Ctitle%7BThis+is+%5Ctexttt%7Barticle1.tex%7D%7D%0A%5Cbegin%7Bdocument%7D%0A%5Csection%7BIntroduction%7D%0A%5Clabel%7Bintroduction%7D%0A%0AThis+is+a+standalone+%5CLaTeX%7B%7D+document+with%0Areferences+we+want+to+use+in+%5Ctexttt%7Bsummary.tex%7D.%0A%0A%5Csubsection%7BMath+references%7D%0A%5Clabel%7Bmathrefs%7D%0AAs+mentioned+in+section+%5Cref%7Bintroduction%7D%2C+%0Adifferent+elements+can+be+referenced+within%0Aa+document.%0A%0A%5Csubsection%7BPowers+series%7D%0A%5Clabel%7Bpowers%7D%0A%0A%5Cbegin%7Bequation%7D%0A%5Clabel%7Beq%3A1%7D%0A%5Csum_%7Bi%3D0%7D%5E%7B%5Cinfty%7D+a_i+x%5Ei%0A%5Cend%7Bequation%7D%0A%0AEquation+%5Cref%7Beq%3A1%7D+is+a+typical+power+series.%0A%5Cend%7Bdocument) La compilation `article1.tex` produit la sortie suivante : ![Sortie produite par la compilation du fichier article1.tex dans Overleaf](/files/36629eeefb430e837702523da4741d48eb0d5e6d) #### summary.tex Voici notre `summary.tex` modifiable *avant* nous avons indiqué quel document externe nous voulons référencer. Pour simplifier, `summary.tex` ne contient aucune `\label` commande, car il n’y a pas de références croisées internes. Toutes les `\ref` commandes font référence aux étiquettes générées par les `\label` commandes contenues dans `article1.tex`. ```latex \documentclass{article} \usepackage{xr} \title{Voici \texttt{summary.tex}} \begin{document} Dans le fichier \texttt{article1.tex}, l’introduction est la section \ref{introduction}. Dans ce fichier, il y a deux sous-sections : \ref{mathrefs} et \ref{powers}. Dans la sous-section \ref{powers}, l’équation \ref{eq:1} démontre une série de puissances. \end{document} ``` [Ouvrez cet *incomplet* `summary.tex` dans Overleaf](https://www.overleaf.com/docs?engine=%5B%5B%3ATemplate%3AEngine%5D%5D}\&snip_name\[]=readme.txt\&snip\[]=A+project+created+from+the+Overleaf+wiki\&snip_name\[]=summary.tex\&main_document=summary.tex\&snip\[]=%5Cdocumentclass%7Barticle%7D%0A%5Cusepackage%7Bxr%7D%0A%5Ctitle%7BThis+is+%5Ctexttt%7Bsummary.tex%7D%7D%0A%5Cbegin%7Bdocument%7D%0AIn+the+file+%5Ctexttt%7Barticle1.tex%7D%2C+the+introduction+is+section+%5Cref%7Bintroduction%7D.++In+that+file%2C+there+are+two+subsections%3A+%5Cref%7Bmathrefs%7D+and+%5Cref%7Bpowers%7D.+In+subsection+%5Cref%7Bpowers%7D%2C+equation+%5Cref%7Beq%3A1%7D+demonstrates+a+power+series.%0A%5Cend%7Bdocument%7D) Si nous compilons cette version de `summary.tex` elle tentera de lire les données de référence à partir de `summary.aux` mais les données requises se trouvent dans le fichier externe `article1.aux` auquel on ne peut pas encore accéder. La compilation de ce `summary.tex` fichier incomplet produit la sortie suivante, avec des doubles points d’interrogation indiquant des références non définies : ![Image montrant le signalement de références manquantes](/files/a0d7cd592e83dcc004bed33a65e3374072a4c760) ### Spécifier le document externe L’étape suivante consiste à spécifier `article1` comme nom du document externe dont nous voulons référencer les étiquettes. Ajoutez la ligne suivante au préambule de `summary.tex`: ```latex \externaldocument{article1} ``` Ici, `article1` peut être remplacé par n’importe quel fichier dont vous voulez accéder aux étiquettes — vous pouvez utiliser plusieurs `\externaldocument` commandes pour accéder à des fichiers externes supplémentaires. ### Créer le fichier latexmkrc L’étape suivante consiste à créer un `latexmkrc` fichier comme indiqué ci-dessous : * Dans la fenêtre de l’éditeur de votre projet, sélectionnez l’icône **Nouveau fichier** en haut à gauche de la fenêtre du projet. * Sélectionnez **Nouveau fichier** depuis la boîte de dialogue contextuelle **Ajouter des fichiers** et nommez le fichier `latexmkrc`— notez qu’il n’y a pas d’extension de fichier : ![Création d’un fichier latexmkrc dans Overleaf](/files/7a58e5588c7b3ae1bd223e7736df767768be91f7) * Assurez-vous que le `latexmkrc` fichier créé et enregistré se trouve au niveau supérieur (racine) de l’espace des fichiers du projet. Autrement dit, pas à l’intérieur d’un dossier de l’arborescence des fichiers. * Copiez et collez le code suivant dans votre `latexmkrc` fichier. #### Code du fichier latexmkrc Overleaf remercie John Collins, [mainteneur de `latexmk`](https://ctan.org/pkg/latexmk?lang=en), pour nous avoir contactés afin de fournir le fichier `latexmkrc` suivant, que nous sommes ravis de publier intégralement — y compris les commentaires en ligne extrêmement utiles. ```perl # Ceci montre comment utiliser le package xr avec latexmk. # John Collins 2023-03-29 # # Le package xr (« un système pour les références externes ») est utilisé par un document # pour faire des références à des sections, des équations, etc. dans d’autres # documents externes. # Les définitions de ce fichier permettent à latexmk d’appliquer latexmk à # mettre automatiquement à jour un document externe chaque fois que son fichier .tex change, # afin que les références dans le document principal restent à jour. # Remarques : # 1. Cette version est définie pour placer les fichiers issus des compilations des # documents externes dans un sous-répertoire défini, afin de séparer # potentiellement de nombreux fichiers générés des répertoires # du document principal. # 2. Mais pour que le mécanisme de dépendance personnalisée de latexmk soit utilisé, comme ici, # le fichier aux issu de la compilation d’un sous-document doit être généré dans # le même répertoire que le fichier source .tex correspondant. Donc le # fichier .aux est copié. # 3. Il est supposé que les documents externes doivent être compilés avec # pdflatex. Cela peut bien sûr être modifié en changeant l’option « -pdf » # fournie à latexmk invoqué vers ce qui est nécessaire. # 4. Une implémentation idéale veillerait aussi à ce que la recompilation d’un # document externe se produise aussi chaque fois que l’un de ses autres # fichiers source change. Mais ce n’est pas fait dans la version actuelle, et # cela impliquerait probablement soit l’utilisation de variables internes de latexmk # soit des améliorations supplémentaires à latexmk. # 5. Le code utilise les sous-routines copy et fileparse qui sont chargées par # latexmk depuis les packages Perl File::Copy et File::Basename. # 6. Il utilise aussi certaines fonctionnalités de latexmk non encore documentées : un tableau # variable @file_not_found et les sous-routines popd, pushd, et # rdb_add_generated. #-------------------- # Choix configurables pour la compilation des documents externes # Sous-répertoire pour les fichiers de sortie issus de la compilation des documents externes : $sub_doc_output = 'output-subdoc'; # Options à fournir à latexmk pour la compilation des documents externes : @sub_doc_options = (); push @sub_doc_options, '-pdf'; # Utiliser pdflatex pour la compilation des documents externes. # Remplacez « -pdf » par « -pdfdvi », « pdfxe » ou « pdflua » si nécessaire. #-------------------- # Ajouter un motif pour le message du journal xr concernant les fichiers manquants à la # liste. La variable @file_not_found de latexmk n’est pas encore documentée. # Cette ligne n’est pas nécessaire pour la version 4.80 ou ultérieure de latexmk. push @file_not_found, '^No file\\s*(.+)\s*$'; add_cus_dep( 'tex', 'aux', 0, 'makeexternaldocument' ); sub makeexternaldocument { if ( $root_filename ne $_[0] ) { my ($base_name, $path) = fileparse( $_[0] ); pushd $path; my $return = system "latexmk", @sub_doc_options, "-aux-directory=$sub_doc_output", "-output-directory=$sub_doc_output", $base_name; if ( ($sub_doc_output ne '') && ($sub_doc_output ne '.') ) { # Dans ce cas, le fichier .aux généré par pdflatex n’est pas dans le même # répertoire que le fichier .tex. # Par conséquent : # 1. Le fichier aux réellement généré doit être सूचीé comme produit par cette # règle, afin que latexmk gère correctement les dépendances. # (Problème à résoudre : si $sub_dir_output est identique à $aux_dir # pour le document principal, xr peut lire le fichier .aux dans le # aux_dir plutôt que celui que la dépendance personnalisée est censée produire selon latexmk, # qui se trouve dans le même répertoire que le fichier source .tex # pour cette dépendance personnalisée.) # Utiliser la sous-routine latexmk non encore documentée rdb_add_generated # pour faire cela : # 2. Une copie du fichier .aux doit se trouver dans le même répertoire que le fichier .tex # pour satisfaire à la définition d’une dépendance personnalisée de latexmk. rdb_add_generated( "$sub_doc_output/$base_name.aux" ); copy "$sub_doc_output/$base_name.aux", "."; } popd; return $return; } } ``` ### Ouvrir un projet Overleaf démontrant xr Le projet suivant, composé de trois fichiers, peut maintenant être ouvert dans Overleaf à l’aide des liens fournis au-dessus et au-dessous des listes de fichiers. Notez que le `latexmkrc` fichier contient le code fourni par John Collins mais, par souci de brièveté, la plupart des commentaires ont été supprimés. [Ouvrir cet exemple à trois fichiers dans Overleaf.](/latex/fr/base-de-connaissances/033-cross-referencing-with-the-xr-package-in-overleaf.md) **summary.tex** Voici notre fichier de synthèse. Depuis ce fichier, nous voulons utiliser des références croisées créées dans des fichiers externes. Ici, nous voulons utiliser des étiquettes générées dans `article1.tex`. ```latex \documentclass[12pt]{article} \usepackage{xr} \title{Utiliser le package xr sur Overleaf} % mettre tous les documents externes ici ! \externaldocument{article1} \begin{document} Dans le fichier \texttt{article1.tex}, l’introduction est la section \ref{introduction}. Dans ce fichier, il y a deux sous-sections : \ref{mathrefs} et \ref{powers}. Dans la sous-section \ref{powers}, l’équation \ref{eq:1} démontre une série de puissances. \end{document} ``` **article1.tex** Ce fichier est l’un de nos articles. Remarquez qu’il contient diverses `\label` commandes pour créer des étiquettes qui, grâce au `xr` package, nous pouvons utiliser dans le fichier `summary.tex`. ```latex \documentclass{article} \title{Voici \texttt{article1.tex}} \begin{document} \section{Introduction} \label{introduction} Ceci est un document \LaTeX{} autonome avec des références que nous voulons utiliser dans \texttt{summary.tex}. \subsection{Math references} \label{mathrefs} Comme mentionné dans la section \ref{introduction}, différents éléments peuvent être référencés dans un document. \subsection{Powers series} \label{powers} \begin{equation} \label{eq:1} \sum_{i=0}^{\infty} a_i x^i \end{equation} L’équation \ref{eq:1} est une série de puissances typique. \end{document} ``` **latexmkrc** Ce `latexmkrc` fichier contient du code pour garantir que les fichiers externes sont compilés. ```latex $sub_doc_output = 'output-subdoc'; @sub_doc_options = (); push @sub_doc_options, '-pdf'; # Utiliser pdflatex pour la compilation des documents externes. # Remplacez « -pdf » par « -pdfdvi », « pdfxe » ou « pdflua » si nécessaire. push @file_not_found, '^No file\\s*(.+)\s*$'; add_cus_dep( 'tex', 'aux', 0, 'makeexternaldocument' ); sub makeexternaldocument { if ( $root_filename ne $_[0] ) { my ($base_name, $path) = fileparse( $_[0] ); pushd $path; my $return = system "latexmk", @sub_doc_options, "-aux-directory=$sub_doc_output", "-output-directory=$sub_doc_output", $base_name; if ( ($sub_doc_output ne '') && ($sub_doc_output ne '.') ) { rdb_add_generated( "$sub_doc_output/$base_name.aux" ); copy "$sub_doc_output/$base_name.aux", "."; } popd; return $return; } } ``` [Ouvrir cet exemple à trois fichiers dans Overleaf.](/latex/fr/base-de-connaissances/033-cross-referencing-with-the-xr-package-in-overleaf.md) Le graphique suivant est une version annotée de la sortie obtenue en composant `summary.tex`, montrant les références croisées et les étiquettes correspondantes du fichier externe `article1.tex`. ![Affichage des références importées depuis un fichier externe](/files/fd51152fd8691b35cd9e14b7c18fb0b148b08ff4) * Pour plus de détails sur les références croisées, voir l’article Overleaf [Référencer des sections, des équations et des flottants](/latex/fr/structure-du-document/03-cross-referencing-sections-equations-and-floats.md). ## Une remarque sur les erreurs de syntaxe Pour le fichier principal de votre projet, vous pouvez utiliser le mode de compilation Overleaf [Arrêter à la première erreur](/latex/fr/base-de-connaissances/149-using-the-stop-on-first-error-compilation-mode.md) afin de s’assurer que la compilation s’arrête immédiatement dès la détection de la première erreur. Cela peut aider à isoler et identifier les erreurs dans votre code, plutôt que de laisser les erreurs se propager, ce qui rend bien plus difficile la recherche et le débogage des problèmes. Le *documents* externes sont compilés automatiquement via le `latexmkrc` fichier ; par conséquent, toute erreur de syntaxe LaTeX à l’intérieur de ceux-ci n’apparaîtra pas dans l’interface Overleaf — à moins que vous ne les recompiliez aussi dans Overleaf. Des erreurs dans ces fichiers externes pourraient empêcher l’affichage correct des références croisées dans le fichier PDF composé. Nous vous recommandons donc vivement de vérifier et de corriger ces erreurs dès qu’elles se produisent. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://overleaf-pro.ayaka.space/latex/fr/base-de-connaissances/033-cross-referencing-with-the-xr-package-in-overleaf.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.