Pandoc LaTeX 表格输出控制：unnumbered 编号抑制与 float 浮动环境的源码级解析

Pandoc LaTeX 表格输出控制：unnumbered 编号抑制与 float 浮动环境的源码级解析

【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc

本文围绕 pandoc 官方命令测试用例 test/command/11795.md 展开，剖析 pandoc 在将带标题（caption）与属性（attributes）的 Markdown 表格转换为 LaTeX 时，如何通过unnumbered与float两个类名精确控制表格的编号行为与浮动行为。读完本文，你将掌握表格 caption 属性语法、longtable与table两种环境的切换规则、\LTcaptype{none}计数器抑制机制的底层实现，并能直接复现与验证这两条测试用例。

一、测试用例背景：pandoc 如何用黄金文件锁定输出行为

pandoc 的测试体系将每个命令测试用例保存在 test/command/ 目录下，文件名即对应 GitHub issue 编号。11795.md正是 issue #11795 的回归测试，其形式为：文档中每个代码块包含一段完整 shell 会话（% pandoc -t latex起始的命令行、^D结束的输入文档、以及紧随其后的预期输出），pandoc 运行这些命令并逐字节比对输出，任何与预期不符的差异都会导致测试失败。

该用例聚焦一个非常具体的功能点：当表格 caption 带有类名属性时，pandoc 如何决定最终输出longtable环境还是浮动table环境，以及如何抑制 LaTeX 对表格的自动编号。两个测试块分别验证了unnumbered与float两条代码路径。

