When writing a scientific paper, one often provides supplementary materials together with the main manuscript. Supplementary materials can be additional figures, tables, or other materials not included in the main manuscript. However, since these materials are usually kept in a different physical file, they can not be referenced in the main manuscript using the standard approach (\label{} — \ref{}). The eXternal References xr package allows referencing labeled content from external documents, such as supplementary materials
Preparing the package
In the main document, we first load the xr package. Next, we have to let the package know in which external document to look for labels. To do that, we use the name of the tex file, without ending. If the document is located in a different folder, we can use the absolute or relative path to the file.
\usepackage{xr}
\externaldocument{path/to/external-file1}
\externaldocument{path/to/external-file2}
Referencing
Having the external file defined in the main document, we can now reference any content with a label in the external document using the \ref command. More specifically, let’s assume we defined a figure label fig:schema in external-file1.tex. To reference this figure, we would simply write:
\ref{fig:schema}
Multiply-defined labels
If there are multiply-defined labels in the main document and/or the external document(s), LaTeX will throw a warning in the log: ” There were multiply-defined labels”.
A possible solution is to find and replace all multiply-defined labels, either in the main or in the external document. That’s a bad idea for multiple reasons. The xr package offers a more elegant approach. It allows adding a prefix to each external document. The prefix is defined by passing an optional argument to \externaldocument.
\usepackage{xr}
\externaldocument[ext1-]{path/to/external-file1}
\externaldocument[ext2-]{path/to/external-file2}
With that, labeled content defined in external-file1 and external-file2 have to be referenced with the prefix ext1- and ext2-, respectively. As a consequence, labels having the same name in the main document and the external document are named differently in the main document. For example, assume we defined a figure label fig:schema in external-file1.tex. To reference the figure in the main document, we use:
\ref{ext1-fig:schema}
Defining custom reference commands
In a scientific article, one often marks references to supplementary materials with an S (as in Supplementary Figure S1). To simplify referencing of supplementary materials, it might be a good idea to define special \ref commands that print references in the appropriate format. Some example commands are provided below.
% To add an 'S' prefix to a reference
\newcommand*\sref[1]{%
S\ref{#1}}
% For 'Supplementary Figure S1'
\newcommand*\sfref[1]{%
Supplementary Figure S\ref{#1}}
% For 'Supplementary Table S1'
\newcommand*\stref[1]{%
Supplementary Table S\ref{#1}}
% For 'Supplementary Materials S1'
\newcommand*\smref[1]{%
Supplementary Materials S\ref{#1}}
Final remarks
- It is important to always typeset the external document first. Also, when the external document changes, both documents have to be re-processed. Use latexmk to automate the build process.
- Referencing external documents introduces dependencies. Keep that in mind when you move files around or send them to collaborators or editors.
- External references are loaded from the aux-file of the external document. If you clean up the directory after typesetting, you won’t be able to properly reference content from an external document.
- Finally, to get the reference number right, the document always has to be processed twice, for example using
pdflatex.