Pandoc 命令测试用例深度解析：`. . .` 暂停标记在普通 HTML 输出中的行为边界

文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载本篇指南以 pandoc 仓库中的命令测试用例 test/command/8281.md 为核心剖析 Markdown 输入中的. . .三个空格分隔的句点段落在默认-t html输出下为何被原样保留为普通段落p. . ./p而非像 reveal.js 等幻灯片格式那样被转换为逐段揭示fragment效果。通过对照仓库源码Markdown 阅读器、HTML 写出器与同类幻灯片测试用例读者将掌握 pandoc 暂停标记的解析路径、触发条件与扩展边界并能独立复现与验证该行为。一、测试用例本身一份可复现的 golden testtest/command/8281.md是一个完整的 pandoc 命令测试command test文件全文如下% pandoc -t html # Title test . . . test ^D h1 idtitleTitle/h1 ptest/p p. . ./p ptest/p按照 test/Tests/Command.hs 头部注释定义的格式约定第一行以%开头是待执行的命令此处为pandoc -t html%之后到^D之前的行作为标准输入stdin传给命令此处为一段 Markdown 文档以^D结尾的行标记 stdin 终止^D之后的行是期望的标准输出stdout逐行比对。因此该测试断言的核心事实是输入中的. . .段落在普通 HTML 写出时被当作一个普通段落输出为p. . ./p既没有变成水平分隔线也没有触发任何幻灯片暂停/分段逻辑。二、为什么. . .不是水平分隔线Markdown 阅读器的 hrule 解析一个常见的疑问是. . .看起来很像分隔线为何没有被解析为hr答案在 Markdown 阅读器的实现中。在 src/Text/Pandoc/Readers/Markdown.hs 中水平分隔线解析器hrule的实现为hrule :: PandocMonad m ParsecT Sources st m (F Blocks) hrule try $ do skipSpaces start - satisfy isHruleChar count 2 (skipSpaces char start) skipMany (spaceChar | char start) newline optional blanklines return $ return B.horizontalRule而合法的分隔线起始字符由 isHruleChar 限定isHruleChar * True isHruleChar - True isHruleChar _ True isHruleChar _ False可以看到*、-、_三种字符才能触发分隔线解析句点.不在其中。因此. . .无法匹配hrule最终作为包含三个Str .与两个空格的内联序列被解析成一个普通段落Para。这正是测试输出中p. . ./p的由来。三、-t html下为何不触发暂停逻辑HTML 写出器中的条件分支与阅读器不同暂停标记的识别发生在写出端。在 src/Text/Pandoc/Writers/HTML.hs 中HTML 写出器对块序列做了如下处理let isSec (Div (_,section:_:) _) True isSec (Div _ zs) any isSec zs isSec _ False let isPause (Para [Str .,Space,Str .,Space,Str .]) True isPause _ False let fragmentClass case slideVariant of RevealJsSlides - fragment _ - incremental let inDiv zs RawBlock (Format html) (div class\ fragmentClass \) : (zs [RawBlock (Format html) /div]) let breakOnPauses zs case splitBy isPause zs of [] - [] y:ys - y concatMap inDiv ys let breakPauses if slide then walk breakOnPauses else id -- avoid a pointless traversal关键点有两处暂停段的判定条件isPause精确匹配「段落内恰好是句点、空格、句点、空格、句点」的 AST 形态。这与 8281 用例的输入结构一一对应——阅读器将. . .解析为Para [Str ., Space, Str ., Space, Str .]。触发开关breakPauses只有在slide为真时才应用if slide then walk breakOnPauses else id而slide由slideVariant / NoSlides决定。-t html不是任何幻灯片变体slideVariant为NoSlides因此breakPauses退化为恒等函数isPause匹配到的段落被原样写出即p. . ./p。源码注释 avoid a pointless traversal 也表明非幻灯片场景下连遍历都是刻意省去的。四、对照实验幻灯片格式下. . .的行为为了理解 8281 用例所锚定的「边界」可以对照仓库中三个同为暂停标记主题的命令测试test/command/5819.mdpandoc -t revealjs --slide-level2输出中. . .消失后续内容被包入div classfragmenttest/command/7201.mdpandoc -t revealjs --slide-level1配合多栏布局. . .之后的列表被包裹为div classfragmenttest/command/7582.mdpandoc -t revealjs下右栏内容被div classfragmentdiv classcolumn包裹。三个用例的输出均可见div classfragment包装层与 8281 用例中p. . ./p的普通段落输出形成鲜明对照。这正是 HTML.hs 中fragmentClass分支的体现reveal.js 使用fragment类其他幻灯片变体如 beamer、slidy 等则使用incremental类。五、功能文档佐证MANUAL.txt 中的 Inserting pauses暂停标记的正式用法记录在 MANUAL.txt 的 Inserting pauses 一节You can add pauses within a slide by including a paragraph containing three dots, separated by spaces:# Slide with a pause content before the pause . . . content after the pause手册同时给出一个重要限制说明该特性尚未在 PowerPoint 输出中实现this feature is not yet implemented for PowerPoint output。这进一步印证了暂停标记属于幻灯片专属语义而 8281 用例恰恰验证了它在非幻灯片输出中不会越界生效。六、如何运行与扩展验证该测试该用例属于 pandoc 的 command 测试套件运行入口为 test/test-pandoc.hs测试逻辑由 test/Tests/Command.hs 提供。其执行流程是读取 test/command 目录下的每个.md测试文件按前述格式解析出命令、stdin 与期望输出然后实际调用pandoc可执行文件并比对结果。开发者可通过项目标准的构建测试流程如cabal test或stack test参考 README.md 与 INSTALL.md运行整套用例。若要手工复现该行为只需在 shell 中执行printf # Title\n\ntest\n\n. . .\n\ntest\n | pandoc -t html输出即与测试期望一致h1 idtitleTitle/h1 ptest/p p. . ./p ptest/p可以进一步验证行为边界改用pandoc -t revealjs. . .之后的内容将被div classfragment包裹而改用pandoc -t markdown或pandoc -t html -s均可观察输出形态的变化。此外h1 idtitle中的自动编号id来自 pandoc markdown 默认启用的auto_identifiers扩展属于标题的常规处理与暂停标记无关。小结通过 test/command/8281.md 这一个短小精悍的用例可以完整串联起 pandoc 的三层设计Markdown 阅读器仅将. * _识别为分隔线字符、句点段落在 AST 中保持普通段落形态HTML 写出器以slideVariant作为暂停逻辑的总开关仅在幻灯片变体下将精确匹配的. . .段落替换为 fragment/incremental 包装层官方手册则明确了暂停特性的适用范围与 PPTX 输出的未实现限制。8281 用例正是守护这一行为边界、防止暂停逻辑泄漏到普通 HTML 输出的回归测试。赞分享文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载相关推荐Pandoc Reveal.js 输出中的暂停Pause与片段Fragment5819 号命令测试的完整拆解Pandoc Reveal.js 输出中的暂停Pause与片段Fragment5819 号命令测试的完整拆解 导读 本文以 pandoc 仓库中的黄文档开发工具CLIPandoc 命令行测试用例 8364 深度解析citeproc 引用处理与 JATS 输出实战Pandoc 命令行测试用例 8364 深度解析citeproc 引用处理与 JATS 输出实战 导读 本文以 pandoc 仓库 test/command/文档开发工具CLIPandoc 中 implicit_figures 扩展的行为边界以 commonmark 命令测试 6350 为例的源码级解析Pandoc 中 implicit_figures 扩展的行为边界以 commonmark 命令测试 6350 为例的源码级解析 本篇文章聚焦 Pandoc文档开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考