> 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/ja/narejjibsu/033-cross-referencing-with-the-xr-package-in-overleaf.md). # Overleafでxrパッケージを使って相互参照する ## 概要 この [`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 文書を少なくとも 2 回コンパイルする必要があります。1 回目のコンパイルで *生成されます* 参照データが生成され、 `filename.aux`に書き込まれます。2 回目のコンパイルでは、LaTeX が *読み込み* `filename.aux` 参照を解決し、 `\ref{some_string}`. * の出現箇所を置き換えるためのデータを提供します。 [相互参照の詳細については、Overleaf の記事](/latex/ja/wen-shu-gou-zao/03-cross-referencing-sections-equations-and-floats.md). ## セクション、数式、フロートの相互参照 xr パッケージが不要な LaTeX プロジェクト `.tex` 書籍や長いレポートのような大規模な LaTeX プロジェクトは、しばしば複数の小さな `.tex` ファイルに分割され、各章ごとに 1 つのファイルがあり、各章の `\input` または `\include`を使ってメインの LaTeX 文書に追加されます。通常、それらの章はスタンドアロンではありません。\documentclass 文も `\documentclass{...}` または `\begin{document}...\end{document}` 構文も含んでいないため、個別の章だけではコンパイルできません。それらの章は、コンパイル可能な「コンテナ」文書に *組み込まれる* ことを目的としています。このような場合、個々の章ファイル内の文書要素への相互参照は通常どおり行えます。したがって、 *パッケージを使う必要はありません。* に `xr` 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 パッケージが必要なプロジェクトの例 たとえば、N 本の記事からなるコレクションのような、スタンドアロンの LaTeX 文書の集合があるとします。 `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` ファイル内のキーと一致するすべての項目を探します。 ## Overleaf で xr を使う方法 ここでは複数記事の例を簡略化したものを使い、特に、 `latexmkrc` ファイル [が Overleaf に提供したもの](#code-for-latexmkrc) ([の保守者である John Collins によって `latexmk`](https://ctan.org/pkg/latexmk?lang=en)). ### 例で使うファイル この例では次のファイルを使います。 * `**summary.tex**`：これが概要文書です。ここでは、 `article1.tex`に含まれる図や節などの内容を参照する必要があります。 * `summary.tex` は `xr` パッケージを読み込み、 `\externaldocument{article1}` を使って、 `article1.aux` の参照データを使用するよう指定しています。 * `**article1.tex**`：内部相互参照を含む、単独で完結した 1 本の記事です。 `article1.tex` をコンパイルすると、ファイル `article1.aux`. * の中にある相互参照データが生成されます。 `article1.tex` のような外部ファイルは、誰か他の人が書いたものであっても、「そのままの状態」で使えます。つまり変更しないということです。 * `**latexmkrc**`： `article1.tex` の再コンパイルを自動化するためのコード（Perl）を含んでいます。 `article1.aux` ファイル内のキーと一致するすべての項目を探します。 * 私たちの `latexmkrc` ファイルは [が Overleaf に提供したもの](#code-for-latexmkrc) ([の保守者である John Collins によって `latexmk`](https://ctan.org/pkg/latexmk?lang=en)). ### \externaldocument コマンドについて この `xr` パッケージは`\externaldocument` コマンドを提供しており、その一般形は次のとおりです。 ```latex \externaldocument[prefix]{external_file} ``` * **`prefix` （省略可能）：** この省略可能な引数を使うと、外部文書から取り込まれたすべてのラベルに付加されるプレフィックスを定義できます。同じラベル名が複数の文書で使われている場合の競合回避に便利です。 * **`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{導入} \label{introduction} これは、 という参照を含むスタンドアロンの \LaTeX{} 文書です。 \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` 次の出力が生成されます。 ![Overleaf 上で article1.tex ファイルをコンパイルして得られる出力](/files/ec93700b5aeffa74e44e735709e9536fba2f0176) #### 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} です。そのファイルには 2 つの小節、\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/c9f317bcfb09486a71d1312c7b5cb8214ccc7554) ### 外部文書の指定 次の手順は `article1` を、ラベルを参照したい外部文書の名前として指定することです。次の行を `summary.tex`: ```latex \externaldocument{article1} ``` のプリアンブルに追加してください。 `article1` ここでは、ラベルにアクセスしたい任意のファイルに置き換えられます。追加の外部ファイルにアクセスするために複数の `\externaldocument` コマンドを使えます。 ### latexmkrc ファイルの作成 次に、以下に示すような `latexmkrc` ファイルを作成します。 * プロジェクトのエディタウィンドウで、左上にある **新規ファイル** アイコンを選択します。 * 選択 **新規ファイル** から **ファイルを追加** ポップアップダイアログを開き、ファイル名を `latexmkrc`とします。注意：ファイル拡張子はありません。 ![Overleaf で latexmkrc ファイルを作成する](/files/48043b30d75d579b6a5e520cc606ced3aa7244c2) * 必ず `latexmkrc` ファイルが、プロジェクトのファイル領域の最上位（ルート）レベルに作成・保存されていることを確認してください。つまり、ファイルツリー内のどのフォルダの中にも入れないでください。 * 次のコードを `latexmkrc` ファイル内のキーと一致するすべての項目を探します。 #### latexmkrc のコード Overleaf は John Collins 氏に感謝します。 [の保守者である John Collins によって `latexmk`](https://ctan.org/pkg/latexmk?lang=en)、次の `latexmkrc` ファイルを提供していただいたことに感謝します。特に役立つインラインコメントも含め、全文を公開できることをうれしく思います。 ```perl # これは、latexmk と xr パッケージを使う方法を示しています。 # John Collins 2023-03-29 # # xr パッケージ（「外部参照のためのシステム」）は文書によって使われます # 他の外部 # 文書内の節、数式などを参照するためにです。 # このファイルの定義により、latexmk は latexmk を # .tex ファイルが変更されたときに外部文書を自動的に更新し、 # メイン文書内の参照が常に最新の状態に保たれるようにします。 # 注: # 1. この版では、外部文書のコンパイルで生成されたファイルを # あらかじめ定義したサブディレクトリに入れるようにしてあり、 # 生成される多数のファイルをメイン文書の # ディレクトリから分離します。 # 2. ただし、ここでのように latexmk のカスタム依存機構を使うには、 # サブ文書のコンパイルによって生成された aux ファイルは # 対応するソース .tex ファイルと同じディレクトリに生成される必要があります。 # そのため、 # 3. 外部文書は # pdflatex でコンパイルされるものと仮定しています。これは、必要に応じて # 呼び出す latexmk に与える '-pdf' # 4. 理想的な実装では、 # 外部文書の他のソース # ファイルが変更されたときにも再コンパイルが行われるようにすべきです。しかし現行版ではそうなっておらず、 # それには latexmk の内部変数を使うか、 # latexmk への追加拡張が必要になるでしょう。 # 5. このコードは copy と fileparse のサブルーチンを使っており、 # これらは Perl パッケージ File::Copy と File::Basename から latexmk によって読み込まれます。 # 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 の v. 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 '.') ) { # この場合、pdflatex によって生成された .aux ファイルは同じ # ディレクトリにありません。 # したがって： # 1. 実際に生成された aux ファイルは、この # ルールによって生成されたものとして一覧に載っていなければならず、そうすることで latexmk が依存関係を正しく扱えます。 # （回避すべき問題：$sub_dir_output がメイン文書の $aux_dir と同じ場合、 # xr は latexmk が # 生成すると想定している .aux ファイルではなく、 # aux_dir にある .aux ファイルを読むかもしれません。こちらはこのカスタム依存関係の .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; } } ``` ### xr を実演する Overleaf プロジェクトを開く 以下の 3 ファイルのプロジェクトは、ファイル一覧の上と下にあるリンクを使って Overleaf で開けます。なお、 `latexmkrc` ファイルには John Collins 氏から提供されたコードが含まれていますが、簡潔にするため大半のコメントは削除されています。 [この 3 ファイルの例を Overleaf で開く。](/latex/ja/narejjibsu/033-cross-referencing-with-the-xr-package-in-overleaf.md) **summary.tex** これが要約ファイルです。このファイル内から、外部ファイルで作成された相互参照を使いたいと考えています。ここでは、 `article1.tex`. ```latex \documentclass[12pt]{article} \usepackage{xr} \title{Overleaf で xr パッケージを使う} % 外部文書はすべてここに置く！ \externaldocument{article1} \begin{document} ファイル \texttt{article1.tex} では、導入部はセクション \ref{introduction} です。そのファイルには 2 つの小節、\ref{mathrefs} と \ref{powers} があります。小節 \ref{powers} では、式 \ref{eq:1} がべき級数を示しています。 \end{document} ``` **article1.tex** これは記事ファイルの 1 つです。さまざまな `\label` コマンドが含まれていてラベルを作成している点に注意してください。これらは `xr` パッケージのおかげで、 `summary.tex`. ```latex \documentclass{article} \title{This is \texttt{article1.tex}} \begin{document} \section{導入} \label{introduction} これは、 という参照を含むスタンドアロンの \LaTeX{} 文書です。 \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; } } ``` [この 3 ファイルの例を Overleaf で開く。](/latex/ja/narejjibsu/033-cross-referencing-with-the-xr-package-in-overleaf.md) 次の図は、 `summary.tex`を組版した出力に注釈を加えたもので、相互参照と、外部ファイル `article1.tex`. ![外部ファイルから取り込んだ参照の表示](/files/405a49cd6abe99e7b2e261ae1dcd200312cb6924) * の出現箇所を置き換えるためのデータを提供します。 [相互参照の詳細については、Overleaf の記事](/latex/ja/wen-shu-gou-zao/03-cross-referencing-sections-equations-and-floats.md). ## 構文エラーについての注意 メインのプロジェクトファイルでは、Overleaf の [最初のエラーで停止するコンパイルモード](/latex/ja/narejjibsu/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/ja/narejjibsu/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.