Pandoc 用户使用指南 - 引文

当使用 --citeproc 选项时，pandoc 可以自动生成各种样式的引文和参考文献列表。基本用法如下：

pandoc --citeproc myinput.txt

要使用此功能，您需要具备以下条件：

包含引文的文档（参见引文语法）；
引文数据来源：外部参考文献文件或文档 YAML 元数据中的 references 列表；
可选地，一个 CSL 引文样式。

指定引文数据

您可以使用 YAML 元数据部分中的 bibliography 元数据字段或命令行参数 --bibliography 来指定外部参考文献文件。如果您想使用多个参考文献文件，可以提供多个 --bibliography 参数或将 bibliography 元数据字段设置为 YAML 数组。参考文献可以是以下格式之一：

格式	文件扩展名
BibLaTeX	.bib
BibTeX	.bibtex
CSL JSON	.json
CSL YAML	.yaml
RIS	.ris

注意

.bib 可以同时用于 BibTeX 和 BibLaTeX 文件；使用 .bibtex 扩展名以强制将其解释为 BibTeX。

在 BibTeX 和 BibLaTeX 数据库中，pandoc 解析如 title 字段等中的 LaTeX 标记；在 CSL YAML 数据库中，pandoc Markdown；在 CSL JSON 数据库中，一种类似 HTML 的标记：

<i>...</i>
    斜体
<b>...</b>
    加粗
<span style="font-variant:small-caps;">...</span> 或 <sc>...</sc>
    小大写字母
<sub>...</sub>
    下标
<sup>...</sup>
    上标
<span class="nocase">...</span>
    防止短语被转换为标题大小写

作为使用 --bibliography 或 YAML 元数据字段 bibliography 指定参考文献文件的替代方法，您可以在文档的 YAML 元数据的 references 字段中直接包含引文数据。该字段应包含 YAML 编码的引用数组，例如：

---
references:
  - type: article-journal
    id: WatsonCrick1953
    author:
      - family: Watson
        given: J. D.
      - family: Crick
        given: F. H. C.
    issued:
      date-parts:
        - - 1953
          - 4
          - 25
    title: "Molecular structure of nucleic acids: a structure for
      deoxyribose nucleic acid"
    title-short: Molecular structure of nucleic acids
    container-title: Nature
    volume: 171
    issue: 4356
    page: 737-738
    DOI: 10.1038/171737a0
    URL: https://www.nature.com/articles/171737a0
    language: en-GB

如果同时提供了外部参考文献和内联（YAML 元数据）引用，则会使用两者。在 id 冲突的情况下，内联引用将优先考虑。

注意

pandoc 可以从 BibTeX、BibLaTeX 或 CSL JSON 参考文献生成此类 YAML 元数据部分：

pandoc chem.bib -s -f biblatex -t markdown
pandoc chem.json -s -f csljson -t markdown

实际上，pandoc 可以在这些引文格式之间进行转换：

pandoc chem.bib -s -f biblatex -t csljson
pandoc chem.yaml -s -f markdown -t biblatex

使用 --citeproc 选项运行 pandoc 以从参考文献文件创建所需格式的格式化参考文献列表：

pandoc chem.bib -s --citeproc -o chem.html
pandoc chem.bib -s --citeproc -o chem.pdf

标题中的大写

如果您使用的是 bibtex 或 biblatex 参考文献，请遵守以下规则：

英文标题应使用标题大小写。非英文标题应使用句子大小写，并且 biblatex 中的 langid 字段应设置为相关语言。（以下值被视为英文：american、british、canadian、english、australian、newzealand、USenglish 或 UKenglish。）
按照 bibtex/biblatex 的标准，专有名词应使用大括号保护，以免在要求使用句子大小写的样式中变为小写。例如：
```
title = {My Dinner with {Andre}}
```
此外，应保持小写（或驼峰命名法）的单词也应受到保护：
```
title = {Spin Wave Dispersion on the {nm} Scale}
```
虽然这对于 bibtex/biblatex 并不是必需的，但对于 citeproc 却是必要的，因为它内部以句子大小写存储标题，并在需要时转换为标题大小写。在此处我们保护 "nm"，以免它在此阶段被转换为 "Nm"。

如果您使用的是 CSL 参考文献（JSON 或 YAML），则应遵守以下规则：

所有标题都应使用句子大小写。
对于非英文标题，使用 language 字段防止其在要求使用标题大小写的样式中转换。（仅当 language 以 en 开头或留空时才会发生转换。）

使用以下语法保护不应转换为标题大小写的单词：

Spin wave dispersion on the <span class="nocase">nm</span> scale

会议论文，已发表与未发表

对于正式发表的会议论文，使用 inproceedings 类型（这将映射到 CSL 的 paper-conference）。

对于未发表的手稿，使用 unpublished 类型而不带 eventtitle 字段（此类型将映射到 CSL 的 manuscript）。

对于演讲、未发表的会议论文或海报展示，使用带有 eventtitle 字段的 unpublished 类型（此类型将映射到 CSL 的 speech）。使用 type 字段来表示类型，例如 “Paper” 或 “Poster”。可能也会用到 venue 和 eventdate，尽管大多数 CSL 样式不会渲染 eventdate。请注意，venue 是事件的发生地点，与描述出版商位置的 location 不同；不要为未发表的会议论文使用后者。

