Pandoc 表格脚注的 LaTeX 输出从回归测试 5367 解读脚注编号与排序的修复实现【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本篇文章以 pandoc 官方回归测试用例 test/command/5367.md 为核心深入剖析 pandoc 将 Markdown 中带有脚注footnote的表格转换为 LaTeX 时如何处理表格标题caption、表头header与单元格cell中的脚注。读者将掌握 pandoc 的 golden test 格式、脚注在longtable环境中的输出形态以及 LaTeX writer 中外部脚注收集 延迟输出这一核心机制的工作原理并了解该机制在 Beamer 等特殊格式下的分支处理逻辑。一、回归测试 5367 的由来与价值test/command/5367.md 是 pandoc 测试套件中的一个典型 golden test 文件其编号对应 GitHub issue #5367。在 changelog.md 的 pandoc 2.8 版本记录中可以找到这次修复的官方说明Fix footnotes in table caption and cells (#5367). This fixes a bug wherein footnotes appeared in the wrong order, and with duplicate numbers, when in table captions and cells. We now use regular\footnotecommands, even in the table caption and the minipages containing cells. Apparently longtable knows how to handle this.也就是说该修复之前位于表格标题、表头与单元格中的脚注会出现顺序错乱和编号重复两个典型缺陷修复之后pandoc 直接在这些位置生成普通的\footnote命令交由 LaTeX 的longtable环境自行处理脚注编号。而 test/command/5367.md 正是这一修复的回归测试防止未来改动重新引入该缺陷。二、读懂 golden test 文件格式pandoc 的命令行回归测试位于 test/command/ 目录采用统一的输入输出约定test/command/5367.md 完整展示了这一格式% pandoc -t latex hello[^1] : Sample table.[^2] ----------- Fruit[^3] ----------- Bans[^4] ----------- dolly[^5] [^1]: doc footnote [^2]: caption footnote [^3]: header footnote [^4]: table cell footnote [^5]: doc footnote ^D hello\footnote{doc footnote} ... dolly\footnote{doc footnote}其结构分为三段第一行% pandoc -t latex指定要执行的命令行等价于运行pandoc -t latex输入为 Markdown输出目标格式为 LaTeX中间输入区以^DEOF 标记结尾的 Markdown 文档本体末尾输出区pandoc 转换后应产生的精确期望输出。测试框架实现于 test/Tests/Command.hs会执行第一行命令并将实际输出与文件末尾的期望输出逐字节比对任何差异都会导致测试失败。因此该文件不仅是一份可运行的转换示例更是一份输入 Markdown → 期望 LaTeX的权威映射。三、测试输入中的脚注分布场景测试输入在一份很短的文档里刻意覆盖了表格中可能出现的全部脚注位置共 5 处脚注标记出现位置脚注文本对应输出位置[^1]正文段落hellodoc footnote文档体脚注[^2]表格标题captioncaption footnote\caption内[^3]表头单元格Fruitheader footnote表头minipage内[^4]表格数据单元格Banstable cell footnote表格行内[^5]正文段落dollydoc footnote文档体脚注其中[^3]与[^4]的位置是关键脚注位于longtable环境的minipage内部而minipage中的\footnote默认会变成带编号的脚注标记但不进入页面底部这正是旧实现容易出错的原因。测试特意在正文hello、dolly也放置脚注用于验证表格内外脚注的整体排序与编号连续性。四、期望输出逐段解析4.1 表格标题中的脚注\caption[Sample table.]{Sample table.\footnote{caption footnote}}\tabularnewline标题被生成为带短标题[Sample table.]的\caption脚注文本caption footnote以普通\footnote命令内联在标题文字内部。这与修复前脚注被移到表格外部、编号错乱的行为形成鲜明对比。4.2 表头中的脚注\begin{minipage}[b]{\linewidth}\centering Fruit\footnote{header footnote} \end{minipage} \\表头单元格被渲染为minipage脚注直接以\footnote{header footnote}形式嵌在单元格文字中。值得注意的细节是longtable会对跨页表格重复输出表头\endfirsthead/\endhead机制在重复的表头部分第二次及之后出现的表头中脚注被替换为Fruit{}——即重复表头中不再重复输出脚注命令避免同一脚注在每一页重复出现\endfirsthead \toprule\noalign{} \begin{minipage}[b]{\linewidth}\centering Fruit{} \end{minipage} \\ \midrule\noalign{} \endhead4.3 单元格与正文中的脚注数据单元格脚注同样以内联形式输出Bans\footnote{table cell footnote} \\而正文段落中的两个脚注则输出为文档体的普通脚注hello\footnote{doc footnote} ... dolly\footnote{doc footnote}最终5 个脚注在 LaTeX 源中保持与输入完全一致的先后顺序编号将由 LaTeX 编译器按出现顺序统一分配彻底消除了旧实现中表格内脚注被提前收集、导致编号重复或错序的问题。五、源码级实现剖析外部脚注机制回归测试背后是 LaTeX writer 一套精心设计的外部脚注收集机制。其核心入口位于 src/Text/Pandoc/Writers/LaTeX/Table.hs-- See #5367 -- footnotehyper/footnote dont work in beamer, -- so we need to produce the notes outside the table... if float || beamer then ($$) $ withExternalNotes renderTable * getAccumulatedNotes else renderTable这段代码的含义是当表格带有float类浮动表格环境或目标格式为 Beamer 时整个表格的渲染过程被包裹在withExternalNotes中渲染完毕后通过getAccumulatedNotes把收集到的脚注追加在表格环境之后输出。5.1 脚注如何被收集而非直接输出withExternalNotes定义于 src/Text/Pandoc/Writers/LaTeX/Util.hs的作用是在渲染期间把 writer 状态中的stExternalNotes标志置为True使脚注处理分支发生切换。在 src/Text/Pandoc/Writers/LaTeX.hs 中可以看到这个分支externalNotes - gets stExternalNotes if externalNotes then do modify $ \st - st{ stNotes noteContents : stNotes st } return \\footnotemark{} else return $ \\footnote beamerMark braces noteContents也就是说在外部脚注模式下脚注不立即输出而是在脚注位置仅输出一个占位标记\footnotemark{}把脚注正文压入状态栈stNotes待表格渲染完毕后由getAccumulatedNotessrc/Text/Pandoc/Writers/LaTeX/Util.hs统一取出、清空并在表格之后输出。而普通的表格路径非 float、非 Beamer则直接走常规\footnote内联输出。这与 changelog 中we now use regular\footnotecommands... longtable knows how to handle this的描述完全吻合——longtable对表格内的\footnote有原生支持因此对最常见的普通长表格场景无需特殊处理。5.2 重复表头中的脚注去重前面提到重复表头中脚注被替换为Fruit{}其实现位于 src/Text/Pandoc/Writers/LaTeX/Table.hs 的tableToLaTeXLongtablefirsthead - mkHead thead let removeNote (Note _) Span (, [], []) [] removeNote x x repeated - mkHead (walk removeNote thead) return $ capt \\tabularnewline $$ firsthead $$ \\endfirsthead $$ repeated代码用walk removeNote对重复表头做了一次 AST 变换把所有Note内联元素替换为空Span从而保证脚注命令只出现在首次表头\endfirsthead之前跨页重复的表头中不再重复产生脚注。这正是测试期望输出中Fruit{}的来源也是防止同一脚注在每页重复出现的关键细节。5.3 非表格场景的常规脚注在文档体的普通块序列中blockListToLaTeXsrc/Text/Pandoc/Writers/LaTeX.hs会在每个块输出后把当前累积的脚注一并追加输出在外部脚注模式下则跳过追加交由表格渲染完成后的getAccumulatedNotes统一处理。这套状态栈累积 延迟冲洗的设计保证了脚注无论出现在正文、列表、标题还是表格内最终都以正确的先后顺序输出。六、测试的运行与验证方式读者可自行复现该测试。在完成 pandoc 构建后通过make test或在仓库根目录执行测试套件即可运行全部 command 测试若只想针对本用例验证可将文件中的输入区% pandoc -t latex之后的 Markdown至^D前保存为临时文件并执行pandoc -t latex input.md将输出与 test/command/5367.md 末尾的期望输出对比。若二者一致说明当前版本的 LaTeX writer 对表格内脚注的处理符合预期。同时将同一输入改用-t beamer输出可以观察到表格渲染走withExternalNotes分支后脚注被收集到表格外部输出、并以.-[frame]等 Beamer 覆盖语法标记见 src/Text/Pandoc/Writers/LaTeX.hs呈现的差异。七、小结test/command/5367.md 看似只是一个几十行的转换示例实则浓缩了 pandoc 关于表格脚注这一边角场景的完整工程决策行为约定表格标题、表头、单元格内的脚注以普通\footnote内联输出交由longtable处理缺陷防护重复表头通过 AST 变换剔除脚注避免跨页重复特殊分支浮动表格与 Beamer 下切换到脚注收集 延迟输出机制规避\footnote在这些环境中的失效问题。对于希望深入 pandoc LaTeX 输出的读者建议按 test/command/ 目录的编号顺序 golden test并结合 src/Text/Pandoc/Writers/LaTeX.hs 与 src/Text/Pandoc/Writers/LaTeX/Table.hs 对照研读可以快速建立起测试即规范的源码阅读路径。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pandoc 表格脚注的 LaTeX 输出：从回归测试 5367 解读脚注编号与排序的修复实现
Pandoc 表格脚注的 LaTeX 输出从回归测试 5367 解读脚注编号与排序的修复实现【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本篇文章以 pandoc 官方回归测试用例 test/command/5367.md 为核心深入剖析 pandoc 将 Markdown 中带有脚注footnote的表格转换为 LaTeX 时如何处理表格标题caption、表头header与单元格cell中的脚注。读者将掌握 pandoc 的 golden test 格式、脚注在longtable环境中的输出形态以及 LaTeX writer 中外部脚注收集 延迟输出这一核心机制的工作原理并了解该机制在 Beamer 等特殊格式下的分支处理逻辑。一、回归测试 5367 的由来与价值test/command/5367.md 是 pandoc 测试套件中的一个典型 golden test 文件其编号对应 GitHub issue #5367。在 changelog.md 的 pandoc 2.8 版本记录中可以找到这次修复的官方说明Fix footnotes in table caption and cells (#5367). This fixes a bug wherein footnotes appeared in the wrong order, and with duplicate numbers, when in table captions and cells. We now use regular\footnotecommands, even in the table caption and the minipages containing cells. Apparently longtable knows how to handle this.也就是说该修复之前位于表格标题、表头与单元格中的脚注会出现顺序错乱和编号重复两个典型缺陷修复之后pandoc 直接在这些位置生成普通的\footnote命令交由 LaTeX 的longtable环境自行处理脚注编号。而 test/command/5367.md 正是这一修复的回归测试防止未来改动重新引入该缺陷。二、读懂 golden test 文件格式pandoc 的命令行回归测试位于 test/command/ 目录采用统一的输入输出约定test/command/5367.md 完整展示了这一格式% pandoc -t latex hello[^1] : Sample table.[^2] ----------- Fruit[^3] ----------- Bans[^4] ----------- dolly[^5] [^1]: doc footnote [^2]: caption footnote [^3]: header footnote [^4]: table cell footnote [^5]: doc footnote ^D hello\footnote{doc footnote} ... dolly\footnote{doc footnote}其结构分为三段第一行% pandoc -t latex指定要执行的命令行等价于运行pandoc -t latex输入为 Markdown输出目标格式为 LaTeX中间输入区以^DEOF 标记结尾的 Markdown 文档本体末尾输出区pandoc 转换后应产生的精确期望输出。测试框架实现于 test/Tests/Command.hs会执行第一行命令并将实际输出与文件末尾的期望输出逐字节比对任何差异都会导致测试失败。因此该文件不仅是一份可运行的转换示例更是一份输入 Markdown → 期望 LaTeX的权威映射。三、测试输入中的脚注分布场景测试输入在一份很短的文档里刻意覆盖了表格中可能出现的全部脚注位置共 5 处脚注标记出现位置脚注文本对应输出位置[^1]正文段落hellodoc footnote文档体脚注[^2]表格标题captioncaption footnote\caption内[^3]表头单元格Fruitheader footnote表头minipage内[^4]表格数据单元格Banstable cell footnote表格行内[^5]正文段落dollydoc footnote文档体脚注其中[^3]与[^4]的位置是关键脚注位于longtable环境的minipage内部而minipage中的\footnote默认会变成带编号的脚注标记但不进入页面底部这正是旧实现容易出错的原因。测试特意在正文hello、dolly也放置脚注用于验证表格内外脚注的整体排序与编号连续性。四、期望输出逐段解析4.1 表格标题中的脚注\caption[Sample table.]{Sample table.\footnote{caption footnote}}\tabularnewline标题被生成为带短标题[Sample table.]的\caption脚注文本caption footnote以普通\footnote命令内联在标题文字内部。这与修复前脚注被移到表格外部、编号错乱的行为形成鲜明对比。4.2 表头中的脚注\begin{minipage}[b]{\linewidth}\centering Fruit\footnote{header footnote} \end{minipage} \\表头单元格被渲染为minipage脚注直接以\footnote{header footnote}形式嵌在单元格文字中。值得注意的细节是longtable会对跨页表格重复输出表头\endfirsthead/\endhead机制在重复的表头部分第二次及之后出现的表头中脚注被替换为Fruit{}——即重复表头中不再重复输出脚注命令避免同一脚注在每一页重复出现\endfirsthead \toprule\noalign{} \begin{minipage}[b]{\linewidth}\centering Fruit{} \end{minipage} \\ \midrule\noalign{} \endhead4.3 单元格与正文中的脚注数据单元格脚注同样以内联形式输出Bans\footnote{table cell footnote} \\而正文段落中的两个脚注则输出为文档体的普通脚注hello\footnote{doc footnote} ... dolly\footnote{doc footnote}最终5 个脚注在 LaTeX 源中保持与输入完全一致的先后顺序编号将由 LaTeX 编译器按出现顺序统一分配彻底消除了旧实现中表格内脚注被提前收集、导致编号重复或错序的问题。五、源码级实现剖析外部脚注机制回归测试背后是 LaTeX writer 一套精心设计的外部脚注收集机制。其核心入口位于 src/Text/Pandoc/Writers/LaTeX/Table.hs-- See #5367 -- footnotehyper/footnote dont work in beamer, -- so we need to produce the notes outside the table... if float || beamer then ($$) $ withExternalNotes renderTable * getAccumulatedNotes else renderTable这段代码的含义是当表格带有float类浮动表格环境或目标格式为 Beamer 时整个表格的渲染过程被包裹在withExternalNotes中渲染完毕后通过getAccumulatedNotes把收集到的脚注追加在表格环境之后输出。5.1 脚注如何被收集而非直接输出withExternalNotes定义于 src/Text/Pandoc/Writers/LaTeX/Util.hs的作用是在渲染期间把 writer 状态中的stExternalNotes标志置为True使脚注处理分支发生切换。在 src/Text/Pandoc/Writers/LaTeX.hs 中可以看到这个分支externalNotes - gets stExternalNotes if externalNotes then do modify $ \st - st{ stNotes noteContents : stNotes st } return \\footnotemark{} else return $ \\footnote beamerMark braces noteContents也就是说在外部脚注模式下脚注不立即输出而是在脚注位置仅输出一个占位标记\footnotemark{}把脚注正文压入状态栈stNotes待表格渲染完毕后由getAccumulatedNotessrc/Text/Pandoc/Writers/LaTeX/Util.hs统一取出、清空并在表格之后输出。而普通的表格路径非 float、非 Beamer则直接走常规\footnote内联输出。这与 changelog 中we now use regular\footnotecommands... longtable knows how to handle this的描述完全吻合——longtable对表格内的\footnote有原生支持因此对最常见的普通长表格场景无需特殊处理。5.2 重复表头中的脚注去重前面提到重复表头中脚注被替换为Fruit{}其实现位于 src/Text/Pandoc/Writers/LaTeX/Table.hs 的tableToLaTeXLongtablefirsthead - mkHead thead let removeNote (Note _) Span (, [], []) [] removeNote x x repeated - mkHead (walk removeNote thead) return $ capt \\tabularnewline $$ firsthead $$ \\endfirsthead $$ repeated代码用walk removeNote对重复表头做了一次 AST 变换把所有Note内联元素替换为空Span从而保证脚注命令只出现在首次表头\endfirsthead之前跨页重复的表头中不再重复产生脚注。这正是测试期望输出中Fruit{}的来源也是防止同一脚注在每页重复出现的关键细节。5.3 非表格场景的常规脚注在文档体的普通块序列中blockListToLaTeXsrc/Text/Pandoc/Writers/LaTeX.hs会在每个块输出后把当前累积的脚注一并追加输出在外部脚注模式下则跳过追加交由表格渲染完成后的getAccumulatedNotes统一处理。这套状态栈累积 延迟冲洗的设计保证了脚注无论出现在正文、列表、标题还是表格内最终都以正确的先后顺序输出。六、测试的运行与验证方式读者可自行复现该测试。在完成 pandoc 构建后通过make test或在仓库根目录执行测试套件即可运行全部 command 测试若只想针对本用例验证可将文件中的输入区% pandoc -t latex之后的 Markdown至^D前保存为临时文件并执行pandoc -t latex input.md将输出与 test/command/5367.md 末尾的期望输出对比。若二者一致说明当前版本的 LaTeX writer 对表格内脚注的处理符合预期。同时将同一输入改用-t beamer输出可以观察到表格渲染走withExternalNotes分支后脚注被收集到表格外部输出、并以.-[frame]等 Beamer 覆盖语法标记见 src/Text/Pandoc/Writers/LaTeX.hs呈现的差异。七、小结test/command/5367.md 看似只是一个几十行的转换示例实则浓缩了 pandoc 关于表格脚注这一边角场景的完整工程决策行为约定表格标题、表头、单元格内的脚注以普通\footnote内联输出交由longtable处理缺陷防护重复表头通过 AST 变换剔除脚注避免跨页重复特殊分支浮动表格与 Beamer 下切换到脚注收集 延迟输出机制规避\footnote在这些环境中的失效问题。对于希望深入 pandoc LaTeX 输出的读者建议按 test/command/ 目录的编号顺序 golden test并结合 src/Text/Pandoc/Writers/LaTeX.hs 与 src/Text/Pandoc/Writers/LaTeX/Table.hs 对照研读可以快速建立起测试即规范的源码阅读路径。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考