> 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/ru/baza-znanii/033-cross-referencing-with-the-xr-package-in-overleaf.md). # Перекрёстные ссылки с пакетом xr в Overleaf ## Обзор Этот [`xr` пакет](https://ctan.org/pkg/xr?lang=en) позволяет создавать перекрёстные ссылки на уравнения, рисунки, таблицы и т. д., содержащиеся во внешних документах LaTeX, при условии, что эти документы *самодостаточны.* Самодостаточный документ LaTeX — это такой документ, который можно скомпилировать, потому что он содержит `\documentclass{...}` инструкцию и `\begin{document}`...`\end{document}` конструкцию. ### Краткое руководство по использованию 1. Напишите `\usepackage{xr}` в преамбуле файла LaTeX, которому нужно делать перекрёстные ссылки на содержимое, находящееся во внешних файлах LaTeX. 2. Используйте `xr` команду пакета `\externaldocument{filename}` чтобы указать внешний документ(ы), на содержимое которого вы хотите ссылаться. Этот `xr` пакет работает, используя метки перекрёстных ссылок, содержащиеся в `.aux` файлах, создаваемых при компиляции внешних документов LaTeX. ### Как работает перекрёстное ссылание (краткое описание) Чтобы сделать перекрёстную ссылку на элемент в документе LaTeX, вам нужно: 1. Дать ему уникальный идентификатор, `some_string`, используя `\label` команду: ```latex \label{some_string} ``` 3. В месте, где вы хотите сослаться на этот элемент, нужно написать ```latex \ref{some_string} ``` Если совсем кратко, LaTeX управляет перекрёстными ссылками, записывая данные в файл с именем `filename.aux` где `filename` — это имя основного `.tex` компилируемого файла. Чтобы процесс работал, документ LaTeX нужно скомпилировать как минимум дважды: первая компиляция *генерирует* данные ссылок — записывая их в `filename.aux`. Во время второй компиляции LaTeX *читает* `filename.aux` их, чтобы разрешить ссылки, предоставляя данные для замены вхождений `\ref{some_string}`. * Подробнее о перекрёстных ссылках см. статью Overleaf [Перекрёстные ссылки на разделы, уравнения и плавающие элементы](/latex/ru/struktura-dokumenta/03-cross-referencing-sections-equations-and-floats.md). ## Проекты, где пакет xr не требуется Крупные проекты LaTeX, такие как книги или длинные отчёты, часто разбиваются на серию более мелких `.tex` файлов, по одному на главу, при этом файл каждой главы `.tex` добавляется в основной документ LaTeX с помощью `\input` или `\include`. Обычно эти главы не являются самодостаточными: вы не можете компилировать отдельные главы, потому что они не содержат `\documentclass{...}` инструкции или `\begin{document}...\end{document}` конструкцию. Эти главы предназначены для *включения* в документ-контейнер, который *можно* скомпилировать. В таких обстоятельствах перекрёстные ссылки на элементы документа — внутри любого отдельного файла главы — работают как обычно: вам не нужно использовать `xr` пакет. Чтобы изучить пример крупного проекта, вы можете [открыть этот пример в 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=) ## Пример проекта, где требуется пакет xr Предположим, у вас есть набор самодостаточных документов LaTeX, например коллекция из N статей: `article1.tex`, `article2.tex` ... `articleN.tex`. Каждую из этих статей можно компилировать отдельно, и, вероятно, они были написаны с использованием разных классов документов, пакетов и т. д. Теперь представьте, что вы хотите использовать LaTeX для написания обзора или сводки по этим статьям — назовём наш файл `summary.tex`. Нашей сводке нужно ссылаться на разделы, рисунки, таблицы, уравнения и т. д., содержащиеся в этих отдельных, самодостаточных N статьях. Как это сделать? Этот `xr` пакет позволяет вам это сделать: он даёт возможность `summary.tex` использовать метки ссылок, созданные любым из самодостаточных `файлов article*.tex` файлов. ### Примечание о файлах .aux * Заметьте, здесь мы используем звёздочку (`*`) как заполнитель для любого числа от 1 до N. Компиляция любого из самодостаточных файлов `article1.tex`, `article2.tex` ... `articleN.tex` приводит к тому, что LaTeX генерирует соответствующий `article*.aux` (\*\*`aux`\*\*вспомогательный) файл, который, среди прочего, содержит данные меток, необходимые для создания перекрёстных ссылок. Если какой-либо из `файлов article*.tex` файлов был отредактирован — например, чтобы изменить, добавить или удалить метки (`\label{...}`) — соответствующий `файлов article*.tex` файл(ы) должны быть перекомпилированы, чтобы обновить соответствующие `article*.aux` файлы. Обнаружение изменений в `файлов article*.tex`, а затем их перекомпиляция могут быть автоматизированы в Overleaf с помощью подходящего `latexmkrc` файла. ## Как использовать xr в Overleaf Мы используем упрощённую версию нашего примера с несколькими статьями; в частности, покажем, как автоматизировать процесс компиляции с помощью `latexmkrc` файла [предоставленного Overleaf Джоном Коллинзом](#code-for-latexmkrc) ([поддерживающего `latexmk`](https://ctan.org/pkg/latexmk?lang=en)). ### Файлы, используемые в нашем примере В нашем примере используются следующие файлы: * `**summary.tex**`: это наш обзорный документ. Нам нужно, чтобы он ссылался на содержимое, находящееся в `article1.tex`, например на рисунки и разделы. * `summary.tex` загружает `xr` пакет и использует `\externaldocument{article1}` чтобы указать, что данные ссылок из `article1.aux` должны использоваться. * `**article1.tex**`: отдельная самодостаточная статья, содержащая внутренние перекрёстные ссылки. Компиляция `article1.tex` генерирует данные перекрёстных ссылок, содержащиеся в файле `article1.aux`. * Внешний файл, такой как `article1.tex` который мог быть написан кем-то другим — чтобы вы использовали его «как есть», то есть без изменений. * `**latexmkrc**`: содержит код (Perl) для автоматизации перекомпиляции `article1.tex` из-за любых внесённых в него изменений — чтобы создать обновлённый `article1.aux` файла. * Наш `latexmkrc` файл был [предоставленного Overleaf Джоном Коллинзом](#code-for-latexmkrc) ([поддерживающего `latexmk`](https://ctan.org/pkg/latexmk?lang=en)). ### О команде \externaldocument Этот `xr` пакет предоставляет`\externaldocument` команду, которая имеет общий вид ```latex \externaldocument[prefix]{external_file} ``` * **`префикс` (необязательно):** Этот необязательный аргумент позволяет задать префикс, который будет добавлен ко всем меткам, импортируемым из внешнего документа. Это полезно, чтобы избежать конфликтов, если одинаковые имена меток используются в нескольких документах. * **`external_file` (обязательно):** Этот обязательный аргумент задаёт имя внешнего документа LaTeX (без `.tex` расширения), из которого вы хотите импортировать ссылки. Пакет `xr` будет искать `.aux` файл, соответствующий `external_file` (например, `external_file.aux`), чтобы получить метки. Например, если наш основной `.tex` файла `summary.tex` и внешний файл, `article1.tex` оба содержат метку `\label{eq:1}` то возникает конфликт имён меток. Этого конфликта можно избежать, написав ```latex \externaldocument[art1-]{article1} ``` в этом случае все метки, созданные при компиляции `article1.tex` получают префикс `art1-`. Теперь вы можете обращаться к `\label{eq:1}`, содержащимся в `article1.tex`, записав `\ref{art1-eq:1}` в `summary.tex`. ### Файлы проекта #### article1.tex Следующий код можно открыть в Overleaf по ссылке под листингом. ```latex \documentclass{article} \title{This is \texttt{article1.tex}} \begin{document} \section{Introduction} \label{introduction} Это самодостаточный документ \LaTeX{} с ссылками, которые мы хотим использовать в \texttt{summary.tex}. \subsection{Math references} \label{mathrefs} Как упоминалось в разделе \ref{introduction}, на разные элементы можно ссылаться внутри документа. \subsection{Powers series} \label{powers} \begin{equation} \label{eq:1} \sum_{i=0}^{\infty} a_i x^i \end{equation} Уравнение \ref{eq:1} — типичный степенной ряд. \end{document} ``` [Откройте `article1.tex` в 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) Компиляция `article1.tex` даёт следующий вывод: ![Вывод, полученный при компиляции файла article1.tex в Overleaf](/files/7be822c8544c446f2a2ebbc1b1c53135c91d8c67) #### summary.tex Вот наш исходный `summary.tex` файла *до* того, как мы указали, на какой внешний документ хотим ссылаться. Для простоты, `summary.tex` не содержит никаких `\label` команд, поскольку внутренних перекрёстных ссылок нет. Все `\ref` команды ссылаются на метки, создаваемые `\label` командами, содержащимися в `article1.tex`. ```latex \documentclass{article} \usepackage{xr} \title{This is \texttt{summary.tex}} \begin{document} В файле \texttt{article1.tex} введение — это раздел \ref{introduction}. В этом файле есть два подраздела: \ref{mathrefs} и \ref{powers}. В подразделе \ref{powers} уравнение \ref{eq:1} демонстрирует степенной ряд. \end{document} ``` [Откройте этот *незавершённый* `summary.tex` в 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) Если мы скомпилируем эту версию `summary.tex` она попытается прочитать данные ссылок из `summary.aux` но необходимые данные содержатся во внешнем файле `article1.aux` к которому пока нельзя получить доступ. Компиляция этого незавершённого `summary.tex` файла даёт следующий вывод, где двойные знаки вопроса показывают неопределённые ссылки: ![Изображение, показывающее сообщение об отсутствующих ссылках](/files/002db3e97436e903dac89a11c9fefcbaef317c6f) ### Указание внешнего документа Следующий шаг — указать `article1` в качестве имени внешнего документа, чьи метки мы хотим использовать. Добавьте следующую строку в преамбулу `summary.tex`: ```latex \externaldocument{article1} ``` Здесь, `article1` можно заменить любым файлом, чьи метки вы хотите использовать — можно применять несколько `\externaldocument` команд для доступа к дополнительным внешним файлам. ### Создание файла latexmkrc Следующий шаг — создать `latexmkrc` файл, как показано ниже: * В окне редактора проекта выберите **Новый файл** значок в левом верхнем углу окна проекта. * Выберите **Новый файл** из **Добавить файлы** всплывающего диалогового окна и назовите файл `latexmkrc`— обратите внимание, что расширение файла отсутствует: ![Создание файла latexmkrc в Overleaf](/files/a97a2ddf4bc83abc5993b4c443f7e94952cfa9cb) * Убедитесь, что `latexmkrc` файл создан и сохранён на верхнем (корневом) уровне области файлов проекта. То есть не внутри каких-либо папок в дереве файлов. * Скопируйте и вставьте следующий код в свой `latexmkrc` файла. #### Код для latexmkrc Overleaf благодарит Джона Коллинза, [поддерживающего `latexmk`](https://ctan.org/pkg/latexmk?lang=en)за то, что он связался с нами и предоставил следующий `latexmkrc` файл, который мы с радостью публикуем целиком — включая чрезвычайно полезные встроенные комментарии. ```perl # Здесь показано, как использовать пакет xr с latexmk. # Джон Коллинз 2023-03-29 # # Пакет xr ("система для внешних ссылок") используется документом # для ссылок на разделы, уравнения и т. д. в других внешних # документах. # Определения в этом файле позволяют latexmk применять latexmk к # автоматически обновлять внешний документ всякий раз, когда изменяется его .tex-файл, # чтобы ссылки в основном документе оставались актуальными. # Примечания: # 1. Эта версия определена так, чтобы помещать файлы, полученные при компиляции # внешних документов, в заданный подкаталог, чтобы отделять # потенциально множество сгенерированных файлов от каталогов # основного документа. # 2. Но чтобы использовать механизм пользовательских зависимостей latexmk, как здесь, # aux-файл, полученный при компиляции поддокумента, должен быть создан в # том же каталоге, что и соответствующий исходный .tex-файл. Поэтому # .aux-файл копируется. # 3. Предполагается, что внешние документы будут компилироваться # pdflatex. Это, конечно, можно изменить, поменяв опцию '-pdf' # в вызове latexmk на нужную. # 4. Идеальная реализация также обеспечила бы, чтобы перекомпиляция # внешнего документа происходила всякий раз, когда изменяется любой из его других исходных # файлов. Но в текущей версии этого не сделано, и # это, вероятно, потребовало бы либо использования внутренних переменных latexmk, # либо дополнительных расширений latexmk. # 5. Код использует подпрограммы copy и fileparse, которые загружаются # latexmk из пакетов Perl File::Copy и File::Basename. # 6. Он также использует некоторые ещё не задокументированные возможности latexmk: массив # переменную @file_not_found и подпрограммы popd, pushd и # rdb_add_generated. #-------------------- # Настраиваемые параметры компиляции внешних документов # Подкаталог для выходных файлов, полученных при компиляции внешних документов: $sub_doc_output = 'output-subdoc'; # Параметры, передаваемые latexmk для компиляции внешних документов: @sub_doc_options = (); push @sub_doc_options, '-pdf'; # Использовать pdflatex для компиляции внешних документов. # При необходимости замените '-pdf' на '-pdfdvi', 'pdfxe' или 'pdflua'. #-------------------- # Добавьте шаблон для сообщения xr в журнале о отсутствующих файлах в # список latexmk. Переменная latexmk @file_not_found ещё не задокументирована. # Эта строка не нужна для latexmk версии 4.80 или более поздней. 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 '.') ) { # В этом случае .aux-файл, создаваемый pdflatex, находится не в том же # каталоге, что и .tex-файл. # Поэтому: # 1. Фактически созданный aux-файл должен быть указан как произведённый этим # правилом, чтобы latexmk корректно обрабатывал зависимости. # (Проблема, которую нужно обойти: если $sub_dir_output совпадает с $aux_dir # для основного документа, xr может прочитать .aux-файл в # aux_dir, а не тот, который, как предполагает latexmk для cus dep, # должен быть создан в том же каталоге, что и исходный .tex # файл для этой пользовательской зависимости.) # Используйте ещё не задокументированную подпрограмму latexmk rdb_add_generated # чтобы сделать это: # 2. Копия .aux-файла должна находиться в том же каталоге, что и .tex-файл, # чтобы соответствовать определению пользовательской зависимости в latexmk. rdb_add_generated( "$sub_doc_output/$base_name.aux" ); copy "$sub_doc_output/$base_name.aux", "."; } popd; return $return; } } ``` ### Откройте проект Overleaf, демонстрирующий xr Следующий трёхфайловый проект теперь можно открыть в Overleaf, используя ссылки, приведённые выше и ниже списков файлов. Обратите внимание, что `latexmkrc` файл содержит код, предоставленный Джоном Коллинзом, но для краткости большинство комментариев удалено. [Откройте этот трёхфайловый пример в Overleaf.](/latex/ru/baza-znanii/033-cross-referencing-with-the-xr-package-in-overleaf.md) **summary.tex** Это наш файл-сводка. Из этого файла мы хотим использовать перекрёстные ссылки, созданные во внешних файлах. Здесь мы хотим использовать метки, созданные в `article1.tex`. ```latex \documentclass[12pt]{article} \usepackage{xr} \title{Использование пакета xr в Overleaf} % поместите все внешние документы здесь! \externaldocument{article1} \begin{document} В файле \texttt{article1.tex} введение — это раздел \ref{introduction}. В этом файле есть два подраздела: \ref{mathrefs} и \ref{powers}. В подразделе \ref{powers} уравнение \ref{eq:1} демонстрирует степенной ряд. \end{document} ``` **article1.tex** Этот файл — одна из наших статей. Обратите внимание, как он содержит различные `\label` команды для создания меток, которые, благодаря `xr` пакету, мы можем использовать в файле `summary.tex`. ```latex \documentclass{article} \title{This is \texttt{article1.tex}} \begin{document} \section{Introduction} \label{introduction} Это самодостаточный документ \LaTeX{} с ссылками, которые мы хотим использовать в \texttt{summary.tex}. \subsection{Math references} \label{mathrefs} Как упоминалось в разделе \ref{introduction}, на разные элементы можно ссылаться внутри документа. \subsection{Powers series} \label{powers} \begin{equation} \label{eq:1} \sum_{i=0}^{\infty} a_i x^i \end{equation} Уравнение \ref{eq:1} — типичный степенной ряд. \end{document} ``` **latexmkrc** Этот `latexmkrc` файл содержит код, обеспечивающий компиляцию внешних файлов. ```latex $sub_doc_output = 'output-subdoc'; @sub_doc_options = (); push @sub_doc_options, '-pdf'; # Использовать pdflatex для компиляции внешних документов. # При необходимости замените '-pdf' на '-pdfdvi', 'pdfxe' или 'pdflua'. 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; } } ``` [Откройте этот трёхфайловый пример в Overleaf.](/latex/ru/baza-znanii/033-cross-referencing-with-the-xr-package-in-overleaf.md) Следующая графика — это аннотированная версия результата верстки `summary.tex`, показывающая перекрёстные ссылки и соответствующие метки из внешнего файла `article1.tex`. ![Отображение ссылок, импортированных из внешнего файла](/files/9f03a12d6b6db3a6c95679c1a7947b9799b97c74) * Подробнее о перекрёстных ссылках см. статью Overleaf [Перекрёстные ссылки на разделы, уравнения и плавающие элементы](/latex/ru/struktura-dokumenta/03-cross-referencing-sections-equations-and-floats.md). ## Примечание об ошибках синтаксиса Для основного файла проекта вы можете использовать [режим компиляции «Остановка при первой ошибке»](/latex/ru/baza-znanii/149-using-the-stop-on-first-error-compilation-mode.md) чтобы компиляция немедленно прекращалась при обнаружении первой ошибки. Это может помочь изолировать и определить ошибки в вашем коде, а не позволять ошибкам накапливаться, что гораздо затрудняет поиск и отладку проблем. Этот *внешние* документы автоматически компилируются через `latexmkrc` файл; следовательно, любые ошибки синтаксиса LaTeX в них не будут отображаться в интерфейсе Overleaf — если только вы не перекомпилируете их также в Overleaf. Ошибки в этих внешних файлах могут помешать корректному отображению перекрёстных ссылок в сверстанном PDF-файле, поэтому мы настоятельно рекомендуем проверять и исправлять любые такие ошибки сразу же после их появления. --- # 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/ru/baza-znanii/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.