作者：Yihui Xie
译者：郑宝童
日期：2021.05.26

2.8 Citations

Pandoc offers two methods for managing citations and bibliographic references in a document.

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

  1. The default method is to use a Pandoc helper program called [pandoc-citeproc](https://github.com/jgm/pandoc-citeproc), which follows the specifications of the Citation Style Language (CSL) and obtains specific formatting instructions from one of the huge number of available CSL style files.
  2. Users may also choose to use either natbib (based on bibtex) or biblatex as a “citation package”. In this case, the bibliographic data files need to be in the bibtex or biblatex format, and the document output format is limited to PDF. Again, various bibliographic styles are available (please consult the documentation of these packages).
    To use natbib or biblatex to process references, you can set the citation_package option of the R Markdown output format, e.g.,
  1. 默认方式是使用Pandoc的名为[pandoc-citeproc](https://github.com/jgm/pandoc-citeproc)的帮助程序, 它遵循引用风格语言(Citation Style Language (CSL) )的规范，从大量可用的CSL风格文件( CSL style files)中获取特定的格式说明。
  2. 用户也可以选择使用natbib (基于bibtex)或 biblatex 作为“citation package”。在这种情况下，书目数据文件的格式需要为bibtex or biblatex ，文档输出格式限制为PDF。同样，有各种书目样式(请参考这些包的文档)。

To use natbib or biblatex to process references, you can set the citation_package option of the R Markdown output format, e.g.,

要使用natbib或biblatex来处理引用，你可以设置R Markdown输出格式的citation_package选项，例如:

  1. output:
  2.   pdf_document:
  3.     citation_package: natbib
  4.   bookdown::pdf_book:
  5.     citation_package: biblatex

Even if you choose natbib or biblatex for PDF output, all other output formats will be using pandoc-citeproc. If you use matching styles (e.g., biblio-style: apa for biblatex along with csl: apa.csl for pandoc-citeproc), output to PDF and to non-PDF formats will be very similar, though not necessarily identical.

即使您选择natbib 或biblatex 作为PDF输出，所有其他的输出格式也都将使用pandoc-citeproc。如果你使用匹配的样式(例如， (e.g., biblio-style: apa for biblatex along with csl: apa.csl for pandoc-citeproc)，输出到PDF和输出到非PDF格式将非常相似，though not necessarily identical.

For any non-PDF output format, pandoc-citeproc is the only available option. If consistency across PDF and non-PDF output formats is important, use pandoc-citeproc throughout.

The bibliographic data can be in several formats. We have only shown examples of BibTeX databases in this section, and please see the “Citations” section of the Pandoc manual for other possible formats.

A BibTeX database is a plain-text file (with the conventional filename extension .bib) that consists of bibliography entries like this:

对于任何非pdf输出格式，pandoc-citeproc是唯一可用的选项。如果PDF和非PDF输出格式之间的一致性很重要，请始终使用 pandoc-citeproc ,
书目数据可以有几种格式。在本节中，我们只展示了`.bib数据库`的示例，其他可能的格式请参阅Pandoc手册的“引文”部分。
BibTeX数据库是一个纯文本文件(具有传统的文件名扩展名。bib)，它由如下书目条目组成:

  1. @Manual{R-base,
  2.   title = {R: A Language and Environment for Statistical
  3.     Computing},
  4.   author = {{R Core Team}},
  5.   organization = {R Foundation for Statistical Computing},
  6.   address = {Vienna, Austria},
  7.   year = {2016},
  8.   url = {https://www.R-project.org/},
  9. }

A bibliography entry starts with @type{, where type may be article, book, manual, and so on.7 Then there is a citation key, like R-base in the above example. To cite an entry, use @key or [@key] (the latter puts the citation in braces), e.g., @R-base is rendered as R Core Team (2021), and [@R-base] generates “(R Core Team 2021)”. If you are familiar with the natbib package in LaTeX, @key is basically \citet{key}, and [@key] is equivalent to \citep{key}.

参考书目以@type{作为开始，type 可以是article, book, manual,等等.7 Then there is a citation key, like R-base in the above example. To cite an entry, use @key or [@key] (the latter puts the citation in braces), e.g., @R-base is rendered as R Core Team (2021), and [@R-base] generates “(R Core Team 2021)”. If you are familiar with the natbib package in LaTeX, @key is basically \citet{key}, and [@key] is equivalent to \citep{key}.

There are a number of fields in a bibliography entry, such as title, author, and year, etc. You may see https://en.wikipedia.org/wiki/BibTeX for possible types of entries and fields in BibTeX.
There is a helper function write_bib() in knitr to generate BibTeX entries automatically for R packages, e.g.,
参考书目条目中有许多字段，如title, author, and year等等。您可以在https://en.wikipedia.org/wiki/BibTeX 上查看BibTeX中可能的条目和字段类型。在knitr中有一个helper函数write_bib() ，可以为R包自动生成BibTeX条目，例如:

  1. # the second argument can be a .bib file
  2. knitr::write_bib(c("knitr", "stringr"), "", width = 60)
  1. @Manual{R-knitr,
  2.   title = {knitr: A General-Purpose Package for Dynamic
  3.     Report Generation in R},
  4.   author = {Yihui Xie},
  5.   year = {2021},
  6.   note = {R package version 1.33},
  7.   url = {https://yihui.org/knitr/},
  8. }
  9. @Manual{R-stringr,
  10.   title = {stringr: Simple, Consistent Wrappers for Common
  11.     String Operations},
  12.   author = {Hadley Wickham},
  13.   year = {2019},
  14.   note = {R package version 1.4.0},
  15.   url = {https://CRAN.R-project.org/package=stringr},
  16. }
  17. @Book{knitr2015,
  18.   title = {Dynamic Documents with {R} and knitr},
  19.   author = {Yihui Xie},
  20.   publisher = {Chapman and Hall/CRC},
  21.   address = {Boca Raton, Florida},
  22.   year = {2015},
  23.   edition = {2nd},
  24.   note = {ISBN 978-1498716963},
  25.   url = {https://yihui.org/knitr/},
  26. }
  27. @InCollection{knitr2014,
  28.   booktitle = {Implementing Reproducible Computational
  29.     Research},
  30.   editor = {Victoria Stodden and Friedrich Leisch and Roger
  31.     D. Peng},
  32.   title = {knitr: A Comprehensive Tool for Reproducible
  33.     Research in {R}},
  34.   author = {Yihui Xie},
  35.   publisher = {Chapman and Hall/CRC},
  36.   year = {2014},
  37.   note = {ISBN 978-1466561595},
  38.   url = {http://www.crcpress.com/product/isbn/
  39.     9781466561595},
  40. }

Once you have one or multiple .bib files, you may use the field bibliography in the YAML metadata of your first R Markdown document (which is typically index.Rmd), and you can also specify the bibliography style via biblio-style (this only applies to PDF output), e.g.,

一旦你有一个或多个 .bib文件，你可以在你的第一个R Markdown文档(通常是 index.Rmd)的YAML元数据中使用 bibliography 字段，你也可以通过biblio-style指定参考书目风格(这只适用于PDF输出)，例如:

  1. ---
  2. bibliography: ["one.bib", "another.bib", "yet-another.bib"]
  3. biblio-style: "apalike"
  4. link-citations: true
  5. ---

The field link-citations can be used to add internal links from the citation text of the author-year style to the bibliography entry in the HTML output.

When the output format is LaTeX, the list of references will be automatically put in a chapter or section at the end of the document. For non-LaTeX output, you can add an empty chapter as the last chapter of your book. For example, if your last chapter is the Rmd file 06-references.Rmd, its content can be an inline R expression:
字段link-citation可用于将内部链接从author-year风格的引文文本添加到HTML输出中的参考书目条目。
当输出格式为LaTeX时，引用列表将自动置于文档末尾的章节或节中。对于非latex输出，可以添加一个空章节作为书的最后一章。例如，如果您的最后一章是Rmd文件06-references.Rmd，其内容可以是一个内联的R表达式:

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

For more detailed instructions and further examples on how to use citations, please see the “Citations” section of the Pandoc manual.

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

References

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

  1. The type name is case-insensitive, so it does not matter if it is manual, Manual, or MANUAL.↩︎