2.8 引文

Pandoc 提供了两种方法来管理文档中引用文献和参考书目。

  1. 默认的方法是使用名为 pandoc-citeproc 的 Pandoc 帮助程序，它遵循 引用样式语言 (Citation Style Language, CSL) 的规范，并从大量可用的 CSL 样式文件 (CSL style files) 之一中获取特定的格式说明。

  2. 用户也可以选择使用 natbib（基于 bibtex）或 biblatex 作为“引文软件包”。在这种情况下，参考书目数据文件需要为 bibtex 或 biblatex 格式，并且文档输出格式仅限于 PDF。与 CSL 相同，可用地参考书目样式也有许多（请参阅这些软件包的文档）。

    为了使用 natbib 或 biblatex 处理参考文献，你可用设置 R Markdown 输出格式的 citation_package 选项，例如：

    output:
  pdf_document:
    citation_package: natbib
  bookdown::pdf_book:
    citation_package: biblatex

即使你为 PDF 输出格式选择了 natbib 或 biblatex 作为引文软件包，所有其它输出格式都将使用 pandoc-citeproc。如果使用相匹配的样式（例如对于 biblatex 采用 biblio-style: apa，而对于 pandoc-citeproc 采用 csl: apa.csl），输出到 PDF 和 非 PDF 的格式将非常相似，但不一定是相同的。

对于任何非 PDF 输出格式，pandoc-citeproc 是唯一可用的选项。如果 PDF 和非 PDF 输出格式之间的一致性很重要，请始终使用 pandoc-citeproc。

参考书目数据有很多种格式。本节仅展示了 BibTeX 数据库的示例，对于其他格式请参见 Pandoc 使用指南中 “Citations” 一节。

BibTeX 数据库是一个纯文本文件（依惯例其文件扩展名为 .bib），其内容包含有类似于以下所示的参考书目条目：

@Manual{R-base,
  title = {R: A Language and Environment for Statistical
    Computing},
  author = {{R Core Team}},
  organization = {R Foundation for Statistical Computing},
  address = {Vienna, Austria},
  year = {2016},
  url = {https://www.R-project.org/},
}

参考书目条目以 @type{ 开头，其中 type 可以是 article、book、manual等等。7紧跟着是一个引文关键词，在上面的示例中为 R-base。要引用一个条目，需要使用 @key 或 [@key]（后者会将引用文字放在圆括号中），例如，@R-base 被渲染为 R Core Team (2023)，而 [@R-base] 则渲染为 “(R Core Team 2023)”。注释也可以包含在方括号中，例如 [a note about, @R-base] 将会被渲染为 “(a note about, R Core Team 2023)”。如果你对 LaTeX 中的 natbib 软件包很熟悉，你会发现 @key 基本上就是 \citet{key}，而 [@key] 等同于 \citep{key}。

在一个参考书目条目中有许多字段，例如 title、author 和 year 等。你可用在 https://en.wikipedia.org/wiki/BibTeX 查看 BibTeX 中可能的条目和字段类型。

在 knitr 中有一个帮助函数 write_bib()，它能够为 R 软件包自动生成 BibTeX 条目，例如：

# the second argument can be a .bib file
knitr::write_bib(c('knitr', 'stringr'), '', width = 60)
@Manual{R-knitr,
  title = {knitr: A General-Purpose Package for Dynamic
    Report Generation in R},
  author = {Yihui Xie},
  year = {2023},
  note = {R package version 1.45},
  url = {https://yihui.org/knitr/},
}

@Manual{R-stringr,
  title = {stringr: Simple, Consistent Wrappers for Common
    String Operations},
  author = {Hadley Wickham},
  year = {2023},
  note = {R package version 1.5.1,
    https://github.com/tidyverse/stringr},
  url = {https://stringr.tidyverse.org},
}

@Book{knitr2015,
  title = {Dynamic Documents with {R} and knitr},
  author = {Yihui Xie},
  publisher = {Chapman and Hall/CRC},
  address = {Boca Raton, Florida},
  year = {2015},
  edition = {2nd},
  note = {ISBN 978-1498716963},
  url = {https://yihui.org/knitr/},
}

@InCollection{knitr2014,
  booktitle = {Implementing Reproducible Computational
    Research},
  editor = {Victoria Stodden and Friedrich Leisch and Roger
    D. Peng},
  title = {knitr: A Comprehensive Tool for Reproducible
    Research in {R}},
  author = {Yihui Xie},
  publisher = {Chapman and Hall/CRC},
  year = {2014},
  note = {ISBN 978-1466561595},
}

一旦你有一个或多个 .bib 文件，你可以在第一个 R Markdown 文档（通常是 index.Rmd）中的 YAML 元数据中使用字段 bibliography 来使用它们，你也可以通过 biblio-style 指定参考书目样式（它仅对 PDF 输出文档起作用），例如：

---
bibliography: ["one.bib", "another.bib", "yet-another.bib"]
biblio-style: "apalike"
link-citations: true
---

字段 link-citations 能够用来添加从“作者-年份”格式的引文文本到 HTML 输出中参考书目条目的内部链接。

当输出格式为 LaTeX 时，参考文献列表将自动放在文档末尾的章节中。对于非 LaTeX 输出，你可以为你的书籍添加一个空章节作为最后一章。例如，如果最后一章是 Rmd 文件 06-references.Rmd，则它的内容可以是内联 R 表达式：

`r if (knitr::is_html_output()) '# References {-}'`

有关如何使用引文的更多详细说明和示例，请参阅 Pandoc 使用指南的“引文”部分。

参考文献

R Core Team. 2023. R: A Language and Environment for Statistical Computing. Vienna, Austria: R Foundation for Statistical Computing. https://www.R-project.org/.

  1. 类型名称不区分大小写，因此不管是 manual、Manual 或 MANUAL 都可以。↩︎