LaTeX 交叉引用系统简介

目录

[TOC]

摘要

1. 简介

2. 指定标签或标记符

3. 标签的位置

4. 引用的生成和更新

5. 引用相关的警告信息

6. 扩展引用功能的宏包
6.1 varioref宏包

6.2 cleveref宏包

6.3 hyperref宏包

6.4 xr/xr-hyper宏包

6.5 宏包载入顺序

6.6 showlabels 宏包

参考文献

摘要

交叉引用系统是LaTeX最强大的功能之一——可以在文档的任意地方引用带编号的结构，包括标题、图形、表格、公式等，并且更重要的是可以自动更新引用编号。本文概述了交叉引用系统，并介绍一些相关的扩展宏包。

1. 简介

LaTeX 实现了 \label和\ref宏，进而可以引用同一文档内的绝大部分带编号对象。首先用\label赋予唯一标识符给某个带编号的对象，然后就可以使用\ref宏进行引用。此外，另一个不那么常用的命令是\pageref，它可以输出被引用对象所在的页码数。

在下面的例子中，假设文档的第一节标题为“Introduction”，在该节添加了标记符sec:intro，之后就可以在接下来的章节中使用该标记符来指代之前的节：\ref{sec:intro}就会输出数字1。

\section{Introduction}\label{sec:intro}

% Content

\section{Methods}

In section \ref{sec:intro} on page

\pageref{sec:intro} we introduced ...

2. 指定标签或标记符

引用的标记符并没有什么格式上的限制。不过，通用的做法是使用前缀+冒号作为标记符的开头。添加前缀可以帮助作者识别被引用对象的类型。例如，引用图形的标记符可以是\label{fig:schema}这样的形式。对于一些最常用的引用对象，下表给出了相应的前缀名建议。

对象	前缀	对象	前缀
Chapter	ch	Figure	fig
Section	sec	Table	tab
Subsection	ssec	List item	itm
Appendix	app	Equation	eqn

当然，使用前缀是个好习惯，不过这也仅仅是建议——作者完全可以使用另一套前缀或者根本不使用。

3. 标签的位置

理想情况下，应该在被引用的计数对象之后立即放置\label标记。而对于图形或表格这样的浮动环境，应在\caption宏内或之后放置\label，这是因为图形或表格的编号是由\caption生成的。如果在编号对象之前使用\label基本上都会导致引用错误。当然，在编号对象之后太久才使用\label也可能会有问题。

4. 引用的生成和更新

一般来说需要两次运行排版命令才能生成引用编号。背后的原理是这样的，第一次运行排版命令时，系统会收集所有标记符信息，并写入一个辅助文件内；而再次运行排版命令时，系统会读取该辅助文件并进而更新引用。只要系统不能正确生成引用，那么在输出文档的相应位置就会生成双问号??标记。如果再次排版后还不能更新正确的引用，可以看一下log日志文件确定问题。下一节将介绍引用相关的警告信息。

5. 引用相关的警告信息

log日志文件中出现与引用相关的警告并不少见。如果标识符的定义有问题，一般会出现两种警告：1. 未定义的引用（undefined references）2. 重复定义的标签（multiply-defined labels）

第一种情况是由于引用的标识符没有定义，而第二种情况是由于多次定义了同一标识符。例如，如果作者复制一些代码片段（比如图形环境）而忘记重命名其中的标识符，那么就会出现重复定义标签的问题。

6. 扩展引用功能的宏包

很多宏包都扩展了LaTeX的交叉引用系统。这里简要介绍以下几个宏包：varioref, cleveref, hyperref, xr/xr-hyper。选择这些宏包的原因是每个宏包都在独特的方面扩展了原有的功能。大体上来说，这些宏包并没有重新定义标准引用命令的功能，而是定义了新命令。因此，标准的\label, \ref和\pageref功能并不会受到影响。

6.1 `varioref`宏包

varioref宏包将基础的引用命令扩展为略微更加复杂的形式。其中，\vref命令合并了\ref和\pageref的功能，会同时输出被引用对象的编号和所在的页码数。如果被引用对象位于同一页，那么会省略页码数。而\vpageref则增加了\pageref的功能：如果被引用对象位于同一页则输出“on this page”，否则输出所在页码数。最后，该宏包还提供了\vrefrange和\vpagerefrange命令，用于多重引用时输出编号也页码范围。

6.2 `cleveref`宏包

很多情况下作者都会在文本中提及所引用对象的类型。例如，某个图形可以引用为“This is shown in figure 1”。而\ref宏只会输出所引用对象的编号，因此这就是cleveref宏包的作用。该宏包会自动识别引用对象的类型，并打印出对应的引用。为此，该宏包提供了\cref命令。类似于varioref宏包，本宏包也实现了输出引用对象所在页码的宏\cpageref和页码范围的宏\cpagerefrange。

6.3 `hyperref`宏包

hyperref宏包中涉及交叉引用的主要功能是给引用加上链接：点击该引用会转到被引用对象所在的页面。只要在导言区导入该宏包即可实现相应功能。同时，该宏包还定义了\autoref宏，其功能类似于cleveref宏包中的\cref命令，即同时输出引用编号和引用类型。此外，该宏包实现了大量与交叉引用无关的其它功能，相关讨论已经超出了本文的主题范围。尽管如此，这里仍然推荐浏览一下该宏包的文档以了解该宏包的更多信息。

6.4 `xr`/`xr-hyper`宏包

xr宏包（eXternal References）可以引用其它文档中的对象。这在科技论文中特别有用，因为经常要在正文之外提供补充材料。使用该宏包就可以在正文中引用补充材料中的图形和表格。要实现此功能，必须在正文的导言区内使用\externaldocument{filename} 来指定外部文档。如果外部的tex文件位于不同文件夹下，那么也要指定相应的路径。然后就可以在正文中引用外部文档中的标识符了。另外要注意的是外部文档每次修改引用标签后都要编译一下，这样正文中才能生成正确的编号。

\documentclass{article}

\usepackage{xr}

\externaldocument{supplementary-materials}

\begin{document}

See supplementary figure \ref{fig:abc}.

\end{document}

对于这样指向外部文档的引用，如果还想要创建超链接，那么使用xr-hyper宏包代替xr。

6.5 宏包载入顺序

由于这些宏包都会影响引用的行为，因此，载入多个宏包可能造成冲突。所以，宏包载入时需要按照正确的顺序，即：(1) xr/xr-hyper, (2) varioref, (3) hyperref, 最后是 (4) cleveref。

6.6 `showlabels` 宏包

最后要提一下showlabels宏包，其功能是在输出的PDF文档的页边处显示标识符。因此，该宏包特别适用于在带有大量标签的长文档中追踪标识符的场合。

参考文献

说明：

本文翻译自Thomas Thurnherr, An introduction to the LATEX cross-referencing system, TUGboat, Volume 38 (2017), No. 1
遵循署名-非商业性使用-相同方式共享 4.0 国际（CC BY-SA 4.0）协议发布。因此，可以自由地对博客中内容进行分享、创作演绎直至商业性的使用，但必须在文章末尾或参考文献处注明文章的出处（文章链接）。完整的协议可以参看这里。