> 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/uk/baza-znan/033-cross-referencing-with-the-xr-package-in-overleaf.md).

# Перехресні посилання за допомогою пакета xr в Overleaf

## Огляд

Функція [`xr` accents](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/uk/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{Це \texttt{article1.tex}}
\begin{document}
\section{Вступ}
\label{introduction}

Це автономний документ \LaTeX{} з
посиланнями, які ми хочемо використати в \texttt{summary.tex}.

\subsection{Math references}
\label{mathrefs}
Як згадано в розділі \ref{introduction},
на різні елементи можна посилатися в межах
документа.

\subsection{Степеневі ряди}
\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/9179d695f1e502e5c6b5dc4666a028d2b0100c4e)

#### summary.tex

Ось наш початковий `summary.tex` файлу *до того, як* ми вказали, на який зовнішній документ хочемо посилатися. Для спрощення, `summary.tex` не містить жодних `\label` команд, тому що немає внутрішніх перехресних посилань. Усі `\ref` команди посилаються на мітки, згенеровані `\label` командами, що містяться в `article1.tex`.

```latex
\documentclass{article}
\usepackage{xr}
\title{Це \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/fe3b409199ea2f0f9d1d2a5e4fb2c77e4de767c3)

### Вказання зовнішнього документа

Наступний крок — вказати `article1` як назву зовнішнього документа, мітки якого ми хочемо використовувати. Додайте таку строку до преамбули `summary.tex`:

```latex
\externaldocument{article1}
```

Тут, `article1` можна замінити на будь-який файл, мітки якого ви хочете отримати — можна використовувати кілька `\externaldocument` команд для доступу до додаткових зовнішніх файлів.

### Створення файлу latexmkrc

Наступний крок — створити `latexmkrc` файл, як показано нижче:

* У вікні редактора проєкту виберіть **Новий файл** піктограму у верхньому лівому куті вікна проєкту.
* Виберіть **Новий файл** у меню **Додати файли** у спливному діалоговому вікні та назвіть файл `latexmkrc`— зауважте, що розширення файлу відсутнє:

![Створення файлу latexmkrc в Overleaf](/files/acc1a1370ea75eb867d34b7c3d34e5ca72cac9ce)

* Переконайтеся, що `latexmkrc` файл створено і збережено на верхньому (кореневому) рівні області файлів проєкту. Тобто не всередині жодної папки в дереві файлів.
* Скопіюйте та вставте наведений нижче код у ваш `latexmkrc` файлі.

#### Код для latexmkrc

Overleaf вдячні Джону Коллінзу, [супроводжувачем `latexmk`](https://ctan.org/pkg/latexmk?lang=en), за те, що він звернувся до нас і надав такий `latexmkrc` файл, який ми із задоволенням публікуємо повністю — включно з надзвичайно корисними вбудованими коментарями.

```perl
# Це показує, як використовувати пакет xr з latexmk.
# Джон Коллінз 2023-03-29
#
# Пакет xr («система для eXternal References») використовується документом
# щоб робити посилання на розділи, рівняння тощо в інших зовнішніх
# документах.
# Визначення в цьому файлі дають змогу 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, має бути створений
               #    цим користувацьким залежним правилом, і який знаходиться в тому самому каталозі, що й вихідний
               #    файл .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/uk/baza-znan/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{Це \texttt{article1.tex}}
\begin{document}
\section{Вступ}
\label{introduction}

Це автономний документ \LaTeX{} з
посиланнями, які ми хочемо використати в \texttt{summary.tex}.

\subsection{Math references}
\label{mathrefs}
Як згадано в розділі \ref{introduction},
на різні елементи можна посилатися в межах
документа.

\subsection{Степеневі ряди}
\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/uk/baza-znan/033-cross-referencing-with-the-xr-package-in-overleaf.md)

Наведена нижче графіка — це анотована версія виводу від верстки `summary.tex`, що показує перехресні посилання та відповідні мітки із зовнішнього файла `article1.tex`.

![Показано посилання, імпортовані із зовнішнього файла](/files/9368c746f05303b73192fc56895315648a1cfe7c)

* Докладніше про перехресні посилання див. статтю Overleaf [Перехресні посилання на розділи, рівняння та плаваючі елементи](/latex/uk/struktura-dokumenta/03-cross-referencing-sections-equations-and-floats.md).

## Примітка щодо синтаксичних помилок

Для основного файлу проєкту ви можете використовувати режим Overleaf [«Зупинятися на першій помилці»](/latex/uk/baza-znan/149-using-the-stop-on-first-error-compilation-mode.md) щоб забезпечити негайне завершення компіляції після виявлення першої помилки. Це може допомогти ізолювати та виявити помилки у вашому коді, замість того щоб дозволяти помилкам накопичуватися, що значно ускладнює пошук і налагодження проблем.

Функція *external* документи компілюються автоматично через `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/uk/baza-znan/033-cross-referencing-with-the-xr-package-in-overleaf.md?ask=<question>&goal=<endgoal>
```

`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.