LaTeX 交叉引用系统简介
LaTeX 交叉引用系统简介
目录
摘要
交叉引用系统是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文档的页边处显示标识符。因此,该宏包特别适用于在带有大量标签的长文档中追踪标识符的场合。
参考文献
cleveref
: Intelligent cross-referencing.hyperref
: Extensive support for hypertext in LATEX.showlabels
: Show label commands in the margin.varioref
:Intelligent page references.xr
: References to other LATEX documents.
说明:
- 本文翻译自Thomas Thurnherr, An introduction to the LATEX cross-referencing system, TUGboat, Volume 38 (2017), No. 1
- 遵循署名-非商业性使用-相同方式共享 4.0 国际(CC BY-SA 4.0)协议发布。因此,可以自由地对博客中内容进行分享、创作演绎直至商业性的使用,但必须在文章末尾或参考文献处注明文章的出处(文章链接)。完整的协议可以参看这里。