Pandoc 引文标点位置控制：`notes-after-punctuation` 元数据深度解析

Pandoc 引文标点位置控制notes-after-punctuation元数据深度解析【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读在使用 pandoc 的--citeproc处理脚注式note style或上标数字式引文时引文标记应该放在逗号、句号之前还是之后是一个典型的排版细节问题英文排版惯例通常是脚注序号紧跟标点之后works,[1]而许多作者却习惯写成works[1],。Pandoc 通过 YAML 元数据字段notes-after-punctuation提供了精确控制其行为差异由 test/command/7826.md 中的五个命令测试用例完整覆盖。本文将基于该测试文档展开结合 src/Text/Pandoc/Citeproc.hs 的源码实现与 MANUAL.txt 的官方说明逐条剖析该选项在 AMA、芝加哥全注释Chicago full note与作者-日期等不同引文风格下的真实行为帮助你彻底掌握引文与标点的排布规则。为什么需要控制引文与标点的相对位置在学术写作中引文标记脚注序号、上标数字或括号引用通常出现在句子末尾。不同引文风格对标点相对位置有不同约定数字上标风格如 AMA、Vancouver上标引文号通常写在句号、逗号之后例如In recent works,^(1,2)。脚注风格如 Chicago full note脚注序号通常紧跟标点之后美式排版惯例例如recent works,[1]。作者-日期风格如 APA、Chicago author-date括号引文属于句子成分的一部分一般不随标点移动。Pandoc 的 citeproc 模块需要针对这些差异提供可配置行为而notes-after-punctuation正是控制引文标记是否移动到其后标点之后的开关。它同时影响两类内容脚注引用[^1]和上标形式的数字引文^(1,2)。测试文档7826.md全景五个场景一个开关test/command/7826.md 是一个 pandoc 命令测试command test文件其格式为%开头的命令行 输入文档以^D结束 期望输出。五个用例共用同一句输入文本In numerous recent works [item1; item2], statistician Foo and Bar have criticized XXX.所有用例都使用pandoc -t plain --citeproc并设置了bibliography: command/biblio.bib与suppress-bibliography: true。suppress-bibliography的作用是隐藏文末参考文献列表使测试输出只聚焦于正文中引文标记的位置变化。下面逐一分析五个场景。场景一AMA 上标风格 notes-after-punctuation: truebibliography: command/biblio.bib suppress-bibliography: true csl: command/american-medical-association.csl notes-after-punctuation: true输入works [item1; item2], statistician引文后跟逗号输出为In numerous recent works,^(1,2) statistician Foo and Bar have criticized XXX.开启该选项后上标^(1,2)从逗号之前被移动到逗号之后得到符合 AMA 排版惯例的works,^(1,2)。场景二AMA 上标风格 默认值不设置该字段bibliography: command/biblio.bib suppress-bibliography: true csl: command/american-medical-association.csl输出为In numerous recent works^(1,2), statistician Foo and Bar have criticized XXX.AMA 属于文中引用in-text风格而非脚注风格因此默认不移动上标保持原位置在逗号之前输出works^(1,2),。对比场景一可见同样是 AMA 风格一个开关即可改变上标与标点的相对顺序。场景三Chicago full note 脚注风格 notes-after-punctuation: falsebibliography: command/biblio.bib suppress-bibliography: true csl: command/chicago-fullnote-bibliography.csl notes-after-punctuation: false输出为In numerous recent works[1], statistician Foo and Bar have criticized XXX. [1] John Doe, First Book (Cambridge: Cambridge University Press, 2005); John Doe, Article, Journal of Generic Studies 6 (2006): 33–34.关闭该选项后脚注序号[1]停留在逗号之前。同时注意因为suppress-bibliography: true只抑制参考文献列表脚注本身仍然输出在正文之后plain 格式下显示为编号列表。item1 与 item2 同属作者 John Doe芝加哥全注释风格将其合并为同一条脚注并以分号列出两条文献。场景四Chicago full note 脚注风格 默认值脚注风格默认 truebibliography: command/biblio.bib suppress-bibliography: true csl: command/chicago-fullnote-bibliography.csl输出为In numerous recent works,[1] statistician Foo and Bar have criticized XXX. [1] John Doe, First Book (Cambridge: Cambridge University Press, 2005); John Doe, Article, Journal of Generic Studies 6 (2006): 33–34.这是脚注风格的默认行为[1]被移动到逗号之后输出works,[1]符合美式排版惯例。对比场景三同一输入在默认与false之间只有标点与序号的位置互换其余输出完全一致。场景五作者-日期风格 notes-after-punctuation: truebibliography: command/biblio.bib suppress-bibliography: true notes-after-punctuation: true此用例未指定csl使用 pandoc 默认的作者-日期风格Chicago author-date 风格。输出为In numerous recent works (Doe 2005, 2006), statistician Foo and Bar have criticized XXX.即使显式开启notes-after-punctuation: true括号引文(Doe 2005, 2006)也不会移动位置——该选项只作用于脚注序号与上标数字引文。另外注意item1 与 item2 作者相同John Doe作者-日期风格将两条引用压缩为(Doe 2005, 2006)。源码级原理moveNotes判定与mvPunct移动算法notes-after-punctuation的处理逻辑集中在 src/Text/Pandoc/Citeproc.hs。在processCitations中首先读取元数据并决定是否启用移动let moveNotes maybe (styleIsNoteStyle sopts) truish (lookupMeta notes-after-punctuation meta)这段代码src/Text/Pandoc/Citeproc.hs揭示了默认值的来源若 YAML 中未设置notes-after-punctuation则取styleIsNoteStyle sopts——即脚注风格note style默认移动非脚注风格默认不移动。这正对应测试场景二AMA 不移动与场景四Chicago full note 移动若显式设置则用truish解析布尔值显式值覆盖风格默认值对应场景一、三、五。关键的移动逻辑在mvPunct函数src/Text/Pandoc/Citeproc.hs源码注释直接给出了两条转换规则-- x [^1], - x,[^1] 引文前有空格空格折叠序号移到逗号后 -- x[^1], - x,[^1] 引文紧贴前文同样把序号移到逗号后mvPunct逐 Inline 元素扫描命中Cite且其末尾元素isNote为真、后续紧跟标点时若moveNotes为真则将标点字符串提取出来放到引文之前并从后续文本中删除该标点。这解释了测试中逗号被挪到上标/序号前面、同时空格被折叠的完整行为。isNote的定义src/Text/Pandoc/Citeproc.hs值得特别注意-- the following allows citation styles that are in-text but use superscript -- references to be treated as if they are notes for the purposes of moving -- the citations after trailing punctuation isNote (Superscript _) True isNote _ False即凡是以上标形式呈现的引文数字如 AMA、Vancouver 等数字上标风格即便在风格分类上属于 in-text 风格也按脚注处理可以被移动到标点之后。这正是场景一AMA true 移动成功能够成立的实现基础。此外isPunctsrc/Text/Pandoc/Citeproc.hs排除了破折号isPunct c isPunctuation c c / \x2014 c / \x2013即 em-dash—U2014与 en-dash–U2013不算作可穿越的标点脚注序号不会围绕破折号移动。同一函数中还包含movePunctInsideQuotes逻辑它与 locale 的punctuation-in-quote设置联动负责处理引文位于引号内时的标点归位。官方文档中的定义与使用边界MANUAL.txt 对该选项给出了权威说明notes-after-punctuation: If true (the default for note styles), pandoc will put footnote references or superscripted numerical citations after following punctuation. For example, if the source containsblah blah [jones99]., the result will look likeblah blah.[^1], with the note moved after the period and the space collapsed. If false, the space will still be collapsed, but the footnote will not be moved after the punctuation. The option may also be used in numerical styles that use superscripts for citation numbers (but for these styles the default is not to move the citation).关键结论可归纳为设置值脚注风格note style上标数字风格如 AMA作者-日期风格未设置默认移动默认 true不移动默认 false不移动true移动移动不移动括号引文不受影响false不移动不移动不移动另外两点边界需要记住空格折叠始终生效即使false不移动序号引文前多余的空格仍会被折叠works [jones99].会变为works[^1].而非works [^1].仅作用于脚注与上标作者-日期风格的括号引文属于句子成分永远不会被移动场景五即验证了这一行为。测试资源与复现方法7826.md依赖的测试资源均位于 test/command 目录biblio.bib包含item1BookJohn Doe2005Cambridge University Press、item2ArticleJohn Doe2006Journal of Generic Studies与пункт3InCollectionJohn Doe Jenny Roe2007三条文献。前两条作者相同因此在上标风格下合并为^(1,2)、在作者-日期风格下合并为(Doe 2005, 2006)、在全注释风格下合并为同一条脚注american-medical-association.cslAMA 数字上标风格测试场景一、二使用chicago-fullnote-bibliography.csl芝加哥全注释脚注风格测试场景三、四使用。若想本地复现可在test/目录下直接执行测试命令例如pandoc -t plain --citeproc --bibliography command/biblio.bib \ --metadata suppress-bibliographytrue \ --metadata notes-after-punctuationtrue \ --csl command/american-medical-association.csl然后在 stdin 中输入测试文本以^D结束。注意测试文档中 YAML 内路径command/biblio.bib是相对于test/目录的写法若在仓库根目录运行应使用test/command/biblio.bib等相对路径。实战建议投稿或排版有明确风格要求时先查阅目标风格对标点位置的规定再显式设置notes-after-punctuation不要依赖默认值——同一个开关在 AMA 与 Chicago full note 下默认行为恰好相反数字上标风格需要标点后置时务必显式设置notes-after-punctuation: true因为这类风格的默认值是不移动见场景一与场景二的对比使用-s生成独立文档时将上述元数据写入 YAML 元数据块而非命令行参数便于与bibliography、csl一同纳入版本管理排查引文位置异常时可先关闭suppress-bibliography观察完整输出再借助 src/Text/Pandoc/Citeproc.hs 中mvPunct的注释规则理解转换方向避免把默认不移动误判为 bug。小结notes-after-punctuation是 pandoc citeproc 体系中一个小而精的排版开关它的默认值由 CSL 风格类型是否 note style决定显式设置可覆盖默认它只作用于脚注序号与上标数字引文对括号式作者-日期引文无效即使关闭移动空格折叠依然生效。围绕 test/command/7826.md 的五个用例我们完整还原了该选项在 AMA、Chicago full note 与作者-日期三种风格下的输出差异并深入到 src/Text/Pandoc/Citeproc.hs 的moveNotes判定与mvPunct算法从源码与测试两个层面确认了行为依据。掌握这一选项即可在跨风格写作时精准控制引文标点排布避免反复手工调整。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考