pandoc pipe_tables 扩展解析从 #3734 命令测试看表格输出策略与相对列宽取舍【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc本篇文章以 pandoc 仓库中的命令测试 test/command/3734.md 为切入点深入解读 pandoc 在将文档转换为 Markdown 时如何决策使用 pipe table 还是 HTML 表格以及表格带相对列宽信息时的取舍逻辑。读者将掌握pipe_tables、raw_html扩展的组合规则、pipe table 的列宽计算原理并能看懂与复现 pandoc 官方的表格回归测试。一、测试文件 3734.md 在做什么test/command/3734.md是 pandoc 的命令测试command test文件。这类文件的格式定义在 test/Tests/Command.hs 的模块注释中以%开头的行是要执行的命令行后续若干行是通过 stdin 传入的输入以单独一行^D结束再往后的行是期望的 stdout 输出。该文件包含三个独立的测试用例输入完全相同——一个带有超长分隔线的 pipe table| aaaaaaaaaaaa | bbbbb | ccccccccccc | |--------------|-------|--------------------------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |三个用例分别是用例命令输出1pandoc -t markdown_strictpipe_tablespipe table列宽压缩2pandoc -t markdown_strictpipe_tables-raw_htmlpipe table列宽压缩3pandoc -t gfmpipe table更紧凑这三个用例共同验证了同一行为即使输入表格的分隔线长度暗示了相对列宽信息只要目标格式启用了pipe_tablespandoc 就优先输出 pipe table而不是退化为 HTML 表格。这一行为正是 issue #3734 修复的内容。二、问题背景相对列宽信息 vs 表格格式选择在 pandoc 的内部文档模型AST中表格的每一列都带有相对宽度width值为 0~1 之间的浮点数。当 Markdown 输入中分隔线的某个部分特别长时解析器会把它解读为相对列宽——这与 MANUAL.txt 中pipe_tables扩展的说明一致如果 Markdown 源中的任何一行比列宽--columns更宽表格将占据整个文本宽度单元格内容将换行相对单元格宽度由表头分隔线中的破折号数量决定。例如---|-会使第一列占全文宽度的 3/4第二列占 1/4。pandoc 读入这类表格后AST 中保存了相对列宽。问题在于输出时 pipe table 语法本身不支持表达相对列宽它的分隔线长度只表达内容宽度读者端并不会据此按比例分配列宽因此早期版本遇到带相对列宽的表格时会放弃 pipe table转而输出 HTMLtable以保留宽度信息。changelog.md记录了这一修复的两个侧面两个不同的 writer 分支都涉及 #3734CommonMark writerPrefer pipe tables to HTML tables even if it means losing relative column width information (#3734)changelog.mdMarkdown writerUse pipe tables ifraw_htmldisabled andpipe_tablesenabled, even if the table has relative width information (#3734)changelog.md修复后的策略是相对列宽信息可以舍弃优先保证输出可读、可移植的 pipe table。测试文件 test/command/3734.md 正是这个策略的回归验证。三、三个测试用例的逐步解读用例 1markdown_strictpipe_tables% pandoc -t markdown_strictpipe_tables | aaaaaaaaaaaa | bbbbb | ccccccccccc | |--------------|-------|--------------------------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | ^D | aaaaaaaaaaaa | bbbbb | ccccccccccc | |------------|-------|------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |关键点在于markdown_strict默认不包含pipe_tables扩展。在 src/Text/Pandoc/Extensions.hs 中可以看到strictExtensions只启用了三个扩展strictExtensions :: Extensions strictExtensions extensionsFromList [ Ext_raw_html , Ext_shortcut_reference_links , Ext_spaced_reference_links ]因此测试必须用pipe_tables显式打开该扩展。命令中的表示启用扩展、-表示禁用扩展这是 pandoc 对格式字符串统一的支持方式见 MANUAL.txt 附近关于扩展切换的说明。启用pipe_tables后writer 选择 pipe table 分支输出。注意输出中第三列的宽度比输入窄很多——因为分隔线的相对宽度信息已被舍弃输出列宽按内容重新计算。用例 2markdown_strictpipe_tables-raw_html% pandoc -t markdown_strictpipe_tables-raw_html ... ^D | aaaaaaaaaaaa | bbbbb | ccccccccccc | |------------|-------|------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |这个用例额外禁用了raw_html。它验证的是changelog.md中 Markdown writer 的修复Use pipe tables ifraw_htmldisabled andpipe_tablesenabled。也就是说即使 HTML 表格这个兜底方案不可用只要pipe_tables开着表格仍然能被正确输出为 pipe table而不会退化成[TABLE]占位符或报错。输出与用例 1 完全一致说明raw_html的启用在pipe table 优先的策略下不影响结果——pipe table 分支在 HTML 兜底分支之前被命中。用例 3gfm% pandoc -t gfm ... ^D | aaaaaaaaaaaa | bbbbb | ccccccccccc | |----|----|----| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |GFMGitHub Flavored Markdown的默认扩展集本身就包含pipe_tables和raw_html见 src/Text/Pandoc/Extensions.hs 中getDefaultExtensions gfm的列表所以无需任何扩展开关直接输出 pipe table。注意这里的输出比前两个用例更紧凑分隔线统一变成|----|----|----|。这是因为 gfm 目标对应 Commonmark 变体src/Text/Pandoc/Writers/Markdown/Table.hs 中pipeWidths的计算逻辑区分了Markdown变体与Commonmark变体——只有在Markdown变体且宽度信息非零、总宽度超限时才会按相对宽度分配分隔线长度Commonmark 变体则直接使用内容宽度或固定 2 个字符宽度。四、源码级原理解析writer 如何选择表格输出格式4.1 Markdown writer 的分支决策Markdown writer 渲染表格的核心逻辑在 src/Text/Pandoc/Writers/Markdown.hs。这段case True of按优先级依次尝试多种表格格式简单表格simple_tables扩展开启时用pandocTable否则若pipe_tables开启用pipeTable——注意此时不检查表格是否带相对列宽这正是 #3734 修复后的行为多行表格multiline_tables网格表格grid_tables处理跨行跨列或列数较多的场景再次尝试pipeTable简单单元格但带跨行跨列时给出近似输出raw_html开启时回退到 HTML5 表格最后才报BlockNotRendered并输出[TABLE]占位符。关键在分支 2/5 先于分支 6 的 HTML 回退所以只要pipe_tables开启即使表格带相对列宽也会选择 pipe table相对宽度信息被丢弃也在所不惜。4.2 pipeTable 的列宽计算pipeTable的实现位于 src/Text/Pandoc/Writers/Markdown/Table.hs。核心逻辑计算每列内容的最大显示宽度contentWidths每列至少 3 个字符宽若所有列内容宽度总和不超过writerColumns即--columns选项默认 72则按内容宽度输出pad maxwidth writerColumns opts分隔线border依据对齐方式生成AlignLeft为: 横线、AlignCenter为: 横线 :、AlignRight为横线 :、AlignDefault为纯横线表头不可省略无表头headless时输出一行空单元格作为表头见代码注释引用 jgm/pandoc#1996这与 MANUAL.txt 中pipe table 表头不能省略的说明对应。这就是为什么测试输出中长分隔线----...----被压缩成与内容匹配的宽度writer 输出时按内容重新计算列宽并不保留输入分隔线的相对宽度语义。4.3 reader 端如何产生相对列宽对应的读取解析逻辑在 src/Text/Pandoc/Readers/Markdown.hs 的pipeTable解析器中。它计算分隔线总长度与实际内容行宽度let lineWidths map (sum . map realLength) (heads : lines) columns - getOption readerColumns -- add numcols 1 for the pipes themselves let widths if maximumBounded (sum seplengths : lineWidths) (numcols 1) columns then map (\len - fromIntegral len / fromIntegral (sum seplengths)) seplengths else replicate (length aligns) 0.0即当输入行宽度超过--columns时按分隔线各段的长度比例计算相对列宽否则所有列宽为 0表示按内容自适应。这正是测试输入中那条超长分隔线被解析成相对宽度的机制也正是输出时被舍弃的信息。五、如何复现与扩展验证在 pandoc 源码目录构建后可直接运行命令测试套件。命令测试的驱动代码见 test/Tests/Command.hs它会扫描test/command/目录下所有.md文件把每个代码块解析为独立的 golden test文件编号作为测试名runCommandTest中testname # show num。单独验证本文三个用例只需手动执行# 用例 1 pandoc -t markdown_strictpipe_tables EOF | aaaaaaaaaaaa | bbbbb | ccccccccccc | |--------------|-------|--------------------------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | EOF # 用例 2 pandoc -t markdown_strictpipe_tables-raw_html EOF | aaaaaaaaaaaa | bbbbb | ccccccccccc | |--------------|-------|--------------------------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | EOF # 用例 3 pandoc -t gfm EOF | aaaaaaaaaaaa | bbbbb | ccccccccccc | |--------------|-------|--------------------------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | EOF感兴趣的话还可以做两个反向验证去掉pipe_tablespandoc -t markdown_strict由于 strict 扩展集不含pipe_tables会走 HTML 回退分支输出table若再叠加-raw_html则两个分支都不可用最终输出[TABLE]占位符并产生BlockNotRendered警告对应 src/Text/Pandoc/Writers/Markdown.hs 的兜底分支。对比--columns的影响用--columns200重放测试输入reader 会发现所有行都未超过列宽从而把相对列宽置为 0输出行为随之改变——这体现了--columns在 reader/writer 两侧的双重作用。六、小结通过 test/command/3734.md 这一组回归测试可以完整梳理 pandoc 表格输出的一条关键策略格式选择优先级pipe_tables优先于 HTML 兜底即使意味着丢失相对列宽信息issue #3734 的修复结论扩展开关语法-t markdown_strictpipe_tables-raw_html形式的/-扩展切换是控制表格输出格式的实用手段列宽语义reader 在行超宽时按分隔线比例计算相对列宽writer 在输出 pipe table 时按内容重新计算宽度变体差异markdown与gfmCommonmark 变体在分隔线宽度的输出策略上存在差异。对日常使用而言这条规则意味着当你把带复杂列宽设计的表格从 HTML 或 LaTeX 转换到 Markdown 时若目标格式支持pipe_tables得到的是干净紧凑的 pipe table列宽比例会被简化——这是 pandoc 有意为之的行为而非 bug。若必须保留精确列宽则需要选择支持宽度表达的格式如 HTML 或 LaTeX作为输出目标。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pandoc pipe_tables 扩展解析：从 3734 命令测试看表格输出策略与相对列宽取舍
pandoc pipe_tables 扩展解析从 #3734 命令测试看表格输出策略与相对列宽取舍【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc本篇文章以 pandoc 仓库中的命令测试 test/command/3734.md 为切入点深入解读 pandoc 在将文档转换为 Markdown 时如何决策使用 pipe table 还是 HTML 表格以及表格带相对列宽信息时的取舍逻辑。读者将掌握pipe_tables、raw_html扩展的组合规则、pipe table 的列宽计算原理并能看懂与复现 pandoc 官方的表格回归测试。一、测试文件 3734.md 在做什么test/command/3734.md是 pandoc 的命令测试command test文件。这类文件的格式定义在 test/Tests/Command.hs 的模块注释中以%开头的行是要执行的命令行后续若干行是通过 stdin 传入的输入以单独一行^D结束再往后的行是期望的 stdout 输出。该文件包含三个独立的测试用例输入完全相同——一个带有超长分隔线的 pipe table| aaaaaaaaaaaa | bbbbb | ccccccccccc | |--------------|-------|--------------------------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |三个用例分别是用例命令输出1pandoc -t markdown_strictpipe_tablespipe table列宽压缩2pandoc -t markdown_strictpipe_tables-raw_htmlpipe table列宽压缩3pandoc -t gfmpipe table更紧凑这三个用例共同验证了同一行为即使输入表格的分隔线长度暗示了相对列宽信息只要目标格式启用了pipe_tablespandoc 就优先输出 pipe table而不是退化为 HTML 表格。这一行为正是 issue #3734 修复的内容。二、问题背景相对列宽信息 vs 表格格式选择在 pandoc 的内部文档模型AST中表格的每一列都带有相对宽度width值为 0~1 之间的浮点数。当 Markdown 输入中分隔线的某个部分特别长时解析器会把它解读为相对列宽——这与 MANUAL.txt 中pipe_tables扩展的说明一致如果 Markdown 源中的任何一行比列宽--columns更宽表格将占据整个文本宽度单元格内容将换行相对单元格宽度由表头分隔线中的破折号数量决定。例如---|-会使第一列占全文宽度的 3/4第二列占 1/4。pandoc 读入这类表格后AST 中保存了相对列宽。问题在于输出时 pipe table 语法本身不支持表达相对列宽它的分隔线长度只表达内容宽度读者端并不会据此按比例分配列宽因此早期版本遇到带相对列宽的表格时会放弃 pipe table转而输出 HTMLtable以保留宽度信息。changelog.md记录了这一修复的两个侧面两个不同的 writer 分支都涉及 #3734CommonMark writerPrefer pipe tables to HTML tables even if it means losing relative column width information (#3734)changelog.mdMarkdown writerUse pipe tables ifraw_htmldisabled andpipe_tablesenabled, even if the table has relative width information (#3734)changelog.md修复后的策略是相对列宽信息可以舍弃优先保证输出可读、可移植的 pipe table。测试文件 test/command/3734.md 正是这个策略的回归验证。三、三个测试用例的逐步解读用例 1markdown_strictpipe_tables% pandoc -t markdown_strictpipe_tables | aaaaaaaaaaaa | bbbbb | ccccccccccc | |--------------|-------|--------------------------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | ^D | aaaaaaaaaaaa | bbbbb | ccccccccccc | |------------|-------|------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |关键点在于markdown_strict默认不包含pipe_tables扩展。在 src/Text/Pandoc/Extensions.hs 中可以看到strictExtensions只启用了三个扩展strictExtensions :: Extensions strictExtensions extensionsFromList [ Ext_raw_html , Ext_shortcut_reference_links , Ext_spaced_reference_links ]因此测试必须用pipe_tables显式打开该扩展。命令中的表示启用扩展、-表示禁用扩展这是 pandoc 对格式字符串统一的支持方式见 MANUAL.txt 附近关于扩展切换的说明。启用pipe_tables后writer 选择 pipe table 分支输出。注意输出中第三列的宽度比输入窄很多——因为分隔线的相对宽度信息已被舍弃输出列宽按内容重新计算。用例 2markdown_strictpipe_tables-raw_html% pandoc -t markdown_strictpipe_tables-raw_html ... ^D | aaaaaaaaaaaa | bbbbb | ccccccccccc | |------------|-------|------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |这个用例额外禁用了raw_html。它验证的是changelog.md中 Markdown writer 的修复Use pipe tables ifraw_htmldisabled andpipe_tablesenabled。也就是说即使 HTML 表格这个兜底方案不可用只要pipe_tables开着表格仍然能被正确输出为 pipe table而不会退化成[TABLE]占位符或报错。输出与用例 1 完全一致说明raw_html的启用在pipe table 优先的策略下不影响结果——pipe table 分支在 HTML 兜底分支之前被命中。用例 3gfm% pandoc -t gfm ... ^D | aaaaaaaaaaaa | bbbbb | ccccccccccc | |----|----|----| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc |GFMGitHub Flavored Markdown的默认扩展集本身就包含pipe_tables和raw_html见 src/Text/Pandoc/Extensions.hs 中getDefaultExtensions gfm的列表所以无需任何扩展开关直接输出 pipe table。注意这里的输出比前两个用例更紧凑分隔线统一变成|----|----|----|。这是因为 gfm 目标对应 Commonmark 变体src/Text/Pandoc/Writers/Markdown/Table.hs 中pipeWidths的计算逻辑区分了Markdown变体与Commonmark变体——只有在Markdown变体且宽度信息非零、总宽度超限时才会按相对宽度分配分隔线长度Commonmark 变体则直接使用内容宽度或固定 2 个字符宽度。四、源码级原理解析writer 如何选择表格输出格式4.1 Markdown writer 的分支决策Markdown writer 渲染表格的核心逻辑在 src/Text/Pandoc/Writers/Markdown.hs。这段case True of按优先级依次尝试多种表格格式简单表格simple_tables扩展开启时用pandocTable否则若pipe_tables开启用pipeTable——注意此时不检查表格是否带相对列宽这正是 #3734 修复后的行为多行表格multiline_tables网格表格grid_tables处理跨行跨列或列数较多的场景再次尝试pipeTable简单单元格但带跨行跨列时给出近似输出raw_html开启时回退到 HTML5 表格最后才报BlockNotRendered并输出[TABLE]占位符。关键在分支 2/5 先于分支 6 的 HTML 回退所以只要pipe_tables开启即使表格带相对列宽也会选择 pipe table相对宽度信息被丢弃也在所不惜。4.2 pipeTable 的列宽计算pipeTable的实现位于 src/Text/Pandoc/Writers/Markdown/Table.hs。核心逻辑计算每列内容的最大显示宽度contentWidths每列至少 3 个字符宽若所有列内容宽度总和不超过writerColumns即--columns选项默认 72则按内容宽度输出pad maxwidth writerColumns opts分隔线border依据对齐方式生成AlignLeft为: 横线、AlignCenter为: 横线 :、AlignRight为横线 :、AlignDefault为纯横线表头不可省略无表头headless时输出一行空单元格作为表头见代码注释引用 jgm/pandoc#1996这与 MANUAL.txt 中pipe table 表头不能省略的说明对应。这就是为什么测试输出中长分隔线----...----被压缩成与内容匹配的宽度writer 输出时按内容重新计算列宽并不保留输入分隔线的相对宽度语义。4.3 reader 端如何产生相对列宽对应的读取解析逻辑在 src/Text/Pandoc/Readers/Markdown.hs 的pipeTable解析器中。它计算分隔线总长度与实际内容行宽度let lineWidths map (sum . map realLength) (heads : lines) columns - getOption readerColumns -- add numcols 1 for the pipes themselves let widths if maximumBounded (sum seplengths : lineWidths) (numcols 1) columns then map (\len - fromIntegral len / fromIntegral (sum seplengths)) seplengths else replicate (length aligns) 0.0即当输入行宽度超过--columns时按分隔线各段的长度比例计算相对列宽否则所有列宽为 0表示按内容自适应。这正是测试输入中那条超长分隔线被解析成相对宽度的机制也正是输出时被舍弃的信息。五、如何复现与扩展验证在 pandoc 源码目录构建后可直接运行命令测试套件。命令测试的驱动代码见 test/Tests/Command.hs它会扫描test/command/目录下所有.md文件把每个代码块解析为独立的 golden test文件编号作为测试名runCommandTest中testname # show num。单独验证本文三个用例只需手动执行# 用例 1 pandoc -t markdown_strictpipe_tables EOF | aaaaaaaaaaaa | bbbbb | ccccccccccc | |--------------|-------|--------------------------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | EOF # 用例 2 pandoc -t markdown_strictpipe_tables-raw_html EOF | aaaaaaaaaaaa | bbbbb | ccccccccccc | |--------------|-------|--------------------------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | EOF # 用例 3 pandoc -t gfm EOF | aaaaaaaaaaaa | bbbbb | ccccccccccc | |--------------|-------|--------------------------------------------------------------------------| | aaaaaaaaaaaa | | cccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc | EOF感兴趣的话还可以做两个反向验证去掉pipe_tablespandoc -t markdown_strict由于 strict 扩展集不含pipe_tables会走 HTML 回退分支输出table若再叠加-raw_html则两个分支都不可用最终输出[TABLE]占位符并产生BlockNotRendered警告对应 src/Text/Pandoc/Writers/Markdown.hs 的兜底分支。对比--columns的影响用--columns200重放测试输入reader 会发现所有行都未超过列宽从而把相对列宽置为 0输出行为随之改变——这体现了--columns在 reader/writer 两侧的双重作用。六、小结通过 test/command/3734.md 这一组回归测试可以完整梳理 pandoc 表格输出的一条关键策略格式选择优先级pipe_tables优先于 HTML 兜底即使意味着丢失相对列宽信息issue #3734 的修复结论扩展开关语法-t markdown_strictpipe_tables-raw_html形式的/-扩展切换是控制表格输出格式的实用手段列宽语义reader 在行超宽时按分隔线比例计算相对列宽writer 在输出 pipe table 时按内容重新计算宽度变体差异markdown与gfmCommonmark 变体在分隔线宽度的输出策略上存在差异。对日常使用而言这条规则意味着当你把带复杂列宽设计的表格从 HTML 或 LaTeX 转换到 Markdown 时若目标格式支持pipe_tables得到的是干净紧凑的 pipe table列宽比例会被简化——这是 pandoc 有意为之的行为而非 bug。若必须保留精确列宽则需要选择支持宽度表达的格式如 HTML 或 LaTeX作为输出目标。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考