企业官网建设流程全解析

• 文档
• 开发工具
• CLI

导读

本文围绕 Pandoc 仓库中的命令测试用例 test/command/10730.md，深入解读 Org-mode 阅读器对等宽（verbatim）行内标记=...=的解析行为：包括如何将多行等宽文本折叠为单个空格、为何生成带verbatimclass 的Code元素，以及 Pandoc 的命令测试框架如何通过标准输入驱动pandoc -f org -t native完成回归验证。读完本文，你将掌握 Org 等宽/代码标记与 Pandoc 行内 AST 的映射关系，并能独立阅读和编写同类命令测试用例。

一、测试用例 10730 揭示的核心行为

test/command/10730.md 全文是一个标准的 Pandoc 命令测试代码块：

% pandoc -f org -t native =hi there= ^D [ Para [ Code ( "" , [ "verbatim" ] , [] ) "hi there" ] ]

该用例验证的是：Org 等宽标记可以跨行书写，且内部的换行符在解析时会被转换为一个普通空格。输入=hi\nthere=被解析为：

• 块级结果：一个段落Para；
• 行内结果：Code ( "", [ "verbatim" ], [] ) "hi there"，即：
  • 属性为空字符串（无语言标注）；
  • 带verbatimclass；
  • 文本内容为"hi there"，中间的换行被折叠成空格。

这与 Emacs Org-mode 对等宽标记跨行时的空格处理语义保持一致，也说明了 Pandoc 的 Org 阅读器并非机械地把标记内文本原样保留，而是进行了规范化处理。

二、Org 等宽标记语法：=与~的分工

在 Org-mode 语法中，行内标记有两类“等宽”变体，Pandoc 的 Org 阅读器在 src/Text/Pandoc/Readers/Org/Inlines.hs 中分别实现：

verbatim :: PandocMonad m => OrgParser m (F Inlines) verbatim = return . B.codeWith ("", ["verbatim"], []) <$> verbatimBetween '=' code :: PandocMonad m => OrgParser m (F Inlines) code = return . B.code <$> verbatimBetween '~'

两者的解析流程共用verbatimBetween，差异仅在边界字符与产出元素：=走codeWith并附加verbatimclass，~走普通code。这也解释了为何 10730 用例的期望输出中Code携带["verbatim"]这一 class——它是 Org 等宽标记区别于代码标记的结构化标识，后续写入 HTML 时会被输出为<code class="verbatim">。

对应的单元测试位于 test/Tests/Readers/Org/Inline.hs，两行即可对照验证：

"Verbatim" =: "=Robot.rock()=" =?> para (codeWith ("", ["verbatim"], []) "Robot.rock()") "Code" =: "~word for word~" =?> para (code "word for word")

三、源码实现：跨行等宽文本如何被折叠为空格

10730 用例最值得玩味之处是换行处理。核心实现在 verbatimBetween：

verbatimBetween :: PandocMonad m => Char -> OrgParser m Text verbatimBetween c = newlinesToSpaces <$> try (emphasisStart c *> many1TillNOrLessNewlines 1 verbatimChar (emphasisEnd c)) where verbatimChar = noneOf "\n\r" >>= updatePositions newlinesToSpaces = T.map (\d -> if d == '\n' then ' ' else d)

逐层拆解：

1. emphasisStart c（源码）：校验开标记位置是否合法——前置字符必须满足afterEmphasisPreChar，开标记后紧跟的字符不能属于emphasisForbiddenBorderChars（即"\t\n\r \x200B"，见 源码），随后把该字符压入行内字符栈以支持嵌套解析。
2. many1TillNOrLessNewlines 1 verbatimChar (emphasisEnd c)（源码）：逐字符读取，遇到换行时允许继续读取，但最多累计 1 个换行、总跨度不超过 2 行；一旦超过限制则回退，标记视为不成立。这正是“等宽标记至多跨两行”这一语法边界的实现来源。
3. verbatimChar = noneOf "\n\r"：标记体内的字符不允许再包含换行本身——原始换行只出现在“行与行”之间。
4. newlinesToSpaces：把收集到的换行符统一映射为空格。10730 中=hi\nthere=的\n因此变成"hi there"中的那个空格。

关闭标记emphasisEnd c（源码）同样有边界约束：关闭标记后必须处于行尾或后随emphasisPostChars中的合法字符，从而避免把普通句子中的孤立=误判为等宽标记。

