索引与文献命令

索引和参考文献不是编译一次就能完成的。首先 LaTeX 写出原始材料(\index 条目写入 .idx\cite 键写入 .aux);然后由另一个程序排序并格式化;最后再次运行 LaTeX,把结果纳入正文。本页介绍这些幕后助手:处理索引的 makeindex / mendex / upmendex,以及处理文献的 bibtex / pbibtex / upbibtex / biber

索引和文献由单独程序处理

在正文中写 \index{...}\cite{...},并不会让 LaTeX 自己排序。第一次编译会输出原始数据.idx.aux);随后运行索引或文献程序,生成格式化后的文件(.ind.bbl);再重新编译一次把它读入。这是一个多阶段流程。手动管理顺序和编译次数很麻烦,因此实际工作中通常交给 latexmk 之类的构建工具。

makeindex / mendex / upmendex — 生成索引

makeindex 是基础工具。它读取 \index 写出的 .idx,排序后生成 .ind。输出格式可用 -s style.ist 控制。不过它的内部处理以单字节为单位,因此无法按正确的日文读音顺序排序。

mendex 是支持日文的版本,会按汉字的读音(yomi)排序。用 reading@term 语法给出读音后,它会按该假名的日文顺序排列。upmendex 是其 Unicode/多语言后继版:内部采用 Unicode,并使用 ICU(Unicode Collation Algorithm) 对日文、拉丁文、希腊文、西里尔文等排序。它向上兼容 makeindex/mendex 的样式,是现代 upLaTeX 或 LuaLaTeX-ja 索引的标准选择。

terminal
makeindex document.idx              # → document.ind
upmendex -s mystyle.ist document.idx # 多言語・スタイル指定 / multilingual, with a style

最小索引会在导言区加载 makeidx、声明 \makeindex,在正文中放置 \index{...},并在索引应出现的位置调用 \printindex。关键点是,\index 并不会在页面上打印可见文字;它会为索引处理器写出材料。当排序键和显示文本需要不同的时候,使用 sort-key@printed-term,例如 latex@LaTeX

latex
\documentclass{jsarticle}
\usepackage{makeidx}
\makeindex
\begin{document}
LaTeX\index{らてふ@LaTeX} で索引を作ります。
\printindex
\end{document}

bibtex / pbibtex / upbibtex / biber — 生成参考文献

bibtex(Oren Patashnik,1985 年)是经典文献工具。它把 .aux 中的 \cite 键与 .bib 数据库匹配,并按 .bst 样式生成 .bbl。处理日文字段和日文排序时,使用 pbibtex(pTeX 系)或支持 Unicode 的 upbibtex(upTeX 系)。

biber 是现代 biblatex 的后端。它用 Perl 编写,提供完整的 Unicode 支持、基于 Unicode Collation Algorithm 的排序、强大的交叉引用、数据模型验证,以及传统 BibTeX 之外的其他功能。如果文档使用 biblatex,首先应假定使用 biber。bibtexbiber 共有的 -min-crossrefs=N(默认 2) 设置 crossref 的阈值:某条目被至少 N 个其他条目引用时,会作为独立参考文献条目出现;否则其字段会并入引用它的条目。

terminal
bibtex document     # 拡張子なし。document.aux を読む / no extension; reads document.aux
biber  document     # biblatex を使う場合 / when the document uses biblatex

经验规则:传统的 \bibliography + .bst 使用 bibtex(日文使用 up/pbibtex)。如果需要多语言和完整功能,并使用 biblatex,就使用 biber。当研究室或期刊模板指定 .bst 时,不要强行迁移,而应遵循该模板的方式。对于可自行选择引用栈的新项目,biblatex + biber 在 Unicode 和细粒度控制方面更强。

在 BibTeX 系列中,.bst 文件控制输出样式,因此期刊或研究室指定 jplainplainnat 或其他样式时,就按它来。使用 biblatex 时,由 LaTeX 侧的选项选择样式,底层数据处理交给 biber。无论哪条路线,正文中的引用键必须与 .bib 中的键一致,否则即使能生成 .bbl,引用也无法解析。先做一个只含一条文献的最小例子并让它通过,再迁移完整参考文献,可以把失败范围缩小。

流程失败时,先问“LaTeX 是否写出了原始材料”:索引看 .idx,biblatex 文献看 .aux.bcf。接着阅读 makeindexupmendexbibtexbiber 的日志。最后再次运行 LaTeX,确认生成的 .ind.bbl 是否真的被纳入正文。按这个顺序调试,可以快速缩小故障范围。

按顺序运行

典型顺序是“编译 → 文献/索引 → 编译 → 编译”。例如 upLaTeX 如下所示。不过,与其手动输入,不如交给 latexmk 等工具自动判断所需顺序和次数,这样最稳妥。

terminal
uplatex  document      # .aux / .idx を生成
upbibtex document      # 文献を整形 (.bbl)
upmendex document      # 索引を整形 (.ind)
uplatex  document      # 取り込み(番号確定のためもう一度流すことも)
uplatex  document