文档格式：注释与引用

#脚注

脚注由两部分组成：引用处的标号[^id]，以及定义，即本章任意位置以[^id]:开头的独立段落。

The keeper climbed the tower every evening.[^steps] The wind put out his candle,
so he learned to count the steps in the dark.
 
[^steps]: The cast-iron staircase has 112 steps; the tower was built in 1861.

• 标号。[^id]把脚注编号印成上标，紧贴前面的词（写在标点之后，如上例）。id可包含字母、数字、-、_、.和:。标号可用于段落、列表项、引用块和标注框；在标题、题注和表格单元格中照原样印出。
• 定义。以[^id]:开头的段落；其文本一直延续到下一个空行，可带常见的行内标记（粗体、斜体、链接、:ref、公式、行内标签）。定义无论写在哪里都会离开文字流，因此可以放在引用它的段落下方，也可以全部集中在章末。同一id以第一个定义为准。
• 编号。脚注按首次引用的顺序编号，每章（一级标题，以及书中的每个文档）重新开始；被引用两次的脚注保留第一次的编号，只排一次。footnotes.numbering: 'document'让编号贯穿全书，'page'像中文书那样每页重新编号；footnotes.numberFormat: 'circled-decimal'在基线上排出① ② ③。footnotes.numberFormat: 'symbols'像期刊那样用*、†、‡、§、‖、¶标注，用完后成对重复，每页重新开始。
• 日文文本。把标号写在句末的。之前（先生[^1]。）：它跟随前一个字符，而。从不出现在行首。日文竖排书默认把标号（1）排在行的右侧，把注文排在章末；footnotes.markerPosition: 'side'在词旁排一个小标号，不占行内空间；footnotes.placement: 'spread'把注文排在每个跨页的正文旁边（见配置 › 脚注）。
• 脚注的位置。默认排在引用它的那一行所在栏的底部，上方有一条短线：该行与其脚注总在同一栏，脚注放不下时，该行会随脚注一起移走。单栏版面中就是页面底部。footnotes.placement: 'chapterEnd'则把一章的所有脚注排在该章最后一个块之后，默认位于它们结束的那一栏的底部。字号、分隔线和间距见配置参考中的脚注。
• 检查。没有定义的标号（undefinedFootnote）在空脚注上印出编号；没有标号引用的定义（unusedFootnote）不排。沙盒在检查面板中列出这两种情况。

#交叉引用与锚点

交叉引用指向书中的某个位置，并印出它的编号、标题或页码：见第3.2节、第4章已说明、见第112页。文字和编号随正文变化：移动一节、重新编号各章或重新排版全书，所有引用都会更新。在PDF、HTML和Sandbox预览中，每个引用都是链接，点击即可跳到目标，跨章也可以。

锚点。 引用需要一个指向的目标：

