Pandoc 表格原生编号深入解析从 5474-tables.md 测试用例看 opendocument native_numbering【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本文以仓库中的命令测试用例 5474-tables.md 为切入点深入剖析 Pandoc 将 Markdown 表格转换为 OpenDocumentLibreOffice 原生格式时native_numbering扩展如何为表格标题Table Caption注入格式自有的计数器字段实现Table 1 / Table 2式的自动编号。读完本文你将掌握该扩展的启用方式、编号机制的原理text:sequence字段、表格样式与对齐在 OpenDocument 输出中的落地规则并能借助仓库源码OpenDocument.hs与测试体系复现和验证这一行为。测试用例全貌一条命令两个表格测试文件 test/command/5474-tables.md 是 Pandoc 命令测试套件中的一个典型用例它以输入 → 期望输出的形式验证某个具体功能在特定命令行参数下的行为。整个用例可拆解为三部分。输入命令与文档内容% pandoc -t opendocumentnative_numbering Right Left ------- ------ 12 11 : First table Right Left ------- ------ 13 14 : Second Table ^D% pandoc ...是命令测试的固定书写格式%之后为待执行的 pandoc 命令^D表示标准输入结束EOF即待转换的 Markdown 文档内容通过 stdin 传入-t opendocumentnative_numbering指明输出格式为opendocument并显式开启native_numbering扩展。输入文档包含两个带标题caption的简单表格第一个表格数据为 12/11标题 First table第二个表格数据为 13/14标题 Second Table。两个表格均为右对齐的两列Right、Left。期望输出OpenDocument XML测试的第二部分是期望的标准输出即完整的 OpenDocument XML 片段。以第一个表格为例text:p text:style-nameTableCaptionTable text:sequence text:ref-namerefTable0 text:nameTable text:formulaooow:Table1 style:num-format11/text:sequence: First table/text:p table:table table:nameTable1 table:style-nameTable1 table:table-column table:style-nameTable1.A / table:table-column table:style-nameTable1.B / table:table-header-rows table:table-row table:table-cell table:style-nameTableHeaderRowCell office:value-typestring text:p text:style-nameP1Right/text:p /table:table-cell table:table-cell table:style-nameTableHeaderRowCell office:value-typestring text:p text:style-nameTable_20_HeadingLeft/text:p /table:table-cell /table:table-row /table:table-header-rows table:table-row table:table-cell table:style-nameTableRowCell office:value-typestring text:p text:style-nameP212/text:p /table:table-cell table:table-cell table:style-nameTableRowCell office:value-typestring text:p text:style-nameTable_20_Contents11/text:p /table:table-cell /table:table-row /table:table第二个表格结构完全一致区别在于序列引用名变为refTable1编号显示为 2表格名为Table2单元格段落样式编号依次递推P3、P4。native_numbering 扩展是什么、何时启用扩展的定义在源码 src/Text/Pandoc/Extensions.hs 中该扩展被定义为| Ext_native_numbering -- ^ Use output formats native numbering for figures and tables即使用输出格式自有的编号机制为图表编号。默认启用情况同一个文件中getAll opendocument的分支Extensions.hs显示getAll opendocument extensionsFromList [ Ext_empty_paragraphs , Ext_native_numbering , Ext_xrefs_name , Ext_xrefs_number ]也就是说opendocument输出格式默认就启用了native_numberingodt同样继承这一组默认扩展。测试命令中-t opendocumentnative_numbering显式写出该扩展是为了让用例自文档化、不受默认值变化影响从而保证测试的稳定性。编号机制原理text:sequence 计数器字段源码调用链在 src/Text/Pandoc/Writers/OpenDocument.hs 的table写出函数中标题部分的分支逻辑为captionDoc - if null c then return empty else inlinesToOpenDocument o (blocksToInlines c) if isEnabled Ext_native_numbering o then numberedTableCaption ident else unNumberedCaption TableCaption若表格没有标题null c则完全不生成标题段落若有标题且启用了native_numbering调用numberedTableCaption若未启用该扩展则退化为unNumberedCaption TableCaption即只输出标题文字、不带任何编号MANUAL.txt 中明确写道If this extension is not enabled, tables and figures in these formats will not be numbered.。numberedTableCaptionOpenDocument.hs维护一个内部计数器stTableCaptionId每遇到一个表格标题就自增 1最终由numberedCaption生成标题段落。计数器字段的三个关键属性numberedCaptionOpenDocument.hs是编号字段的生成核心s inTags False text:sequence [ (text:ref-name, ident), (text:name, name), (text:formula, ooow: name 1), (style:num-format, 1) ] $ text $ show num对照测试输出Table text:sequence ...1/text:sequence: First table三个属性含义如下属性测试输出示例作用text:ref-namerefTable0、refTable1该序列字段的唯一引用名供xrefs_number/xrefs_name交叉引用使用若源表格未指定identifier则自动生成为ref 类型名 序号如refTable0text:nameTable序列类别名同类别计数器共享表格用Table插图用Illustrationtext:formulaooow:Table1LibreOffice 的序列公式每次遇到该字段Table类计数器 1style:num-format1编号的数字格式1表示阿拉伯数字字段的可见文本text:sequence标签包裹的1、2是 Pandoc 写出的初始值在 LibreOffice 中打开并刷新字段后编号会按公式重新计算。这与 MANUAL.txt 对xrefs_number的说明一致Numbers in cross-references are only visible in the final document once it has been refreshed.同理插图标题走numberedFigureCaptionOpenDocument.hs序列名称为Illustration使用独立的计数器stImageCaptionId——表格与插图各自独立编号。从输出反推样式与对齐规则测试输出不仅验证了编号还揭示了 OpenDocument 写手对表格样式命名的固定规则见 OpenDocument.hs 的paraTableStyles表格命名Table1、Table2按出现顺序编号列样式为Table1.A、Table1.BgenIds map chr [65..]即从字母A起逐列分配表头单元格统一使用样式TableHeaderRowCell数据单元格段落右对齐列使用按序生成的P1、P2样式其内嵌对齐属性为end左对齐默认列则复用预置样式Table_20_Heading表头与Table_20_Contents内容不额外生成新样式单元格office:value-typestring表明表格内容一律按字符串输出数字 12、11、13、14 也不例外。这正是测试输出中 Right 列单元格样式为P1/P2、而 Left 列样式为Table_20_Heading/Table_20_Contents的源码原因输入表格的两列中第一列Right右对齐第二列Left未显式指定对齐默认左对齐。标题位置CaptionAbove / CaptionBelowtable函数末尾还根据writerTableCaptionPosition决定标题与表格的先后顺序OpenDocument.hscase writerTableCaptionPosition opts of CaptionAbove - captionDoc $$ tableDoc CaptionBelow - tableDoc $$ captionDoc测试输出中标题段落text:p ...Table 1: First table/text:p位于table:table ...之前对应默认的CaptionAbove标题在表格上方。该选项在 CLI 中由--table-caption-positionabove|below控制插图标题则由--figure-caption-position控制。如何在本地复现与验证仓库的命令测试通过 test/Command.hs 驱动。手动复现该用例只需把测试输入中的文档内容存为input.md然后执行pandoc -t opendocumentnative_numbering input.md对比输出与test/command/5474-tables.md中期望的 XML若一致说明当前构建的 Pandoc 行为符合该功能预期。若想观察扩展关闭时的差异可改为pandoc -t opendocument-native_numbering input.md此时按 MANUAL.txt 的说明表格标题将不再携带编号unNumberedCaption TableCaption分支只输出纯文字标题。对odt格式执行相同转换则可得到可直接用 LibreOffice 打开、带自动刷新编号字段的文档进一步验证刷新后编号可见的行为。关联知识xrefs_name 与 xrefs_numbernative_numbering常与opendocument默认开启的另外两个扩展搭配使用MANUAL.txtxrefs_name把指向标题/图表的内链替换为使用被引用项名称或标题的交叉引用xrefs_number把内链替换为使用被引用项编号的交叉引用编号来源正是text:sequence字段——因此 MANUAL 特别提示要让xrefs_number生效必须同时启用native_numbering等让标题带编号的机制。在源码 OpenDocument.hs 中sequenceRef根据两个扩展的开关组合选择编号名称仅名称仅编号三种引用形式并通过text:sequence-ref引用refTable0/refTable1这类序列引用名——这正是测试输出中text:ref-name存在的原因之一。小结一个看似只有 63 行的测试用例完整串联了 Pandoc 的扩展系统Extensions.hs、OpenDocument 写手OpenDocument.hs与官方手册MANUAL.txt三层代码事实native_numbering通过text:sequence计数器字段让 LibreOffice 在刷新后自动维护表格/插图编号默认启用、可显式开关编号与xrefs_number交叉引用机制深度耦合。理解这条调用链你就掌握了 Pandoc 输出 OpenDocument 时表格编号—引用—刷新的完整数据流也学会了如何像test/command/5474-tables.md一样用最小化用例验证输出格式的每一个细节。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考