指定引用样式

可以使用 Citation Style Language 支持的任何样式来格式化引用和参考文献，这些样式列在 Zotero Style Repository 中的 Citation Style Language。这些文件可以通过 --csl 选项或 csl（或 citation-style）元数据字段指定。默认情况下，pandoc 将使用 Chicago Manual of Style 的作者日期格式。（您可以通过将您选择的 CSL 样式复制到用户数据目录中的 default.csl 来覆盖此默认值。）CSL 项目提供了有关查找和编辑样式的更多信息。

可以通过 --citation-abbreviations 选项（或 citation-abbreviations 元数据字段）来指定包含应在格式化参考书目中使用的期刊缩写的 JSON 文件。该文件的格式可以通过示例说明：

{
  "default": {
    "container-title": {
      "Lloyd's Law Reports": "Lloyd's Rep",
      "Estates Gazette": "EG",
      "Scots Law Times": "SLT"
    }
  }
}

笔记样式中的引用

Pandoc 的引用处理旨在允许您在作者日期、数字和笔记样式之间移动，而无需修改 Markdown 源。当您使用笔记样式时，请避免手动插入脚注。相反，就像在作者日期样式中一样插入引用——例如，

Blah blah [@foo, p. 33].

脚注将自动生成。Pandoc 将负责删除空格并根据 notes-after-punctuation 的设置，在句号之前或之后移动注释，如下文其他相关元数据字段中所述。

在某些情况下，您可能需要在常规脚注中放置引用。普通引用（如 [@foo, p. 33]）将在括号中呈现。内联引用（如 @foo [p. 33]）将不带括号呈现。（如果适当的话，会添加逗号。）因此：

[^1]: 一些研究 [@foo; @bar, p. 33] 表明 frubulicious zoosnaps 是量化性的。 对于文献综述，参见 @baz [chap. 1].

参考文献的位置

如果样式要求列出引用的作品，则会将其放在具有 id refs 的 div 中，如果存在的话：

::: {#refs}
:::

否则，它将放在文档的末尾。通过在 YAML 元数据中设置 suppress-bibliography: true 来抑制参考文献的生成。

如果您希望参考文献有一个章节标题，可以在元数据中设置 reference-section-title，或者在具有 id refs 的 div 的开头（如果您正在使用它）或文档的末尾放置标题：

last paragraph...

# References

参考文献将在本标题之后插入。请注意，将为此标题添加 unnumbered 类别，因此该章节将不会被编号。

如果你想将参考文献放入模板中的变量，一种方法是在元数据字段中放入具有 id refs 的 div ，例如：

---
refs: |
  ::: {#refs}
  :::

你可以在模板中你想放置参考文献的位置放入变量 $refs$ 。

在参考文献中包含未引用的条目

如果你想在参考文献中包含未实际在正文文本中引用的条目，你可以定义一个虚拟的 nocite 元数据字段，并在那里放置引用：

---
nocite: |
@item1, @item2
...

@item3

在这个例子中，文档只包含对 item3 的引用，但参考文献将包含 item1、item2 和 item3 的条目。

通过使用通配符，可以创建包含所有引用的参考文献，无论它们是否出现在文档中：

---
nocite: |
@*
...

对于 LaTeX 输出，你也可以使用 natbib 或 biblatex 来呈现参考文献。为此，请按照上述方式指定参考文献文件，并向 pandoc 调用添加 --natbib 或 --biblatex 参数。请记住，参考文献文件必须是 BibTeX 格式（对于 --natbib）或 BibLaTeX 格式（对于 --biblatex）。

其他相关的元数据字段

有几个其他的元数据字段会影响参考文献的格式化：

link-citations

如果为真，则引用将被超链接到相应的参考文献条目（仅限作者日期和数字样式）。默认为假。
link-bibliography

如果为真，则参考文献中的 DOIs、PMCIDs、PMID 和 URL 将被渲染为超链接。（如果条目包含 DOI、PMCID、PMID 或 URL，但这些字段没有被样式渲染，则标题或如果没有标题则整个条目将被超链接。）默认为真。
lang

lang 字段将影响样式的本地化，例如标签的翻译、引号的使用以及条目的排序方式。（为了向后兼容，可以使用 locale 替代 lang，但这用法已被废弃。）

需要 BCP 47 语言标签：例如，en、de、en-US、fr-CA、ug-Cyrl。可以使用 unicode 扩展语法（在 -u- 之后）更精确地指定排序选项。这里有一些示例：
- zh-u-co-pinyin：使用拼音排序的中文。
- es-u-co-trad：使用传统排序（带有 Ch 排在 C 后面）的西班牙语。
- fr-u-kb：使用“反向”重音排序（带有 coté 排在 côte 后面）的法语。
- en-US-u-kf-upper：使用大写字母排在小写字母之前（默认为小写排在大写之前）的英语。
notes-after-punctuation

如果为真（笔记样式的默认值），pandoc 将在后面的标点符号之后放置脚注引用或上标数字引用。例如，如果源包含 blah blah [@jones99].，结果看起来像 blah blah.[^1]，脚注移到标点符号之后且空格被压缩。如果为假，则空格仍将被压缩，但脚注不会移动到标点符号之后。此选项也可用于使用上标进行引用编号的数字样式（但对于这些样式，默认值是不移动引用）。