需要说明的是，many1TillNOrLessNewlines中的换行约束（emphasisAllowedNewlines = 1，见 源码）与 Org 的通用强调规则一致：所有行内强调标记（斜体、粗体、删除线、下划线、等宽、代码）都共享“最多一个换行”的跨度上限。因此=hi\nthere=合法，而三段以上的多行内容不会被视为一个等宽标记。

四、命令测试框架：10730 是如何被执行的

test/command/*.md下的每个文件都是若干“命令测试”的集合，执行逻辑位于 test/Tests/Command.hs：

• 代码块第一行以%开头，其后是待执行的命令（如pandoc -f org -t native）；
• 后续行作为命令的标准输入，直到单独一行的^D结束；
• ^D之后的行是期望的 stdout 输出；
• 若需校验 stderr，则用2>前缀标注；若需校验非零退出码，则在最后追加=> <exitcode>。

runCommandTest函数（源码）解析上述格式后调用execTest执行命令，并把实际输出与期望输出做 golden diff。测试运行器tests（源码）会扫描command目录下所有.md文件，为每个代码块生成一个名为#编号的 Tasty 测试组——因此 10730 这个用例既是文档、也是可自动运行的回归测试。

值得注意的是，实际执行时 pandoc 命令会被替换为test-pandoc --emulate（见 pandocToEmulate），即在测试环境中模拟pandoc可执行文件的行为，保证测试不依赖外部安装的二进制。

五、在真实使用中验证与排查

复现方式

在仓库根目录构建出pandoc可执行文件后，可直接复现该用例：

printf '=hi\nthere=\n' | pandoc -f org -t native

期望输出：

[ Para [ Code ( "" , [ "verbatim" ] , [] ) "hi there" ] ]

如果换行处出现解析失败或输出与预期不符，可按以下顺序排查：

1. 确认标记处于合法位置：等宽标记不能以空格、制表符、换行、\x200B（零宽空格）等emphasisForbiddenBorderChars中的字符紧贴内侧边界；开标记前必须是合法的强调前置字符。
2. 确认没有超过两行：emphasisAllowedNewlines = 1意味着标记内最多出现 1 个换行，超出则标记不成立，=会被当作普通字符。
3. 确认关闭标记后的字符合法：关闭标记后必须是行尾或emphasisPostChars中允许的字符，否则解析回退。

与~...~代码标记的区分

如果需求是“代码片段”，应使用~...~（产出无 class 的Code）；如果需求是“等宽文本并保留 verbatim 语义”，应使用=...=。两者在 AST 层面的差异（是否携带["verbatim"]class）会直接影响后续 writer 的输出样式，例如 HTML writer 会渲染为<code class="verbatim">而普通代码为<code>。

强调规则的定制入口

Org 的强调边界字符默认值在源码中固化（emphasisForbiddenBorderChars = "\t\n\r \x200B"），但 Pandoc 允许在 Org 源文件中通过特殊行临时覆盖，详见 doc/org.md 的 Emphasis rules 章节：

#+pandoc-emphasis-pre: "-\t ('\"{\x200B" #+pandoc-emphasis-post: "-\t\n .,:!?;'\")}[\x200B"

这两行分别对应 Emacs 变量org-emphasis-regexp-components中的 pre/post 字符集合，参数必须是合法的 Haskell 字符串，解析失败时恢复默认值；它们只影响其后文档的解析，且应位于文件靠前位置才能对整个文档生效。

六、小结

通过 test/command/10730.md 这一最小用例，可以完整看到 Pandoc Org 阅读器对等宽标记的处理链路：

• 语法层：=...=与~...~共享verbatimBetween解析器，仅产出元素与 class 不同；
• 语义层：跨行时换行折叠为空格（newlinesToSpaces），跨度上限为 1 个换行（2 行）；
• 验证层：命令测试以“命令 + stdin + 期望 stdout”的代码块形式沉淀为可自动运行的 golden 测试，与 test/Tests/Readers/Org/Inline.hs 中的单元测试互为补充。

对开发者而言，这一用例同时提供了三份可复用的知识：Org 等宽标记的准确语法与边界条件、Pandoc 行内 AST（Code与verbatimclass）的结构化表达，以及 Pandoc 命令测试文件的标准编写格式——三者结合，足以支撑你在自己的文档转换管道中准确预测并验证 Org 等宽文本的解析结果。

• 文档
• 开发工具
• CLI