• 带标识符的标题：## 方法 {#sec-method}（Pandoc的写法；也可写id="sec-method"）。
• 带标识符的框或其他容器：:::callout{#box-safety title="安全"}。编号样式的框（定理）按标签和编号引用：定理2。
• 带\label{eq:x}的独立公式（见数学公式）：引用印出与公式相同的编号，(3)。
• 正文中的一点：:anchor{#key-idea}设一个不可见的锚点；[关键思想]{#key-idea}保留文字并为其命名。

标识符可用字母、数字、-、_、.和:，在全书中必须唯一：检查面板会列出重复的标识符（duplicateAnchor），引用指向第一个。

引用。 :ref{id="…"}指向锚点的方式与指向图表相同：

## 方法 {#sec-method}
 
:ref{id="sec-method"}的结论见:ref{id="sec-method" style=page}。

正文中也可以写LaTeX的\eqref{x}和\ref{x}：\eqref相当于不设style的引用，\ref相当于style=number，所以\ref{thm:main}印出2，\ref{fig:map}印出图的编号。紧挨在它们前面的~是不断行空格（Theorem~\ref{thm:main}）。写在$…$之内时，它们属于公式。

text="…"印出自定的文字，仍然是链接；case=capitalize使西文名称首字母大写。文字随文档语言变化（section 3.2、sección 3.2、第3.2节），可在配置的交叉引用中修改；编号模板已含文字的标题（第四章、Chapter 4）照原样印出。在竖排中，引用里的数字按cjk.uprightDigits的规则排列。

换行。 以文字印出的引用与周围正文一样在空格处换行：锚点的文字（[close the lever so that it points backwards]{#step}）、标题、自定的text="…"。其中的空格就是行内的空格，在两端对齐的行里与其他空格一同拉伸；引用仍是一个链接，跨两行时分成两段。其中的词从不断词。在这样的引用文字里，数字、罗马数字或单个字母与它前面的词不分开，所以text="Fig. 1a"、text="plate IV"不会被拆到两行。带编号或页码的引用文字（section 3.2、p. 112、Fig. 1.7、Theorem 2）从不换行，不论模板里用的是哪种空格；引用文字中的不断行空格与在别处一样把两边粘住。crossRefs.breakLabels: false让每个引用文字保持完整，与postext 1.27及更早版本相同，那时引用文字是一个词，无法移上前一行；见交叉引用。

页码引用要在全书排好后才知道。引擎会用上一遍的页码重新排版，直到页码不再变化，与目录的做法相同；在此之前页码印为*?*。

pandoc-crossref。 为pandoc-crossref写的文本照样可读：@sec:method、[@fig:map]，[-@tbl:data]只印编号。前缀（sec、fig、tbl、eq、lst）可以是标识符的一部分（{#sec:method}），也可以不写（{#method}）。紧贴在词后的@（如电子邮件地址）仍是文本。

指向不存在的id的引用印为*?*，并在检查面板中列出（unknownResourceId）。在Sandbox编辑器中输入@，会列出书中的图、表、带标识符的标题和锚点。

#引用与参考文献

按Pandoc的写法书写引用，把参考文献保存在文档中，在设置里选择引用样式：从APA换成IEEE或芝加哥注释体，只需改设置中的样式，不必改正文。每条引用都链接到参考文献表中的对应条目。

#引用

正如[@garcia2020, 页 33]所示，纸上阅读更快[参见 @lopez2019, 章 2; @bringhurst2004]。
@garcia2020 [页 4]说得很清楚；2020年的研究[-@garcia2020]也同意。

• [@key]：括号引用；多个文献放在同一对方括号中，用;分隔。
• 位置（locator）：逗号之后写页 33、p. 33、pp. 4–6、章 2、chap. 2、§ 4.2等；只写数字表示页码。范围用短破折号，也可以用TeX的两个连字符：pp. 4--6排出来是4–6。
• 前缀与后缀：@之前的文字（参见）和键或位置之后的文字（, 着重号为引者所加）。后缀保留写在它前面的逗号，无论有没有位置：[@brown2020, inter alia]印作*(Brown et al., 2020, inter alia)*，与 Pandoc 一致；不写逗号（[@brown2020 inter alia]）就没有逗号。前缀和后缀中的强调在所有样式中都排成强调：[*e.g.*, @brown2020, *inter alia*]。
• [-@key]：省略著者，用于正文已提到著者的句子。
• @key：叙述式引用（García (2020)）；@key [页 4]加上位置。
• 图表题注：图或表的题注及其注释可以像正文一样引用（此前最好成绩见[@cobbe2021]。）。其中的文献无需nocite即收入参考文献表；顺序编码制按资源放置的位置编号，即排在第一次提到它的段落（其::resource块或第一个:ref）的引用之后。表格单元格中的引用仍按原文印出。
• 紧贴在字母或数字后的@（电子邮件地址）、行内代码中的@以及\@都是普通文字。书中没有对应参考文献的引用按原文印出，所以没有参考文献的文档读起来与以前一样。多文献引用中若有未定义的键，该键以粗体排在其余引用之后（（Glen，1955）**@nye1953**），缺失的文献在页面上和检查警告中都能看到。引用后的冒号是正文：[@french2018]：……。
• 在中文、日文和韩文正文中，引用紧接前一个字，不加空格（周明远@zhou2019认为）；著者-出版年引用采用与正文一致的全角标点：（施雅风等，1988；刘时银等，2015）。

#参考文献数据

参考文献以CSL格式（Zotero和Pandoc使用的数据模型）写在文档中：

---
references:
  - id: zhang2018
    type: book
    language: zh-CN
    author: [张三, 李四, 王五, 赵六]
    title: 排版学
    issued: 2018
    publisher: 商务印书馆
    publisher-place: 北京
nocite: "@lopez2019"
---

也可以写在:::references块中，格式为BibTeX（Zotero、JabRef、Google学术导出的格式）、CSL-JSON或CSL-YAML：

:::references{format=bibtex}
@book{zhang2018, author = {张三 and 李四}, title = {排版学}, publisher = {商务印书馆},
  address = {北京}, year = {2018}, langid = {chinese}}
:::

该块本身不印任何内容。nocite列出不引用但要收录的文献（@*表示全部）。在书中，任何一章里写的参考文献对全书有效。

在 BibTeX 的姓名列表中，and others代表省略的著者（author = {Tan, Wei and others}）：各样式在该处印出“等”或 et al.。在 YAML 中，把others写作列表的最后一个姓名。

#参考文献表

:::bibliography在其所在位置排出所引文献的列表；没有它时，列表放在最后一章之后，标题采用文档语言（参考文献、References）。:::bibliography{title="引用文献"}修改标题，title=""不印标题；scope=chapter只列出本章引用的文献（适用于合集）。每个条目都是一个锚点（ref-<key>），因此指向#ref-zhang2018的Markdown链接可以跳到它，PDF中将其标记为BibEntry。

scope=new列出文档中到此为止引用过、且之前的列表尚未印出的文献，按样式的顺序和编号排列：在正文之后放一个:::bibliography{scope=new}，在方法部分之后再放一个，就得到 Nature 论文的两个列表，第二个接着第一个编号。顺序编码制默认在全书连续编号；设置citations.numbering: 'chapter'后，每章（每个文档，以及引用之后的每个一级标题）从 1 开始编号，章内列表也使用这些编号，适用于简报中的各篇报告或会议论文集。

#样式

样式决定引用和条目的内容。内置样式见下表；其他任何CSL样式（Zotero样式库中有一万多种）都可以在设置 → 引用与参考文献中从.csl文件加载。

使用注释体样式时，每条引用成为一个脚注，按脚注设置放置和编号；同一文献的后续引用采用简略形式。在中文正文中，citations.notes: 'warichu'把引用排成行内双行夹注；夹注后紧跟中文标点（，、。）时，省去夹注末尾的句点。

中文。 GB/T 7714-2015样式写出文献类型标识（[M]、[J]、[D]、[EB/OL]），中文姓名完整保留，三位以上著者时中文文献写等、西文文献写et al.，依据每条文献的language判断。竖排时，上标编号位于所注字的右侧；citations.marker: 'corner'写作〔1〕，在竖排中保持直立。

引擎。 引用由postext-citeproc包（citeproc-js与CSL样式）排版。Sandbox会为有引用的文档加载它；在自己的代码中，排版前先注册：

import 'postext-citeproc/register';

检查面板会列出没有参考文献定义的键（unknownCitationKey）和无法读取的参考文献块（referencesUnreadable）。

#索引

书后索引列出书中的术语及其出现的页码。在正文讨论某个术语的地方标记它，再用:::index在需要的位置印出索引，通常放在书末单独的一章。排版完成后，引擎找出每个标记所在的页，因此页码随正文变化：增加一段、移动一章或改变成品尺寸，索引都会印出新的页码。

Iron-deficiency :index[anaemia] is the most common kind.
The pulse is taken at the wrist.:index{term="Pulse!radial" main}
 
# Index {style="index"}
 
:::index

#索引标记

• :index[text]印出text，并以它本身的词作为条目。内部的行内标记会印出，但不进入条目。方括号后的属性可把它归到别的条目下：:index[iron deficiency]{term="Anaemia!iron-deficiency"}。
• :index{term="…"}什么都不印。标记取所在行中紧挨在它前面的词所在的页；若它位于行首，则取它后面的词所在的页。只含标记的行会被删除，因此单独成行的标记从不拆开段落，也不增加空白。
• 适用位置。段落、标题、列表项、引用块、标注框和脚注定义。在题注、表格单元格和设计元素中，标记照原样印出。在行内代码中以及反斜杠之后（\:index），它是文本。

没有术语的标记（单独的:index{}或:index{see="…"}）不索引任何内容，并报出indexMarkInvalid。

#印出索引

:::index在所在位置印出主索引，:::index{index="names"}印出具名索引。该指令展开为普通的块，每个条目一块，像正文一样流过各栏和各页：放在标题样式设定了两栏layout的标题之下，就得到常见的两栏索引。点击某个条目会跳到该指令所在的行。

# Index of names {style="index"}
 
:::index{index="names"}
 
# Index of subjects {style="index"}
 
:::index

• 顺序。条目按文档语言（locale或index.locale）的字母顺序排序：带重音的字母与其基本字母归在一起（Árbol归在A下），西班牙语中ñ排在n之后，自成一组。以符号开头的条目排在最前，其次是以数字开头的，然后是字母。子条目在其条目下以同样方式排序，每深一级缩进一级。日文索引按JIS X 4061的顺序依读音排序，按五十音行（あ行、か行…）分组，拉丁条目排在假名之前（见日文排版 › 五十音顺索引）。
• 分组。每出现一个新的首字母就开启一组：一个字母标题（index.groups），其上方空一行（第一组上方不空）。字母标题与该组第一个条目排在同一个块中，因此不会单独留在栏末；没有自身页码的条目（只作为其子条目的上级）出于同样原因与其第一个子条目排在一起。
• 页码。使用页面上印出的页码标签，包括前置部分的罗马数字页码。条目的页码经过排序且每页只列一次；连续的页合并为范围（12–14，index.mergeRanges），落在同一条目某个范围内的页并入该范围（其中若有主要页，整个范围排成粗体），index.rangeFormat: 'chicago'会缩短第二个数字（234–37）。粗体（主要）页码单独列出。在PDF中，每个页码都链接到对应的页。
• 参见位于条目末尾：条目没有页码时为Term. See Target，有页码时为Term, 12. See also Target。这些标签随文档语言变化（See、Véase……），可在index.see中设定。
• 图书。在逐章排版的书中（沙盒、buildBundle），印出索引的那一章会收到所有章节的标记及其页码，只有当其中某个标记移动时才重新排版。同时包含标记和索引的文档会反复排版，直到页码稳定，与:::toc相同。

排版样式、缩进和分隔符见配置参考中的索引。