Pandoc MediaWiki 表格解析实战:HTML 注释处理与 `-f mediawiki` 读取器原理剖析
Pandoc MediaWiki 表格解析实战:HTML 注释处理与 -f mediawiki 读取器原理剖析
本篇技术指南围绕 Pandoc 中 MediaWiki 读取器的表格解析能力展开,以 test/command/8110.md 这一官方回归测试为锚点,完整讲解 MediaWiki 表格语法的转换流程,重点剖析“行首后紧跟 HTML 注释”这一曾被修复的边缘场景(对应 GitHub issue #8110),并给出可复制、可运行的命令行验证方法。读者学完后将能:熟练使用 pandoc -f mediawiki 将维基表格转换为标准 HTML 表格,理解读取器底层状态机(行分隔符、单元格分隔符、列头判定)的解析顺序,并掌握如何通过 test/command 目录中的回归测试用例来验证 Pandoc 读取器的行为。
一、测试用例速览:一段带注释的 MediaWiki 表格
test/command/8110.md 是一个典型的 Pandoc 命令回归测试(golden test),它完整记录了输入、命令行与期望输出:
% pandoc -f mediawiki
{| class="wikitable"
! Header text
! Header text
! Header text
|
|-
| Example
| Example
| Example
|
|- <!-- This is a comment -->
| Example
| Example
| Example
|}
^D
<table>
<thead>
<tr>
<th>Header text</th>
<th>Header text</th>
<th>Header text</th>
</tr>
</thead>
<tbody>
<tr>
<td>Example</td>
<td>Example</td>
<td>Example</td>
</tr>
<tr>
<td>Example</td>
<td>Example</td>
<td>Example</td>
</tr>
</tbody>
</table>
1.1 测试文件的结构约定
Pandoc 仓库中 test/command/ 目录下的 *.md 文件是可自动执行的命令行回归测试:文件以 % pandoc ... 开头声明要运行的命令,随后是标准输入内容(以 ^D 表示 EOF),^D 之后则是期望的标准输出。test-pandoc.hs 驱动的测试框架会逐字节比对实际输出与期望输出,任何不一致都会导致测试失败。因此,8110.md 本身既是文档,也是一份可验证的契约。
1.2 用例覆盖的核心场景
该用例同时验证了 MediaWiki 表格解析的多个要点:
{|/|}包裹的完整表格结构;!前缀的表头行(<thead>/<th>);|-行分隔符;class="wikitable"表格属性被正确解析;- 第二段表体行前紧跟 HTML 注释
<!-- This is a comment -->,注释被忽略且行仍被正确解析为新的<tr>——这正是本测试的回归对象(issue #8110)。
二、从 MediaWiki 表格到 HTML:解析流程全解
2.1 命令入口与格式识别
在 MANUAL.txt 中,mediawiki 被列为 Pandoc 默认支持的输入格式之一。运行时通过 -f mediawiki 指定输入格式,-t html(或省略时的默认输出)指定输出格式。整个读取过程由 src/Text/Pandoc/Readers/MediaWiki.hs 中的 readMediaWiki 函数完成:它接收 ReaderOptions 与输入文本,调用 parseMediaWiki 解析器,最终产出 Pandoc 内部文档表示(Pandoc 类型),随后由 HTML 写入器渲染为 <table>。
2.2 表格块级解析器
block 解析器(MediaWiki.hs)按优先级依次尝试:空行、table、标题、水平线、有序/无序/定义列表、HTML 注释、预格式化块、块级标签、模板与段落。table(MediaWiki.hs)是其中专用于表格的分支,其完整工作流如下:
- 表格起始:
tableStart(MediaWiki.hs)要求{|位于列首(guardColumnOne),并允许前导空白; - 属性解析:
parseAttrs(MediaWiki.hs)解析class="wikitable"这类key="value"或key=value形式的属性,其中width属性还会经parseWidth(MediaWiki.hs)换算为相对列宽; - 表头判定:通过
lookAhead (skipSpaces *> char '!')前瞻探测首行是否以!开头,决定该行进入<thead>还是作为普通表体行; - 行与单元格解析:
tableRow(MediaWiki.hs)逐行调用tableCell(MediaWiki.hs),后者经cellsep(MediaWiki.hs)识别|/!单元格分隔符,并处理align、colspan、rowspan等单元格属性; - 行分隔:
rowsep(MediaWiki.hs)匹配|-行分隔符; - 表格结束:
tableEnd(MediaWiki.hs)匹配列首的|},随后经compactifyTable压缩空单元格结构,产出最终的 Pandoc 表格(B.table)并交由 HTML 写入器渲染。
2.3 行分隔符中的注释处理(#8110 修复点)
rowsep 的完整定义是本次回归测试的关键实现:
rowsep = try $ guardColumnOne *> skipSpaces *> sym "|-" <*
many (char '-') <* optional parseAttrs
<* skipSpaces
<* skipMany htmlComment
<* blanklines
可以看到,在匹配到 |- 之后,解析器依次处理:连续的 - 字符、可选的行属性、空白、任意数量的 HTML 注释(skipMany htmlComment),最后是空行。正是 skipMany htmlComment 这一行,使得 |- <!-- This is a comment --> 这种“行分隔符后紧跟注释”的写法可以被正确识别。
在 changelog.md 中记录了这一修复:"Allow HTML comment after row start (#8110)"(允许行首后出现 HTML 注释),归属于 MediaWiki 读取器的小节。也就是说,在修复之前,|- 后的 HTML 注释会导致行分隔符解析失败,进而可能把后续内容误判为前一行的延续,破坏整个表格结构;修复后,注释被静默跳过(丢弃),表格行照常切分。
2.4 HTML 注释在解析器中的一般处理
HTML 注释在 MediaWiki 读取器中并不特殊:htmlComment(MediaWiki.hs)复用 Text.Pandoc.Readers.HTML 的 isCommentTag 来匹配 <!-- ... --> 结构。除了 rowsep 中用于容忍行分隔符后的注释外:
block解析器(MediaWiki.hs)允许注释单独成块时被整体忽略(mempty <$ try (spaces *> htmlComment));tableRow(MediaWiki.hs)在解析行首时也执行skipMany htmlComment,因此即使注释出现在新行行的最前面,也不会干扰行解析;whitespace(MediaWiki.hs)将行内注释视为空白处理。
2.5 输出侧:表格如何变成 <table>
MediaWiki 读取器产出的是 Pandoc 统一的内部表格表示(Table 块,含 TableHead、TableBody、TableFoot)。HTML 写入器负责将其渲染为语义化结构:表头行输出为 <thead><tr><th>…</th></tr></thead>,表体行输出为 <tbody><tr><td>…</td></tr></tbody>,表格属性(如 class="wikitable")则写入 <table> 标签的属性中。这也解释了 8110 用例期望输出中 <th>Header text</th> 与 <td>Example</td> 的对应关系。
三、动手验证:复现 8110 测试
3.1 使用命令行直接验证
如果本机已安装 Pandoc,可完全复现该测试。将用例输入保存为 table.wiki:
{| class="wikitable"
! Header text
! Header text
! Header text
|
|-
| Example
| Example
| Example
|
|- <!-- This is a comment -->
| Example
| Example
| Example
|}
然后执行:
pandoc -f mediawiki -t html table.wiki
输出应与 8110 用例的期望输出完全一致:两行表体 <tr>,注释被丢弃且不产生任何残留节点。这说明读取器在“注释夹在行分隔符与新行之间”时依然能正确切分表格行。
3.2 交叉验证其他格式
-
转换为 Pandoc 原生格式观察内部表示:
pandoc -f mediawiki -t native table.wiki可看到
Table块、TableHead、TableBody与ColWidth列宽信息,有助于理解内部结构。 -
转换为 Markdown / GFM(GitHub 风格):
pandoc -f mediawiki -t gfm table.wiki输出为 GFM 管道表格,可用于验证表格属性与列宽在不同目标格式下的降级表现。
仓库中其他 MediaWiki 读取器回归测试同样可以参考,例如 test/command/10390.md、test/command/2606.md(含多个 -f mediawiki -t html5 用例)、test/command/3585.md(mediawiki+smart 扩展组合)以及 test/command/11299.md(输出 native 格式),它们共同覆盖了表格、列表、链接、数学等更广泛的 MediaWiki 语法。
3.3 运行仓库测试套件
若需要从源码运行测试,可参考 test/Tests/Old.hs:其中将 mediawiki 读取器与写入器纳入 writerTests' / extWriterTests' / reader 测试组,输入为 test/mediawiki-reader.wiki,期望输出为 test/mediawiki-reader.native。命令回归测试(含 8110)则通过 test/test-pandoc.hs 执行,例如:
cabal test pandoc-tests --test-options='-p command'
四、边界与局限
从源码结构可以推断,当前 MediaWiki 读取器仍存在若干已知边界(文件头部的 TODO 注释亦有提及,见 MediaWiki.hs):
- 嵌套表格:TODO 中明确写有 "correctly handle tables within tables",单元格内嵌套表格的解析属于已知未完全覆盖场景;
- 模板与魔术字:
template解析器(MediaWiki.hs)仅将{{...}}模板整体保留为rawBlock "mediawiki"原始内容,不做模板展开;行为开关类魔术字(如__NOTOC__)则经behaviorSwitch(MediaWiki.hs)写入文档元数据; - 注释位置:8110 修复针对的是行分隔符(
|-)之后的注释;从tableRow的实现看,行首(第一个单元格前)的注释也会被跳过,但注释出现在单元格内容中间时,按whitespace规则会退化为空格处理。
五、小结
test/command/8110.md 表面上只是一个 41 行的回归测试,但它精确锚定了 Pandoc MediaWiki 读取器在表格行切分上的一个真实缺陷与修复方案。通过该用例,我们梳理了从 -f mediawiki 命令入口、readMediaWiki 状态机、table/rowsep/tableCell 解析器链,到 HTML 写入器输出 <table> 的完整链路,并给出了可复现的验证命令。对于需要批量迁移维基站点内容、或为 Pandoc 贡献读取器修复的开发者,这份用例与 src/Text/Pandoc/Readers/MediaWiki.hs 源码配合阅读,是最直接的入手路径。