二、用例一：{#foo .unnumbered}与 longtable 编号抑制

第一个测试块输入如下（摘自 test/command/11795.md）：

% pandoc -t latex || |--|-- |a|b : {#foo .unnumbered} ^D

Markdown 源文档由三部分组成：一个两列两行的 pipe table、一个以:开头的表格 caption、以及紧随其后的{#foo .unnumbered}属性行。pandoc 的预期输出为：

{\def\LTcaptype{none} % do not increment counter \begin{longtable}[]{@{}ll@{}} \toprule\noalign{} \endhead \bottomrule\noalign{} \endlastfoot a & b \\ \end{longtable} }

这段输出揭示了三个关键事实：

1. caption 属性语法的解析：{#foo .unnumbered}中，#foo是表格的标识符（id），.unnumbered是类名（class）。Markdown 读取器将二者附加到表格自身的属性（Attr）上，而非 caption 文本上——因此输出中没有任何\caption命令，表格没有标题文本。
2. 默认环境是 longtable：由于表格未声明float类，pandoc 选择输出longtable环境（\begin{longtable}），这是 pandoc 默认的非浮动表格路径。
3. 编号抑制机制：整个longtable被{\def\LTcaptype{none} % do not increment counter ... }包裹。这是 LaTeX 层面的编号抑制技巧：\LTcaptype是longtable宏包用于生成\caption计数器类型的内部命令，将其重定义为none后，longtable内部的 caption 便不再触发table计数器递增，从而实现"不编号"。

换一个角度理解：即使表格没有unnumbered类，只要 caption 为空（无文本、无 id），pandoc 同样会走makeUnnumbered包装路径，避免产生编号副作用。

三、用例二：{.float}与浮动 table 环境

第二个测试块将属性行改为{.float}：

% pandoc -t latex || |--|-- |a|b : {.float} ^D

预期输出完全不同：

{\def\LTcaptype{none} % do not increment counter \begin{table}[] \centering \begin{tabular}{@{}ll@{}} \toprule\noalign{} a & b \\ \bottomrule\noalign{} \end{tabular} \end{table} }

对比用例一，差异一目了然：

• 表格从跨页的longtable切换为浮动体\begin{table}[] ... \end{table}，内部使用tabular排版单元格；
• 由于表格内容简单（单元格均为纯文本、未指定列宽），pandoc 判定其为 simple table，输出简化的@{}ll@{}列描述符；
• 空 caption 仍然触发了{\def\LTcaptype{none} ...}包裹——这说明LTcaptype抑制逻辑同时作用于两种环境路径，是编号控制的统一前置步骤。

注意这里table环境的可选参数为空（[]）：只有当属性中显式给出latex-placement键值对时，才会填充该位置参数（如\begin{table}[ht]）。

四、源码级原理：float类如何决定环境选择

两个用例的输出差异，根源在 LaTeX 写入器的表格模块 src/Text/Pandoc/Writers/LaTeX/Table.hs 的tableToLaTeX函数。其核心逻辑如下（对应源文件 L54-L85）：

-- if the float class is included in table attributes, we generate a floating -- table environment; otherwise we use longtable let float = "float" `elem` classes ... let unnumbered = "unnumbered" `elem` classes ... let makeUnnumbered x = "{\\def\\LTcaptype{none} % do not increment counter" $$ x $$ "}" let makeTable = if float then tableToLaTeXTable placement else tableToLaTeXLongtable (if unnumbered || isEmpty capt then makeUnnumbered else id) <$> makeTable colDesc mkHead mkRow capt thead tbodies tfoot

逐行解读这段实现：

• 环境路由："float" \elem` classes检查表格属性类列表中是否含float。含则调用tableToLaTeXTable（生成table+tabular浮动体，见同文件 L92-L132），不含则调用tableToLaTeXLongtable（生成longtable`，见 L135-L200）。这就是用例一与用例二输出环境不同的直接原因。
• 编号抑制的条件：unnumbered || isEmpty capt——只要表格声明了unnumbered类，或者caption 为空，就整体包上\def\LTcaptype{none}。makeUnnumbered中那行注释% do not increment counter与源码注释（L78）完全一致，正是测试预期输出中注释的来源。
• placement 传递：placement = brackets $ maybe mempty ... $ lookup "latex-placement" kvs（L52-L53），从表格的键值对属性中读取latex-placement，用于生成\begin{table}[...]的位置参数。

五、属性语法解析：{#id .class key="val"}的读取器实现

测试用例中的{#foo .unnumbered}与{.float}由 Markdown 读取器的 caption 属性解析逻辑处理。在 src/Text/Pandoc/Readers/Markdown.hs 中，tableCaption（L1327 起）负责识别以:开头的 caption 行及其后的属性；属性各组成部分由三个组合子解析：

• identifierAttr（L661-L665）：#后跟字母数字及-_:.字符，成为表格 id；
• classAttr（L667-L671）：.后跟标识符，追加进类名列表；
• keyValAttr（L673-L686）：key="value"形式，支持双引号、单引号包裹；特殊键id与class会被分别并入 id 与类列表，其余键（如latex-placement）进入键值对表。

因此{#foo .unnumbered}解析结果为id = "foo"、classes = ["unnumbered"]；{.float}解析结果为classes = ["float"]。除此之外，specialAttr（L688-L691）支持-前缀快捷写法，等价于追加unnumbered类，例如 caption 属性写{-}与写{.unnumbered}效果相同。

六、同类用例佐证：1023.md中的完整浮动表格输出

测试用例 test/command/1023.md 提供了与11795.md互补的完整示例，展示带标题文本、id 与放置参数的浮动表格输出：

: Here's the caption. It may span multiple lines. {.float #ident latex-placement="ht"}

其预期输出为：

\begin{table}[ht] \centering \caption{Here's the caption. It may span multiple lines.}\label{ident}\tabularnewline ... \end{table}

这里可以看到与11795.md的差别：当 caption 非空且存在 id 时，pandoc 会生成\caption{...}\label{...}；当给出latex-placement="ht"时，table环境的可选参数变为[ht]。而11795.md中的两个用例之所以没有\caption/\label，正是因为其 caption 文本为空、仅携带属性——这正是该回归测试要锁定的边界行为。

七、实战验证与适用边界

要复现本文全部结论，只需按测试文档原样执行：

# 在 pandoc 源码仓库根目录运行 printf '||\n|--|--\n|a|b\n\n: {#foo .unnumbered}\n' | pandoc -t latex printf '||\n|--|--\n|a|b\n\n: {.float}\n' | pandoc -t latex

两个命令的输出应分别与 test/command/11795.md 中的预期完全一致。也可以使用pandoc -t native查看中间 AST，确认属性被挂载在Table节点的Attr上。

需要明确的适用前提与限制：

• 本文行为针对LaTeX 输出（-t latex），其他输出格式（如 HTML、ConTeXt）对float、unnumbered的解释各自独立；
• \def\LTcaptype{none}抑制的是 LaTeX 侧table/longtable计数器的自动递增，Markdown 源中并不存在"表格编号"这一概念；
• 浮动环境与latex-placement仅在输出 LaTeX 时生效，且仅在使用table浮动体路径（即声明float类）时才有实际意义；
• 本测试用例同时要求表格读取扩展table_captions处于开启状态，pandoc 默认的 Markdown 变体（markdown、markdown_strict等）中该扩展默认启用的组合可在 pandoc 手册（MANUAL.txt）中查证。

通过 src/Text/Pandoc/Writers/LaTeX/Table.hs 的源码阅读，可以确认11795.md两条用例分别覆盖了tableToLaTeX中两条互斥分支：unnumbered走makeUnnumbered包装的 longtable 路径，float走浮动table路径。二者共同构成了 pandoc 表格 LaTeX 输出中最关键的"是否浮动、是否编号"控制面，理解这段实现，即可精准预测任意属性组合下的输出形态。

【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc