文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载four_space_rule是 pandoc 中一个复古型的 Markdown 扩展它把列表解析与输出的缩进规则恢复到 pandoc ≤ 2.0 的经典行为。本文以仓库中的命令测试用例 test/command/10812.md 为骨架完整讲解该扩展在plain纯文本writer 下的行为差异、默认关闭的事实依据并结合 Markdown 读取器 与 Markdown/plain 写入器 的源码调用链说明其底层实现原理。读完本文你将掌握如何用four_space_rule/-four_space_rule精确控制列表项的缩进宽度并能看懂同类测试用例的验证逻辑。一、测试场景four_space_rule对 plain writer 的影响在 pandoc 的命令测试套件由 test/Tests/Command.hs 驱动、测试用例存放于 test/command 目录中10812.md专门验证两件事开启four_space_rule后plain输出中的列表项内容会以四空格缩进默认不开启情况下列表项内容保持单空格缩进行为不变。该用例输入一个简单文档一个标题段落、一个过渡段落、一个三项的无序列表a、b、c分别用两种 writer 配置输出并比对结果。它属于典型的golden test——用% pandoc行描述要执行的命令行用^D标记标准输入结束之后紧跟期望的标准输出。二、用例原文开启与默认关闭的完整对照2.1 开启four_space_rule时的输出% pandoc -f markdown -t plainfour_space_rule This is the title Here we fix: - a - b - c ^D期望输出This is the title Here we fix: - a - b - c注意三个列表项从- a变成了- a连字符后跟 3 个空格加上连字符本身共占 4 列这正是四空格规则在输出端的体现列表项内容的起始列被对齐到第 4 列。2.2 默认关闭时的输出% pandoc -f markdown -t plain This is the title Here we fix: - a - b - c ^D期望输出This is the title Here we fix: - a - b - c用例的第二个检查点明确断言four_space_rule默认是关闭的。不加扩展开关时plain 输出保持现代 Markdown 的单空格风格输出与输入完全一致。三、扩展语义与历史背景回到 pandoc ≤ 2.0 的列表规则3.1 官方定义在 MANUAL.txt 的扩展参考章节中官方对four_space_rule的定义是Selects the pandoc 2.0 behavior for parsing lists, so that four spaces indent are needed for list item continuation paragraphs.即选择 pandoc ≤ 2.0 的列表解析行为要求列表项续段continuation paragraphs使用四空格缩进。它的作用并不只限于输出首先是一个影响解析的扩展。3.2 为什么叫规则续段缩进的歧义Markdown 中一个列表项可以包含多个块多个段落、代码块、嵌套列表等。读取器需要根据缩进判断哪些内容属于当前列表项。在 pandoc 2.0 之前规则是列表项内容的续段必须缩进 4 个空格而 pandoc 2.0 之后改为更宽松的规则通常 2 个空格即可具体取决于列表标记宽度。four_space_rule就是把这个旧规则重新启用用于兼容旧文档。3.3 默认关闭属于非默认 Markdown 扩展该扩展在 src/Text/Pandoc/Extensions.hs 中定义| Ext_four_space_rule -- ^ Require 4-space indent for list contents并出现在allMarkdownExtensions列表src/Text/Pandoc/Extensions.hs中——全部 Markdown 扩展集合但它不在pandoc 默认启用的pandocExtensions里因此默认不生效。这也正是测试用例 10812 中第二个检查点默认输出不变存在的意义用测试固化默认关闭这一契约。四、源码级实现扩展如何贯穿 reader 与 writerfour_space_rule并非只影响某一端而是同时影响 Markdown 读取器解析缩进和 Markdown 家族写入器生成缩进包含markdown、commonmark之外的plain。下面按数据流拆解。4.1 Reader 侧列表解析中的四空格判定在 src/Text/Pandoc/Readers/Markdown.hs 中三种列表解析器都会先探测该扩展是否启用得到一个布尔标志fourSpaceRule无序列表L1002-L1007bulletList do fourSpaceRule - (True $ guardEnabled Ext_four_space_rule) | return False items - fmap sequence $ many1 $ listItem fourSpaceRule bulletListStart return $ B.bulletList $ fmap compactify items有序列表L993-L995fourSpaceRule - (True $ guardEnabled Ext_four_space_rule) | return (style Example)这里有一个值得注意的特例当列表样式为Example示例列表ext_example_lists时即使未开启four_space_rulefourSpaceRule也为True——即示例列表始终按四空格规则解析。这与 MANUAL.txt 中示例列表需要四空格缩进的说明一致。定义列表L1023fourSpaceRule - (True $ guardEnabled Ext_four_space_rule) | pure False这个布尔值随后被传入listItem/rawListItemL975用于决定列表项续段至少需要多少缩进才算属于本列表项。开启扩展后4 空格缩进以内的内容不再被接纳为续段从而改变块的归属判定。4.2 Writer 侧plain/markdown 输出的缩进生成pandoc 的plainwriter 与markdownwriter 共用 src/Text/Pandoc/Writers/Markdown.hs 的实现通过envVariant区分PlainText与Markdown等变体。four_space_rule在写入端控制三处缩进① 无序列表项L819-L824Markdown | isEnabled Ext_four_space_rule opts - - T.replicate (writerTabStop opts - 2) PlainText | isEnabled Ext_four_space_rule opts - - T.replicate (writerTabStop opts - 2) _ - - 当扩展启用且writerTabStop为默认值 4 时列表项标记为- 再补4 - 2 2个空格即- ——对应测试 10812 中输出的- a。未启用时仅输出- 单空格。② 有序列表项L849-L851let ind if isEnabled Ext_four_space_rule opts then writerTabStop opts else T.length marker sps开启后续行挂起hang的缩进直接取writerTabStop默认 4 列而不是按标记宽度动态计算。③ 定义列表L877-L879n | variant Markua - 2 | isEnabled Ext_four_space_rule opts , n 2 - n | otherwise - 2同理定义列表的引导缩进在开启扩展时取tabStop4否则取 2。4.3writerTabStop缩进计算的基准值上述所有计算都依赖writerTabStop选项。它的定义与默认值位于 src/Text/Pandoc/Options.hs, writerTabStop :: Int -- ^ Tabstop for conversion btw spaces and tabs默认值为 4L400。因此四空格规则在默认配置下正好等于一个 tab stop若用户通过--tab-stop修改该值four_space_rule的缩进也会随之变化——它是跟随 tab stop 的规则而非字面写死的 4。五、关联测试同一扩展在 markdown 与定义列表上的验证four_space_rule的测试不止 10812 一处仓库中还有两个兄弟用例可以从侧面印证其行为5.1 markdown writer 下的嵌套列表test/command/7172.md% pandoc -t markdown - one - two ^D - one - two% pandoc -t markdownfour_space_rule - one - two ^D - one - two可见开启扩展后不仅顶层项变成- one嵌套子列表也整体右移并保持四空格对齐——与 10812 中 plain 输出的行为完全一致证明该逻辑在Markdown与PlainText两个变体间共享。5.2 定义列表的四空格输出test/command/11542.md该用例先用 native 格式定义了一个包含代码块的定义列表再对比默认输出与four_space_rule输出% pandoc -f native -t markdown [ DefinitionList [ ( [ Str Input ] , [ [ CodeBlock ( , [] , [] ) Term\n\n : Def ] ] ) ] ] ^D Input : Term : Def% pandoc -f native -t markdownfour_space_rule [ DefinitionList [ ( [ Str Input ] , [ [ CodeBlock ( , [] , [] ) Term\n\n : Def ] ] ) ] ] ^D Input : Term : Def同时该用例还验证了按四空格缩进书写定义列表、再读回 native能够保持 AST 一致round-trip说明 reader 与 writer 两侧的规则是对称的。六、实战建议何时开启four_space_rule结合以上实现与测试可以给出如下判断标准场景建议需要与 pandoc ≤ 2.0 时代的文档、脚本保持完全一致的列表缩进开启-t plainfour_space_rule/-t markdownfour_space_rule处理大量手工书写的旧式四空格缩进 Markdown 源文件开启-f markdownfour_space_rule输出需要被其它严格按四空格续段解析的工具消费开启 writer 侧扩展面向新文档、追求更紧凑的输出保持默认关闭使用方法与其它 pandoc 扩展一致用/-后缀在格式名上开关例如pandoc input.md -t plainfour_space_rule -o output.txt pandoc -f markdownfour_space_rule -t native input.md需要注意的是plain输出格式默认不包含该扩展必须显式写出four_space_rule才会生效——这正是 test/command/10812.md 通过两组对照用例固化的行为契约。七、版本沿革与变更记录从仓库的变更记录可以追踪该扩展的演进扩展本身在较早版本中引入用于恢复旧式解析行为changelog.md 附近有-f markdownfour_space_rule的用法说明Ext_four_space_rule构造器同期加入 src/Text/Pandoc/Extensions.hs后来补充了对plain输出的支持对应变更记录为 Support thefour_space_ruleextension forplainoutputchangelog.md发布公告中亦明确 Thefour_space_ruleextension now works forplainoutputrelease-announcements.txt另有修正 Use correct indentation whenfour_space_ruleextension is …changelog.md说明其缩进计算经历了持续打磨。命令行手册 pandoc-cli/man/pandoc.1 中也有该扩展的独立章节与 MANUAL.txt 的说明保持一致可作为查阅入口。结语four_space_rule是一个小而典型的 pandoc 扩展它同时贯穿读取器与写入器两端用一枚布尔标志统一了列表续段解析和输出缩进两套逻辑。通过 test/command/10812.md 这组对照用例可以清晰看到默认关闭 显式开启后四空格对齐的完整行为而 Markdown 读取器 与 写入器 的源码则揭示了writerTabStop在其中扮演的基准角色。无论是兼容旧文档还是生成规整的纯文本列表这个扩展都是值得掌握的一个开关。赞分享文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载相关推荐pandoc 定义列表与代码块往返转换four_space_rule 扩展的缩进语义剖析pandoc 定义列表与代码块往返转换four_space_rule 扩展的缩进语义剖析 导读 本文以仓库中的命令级测试用例 test/command/115文档开发工具CLIPandoc four_space_rule 扩展全解析从 3511 号回归测试看列表续行缩进规则的底层实现Pandoc four_space_rule 扩展全解析从 3511 号回归测试看列表续行缩进规则的底层实现 在 Pandoc 的 Markdown 解析器中文档开发工具CLIpandoc pipe_tables 扩展解析从 3734 命令测试看表格输出策略与相对列宽取舍pandoc pipe_tables 扩展解析从 3734 命令测试看表格输出策略与相对列宽取舍 本篇文章以 pandoc 仓库中的命令测试 test/com文档开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pandoc `four_space_rule` 扩展解析：plain 输出如何恢复 pandoc 2.0 的四空格列表缩进
文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载four_space_rule是 pandoc 中一个复古型的 Markdown 扩展它把列表解析与输出的缩进规则恢复到 pandoc ≤ 2.0 的经典行为。本文以仓库中的命令测试用例 test/command/10812.md 为骨架完整讲解该扩展在plain纯文本writer 下的行为差异、默认关闭的事实依据并结合 Markdown 读取器 与 Markdown/plain 写入器 的源码调用链说明其底层实现原理。读完本文你将掌握如何用four_space_rule/-four_space_rule精确控制列表项的缩进宽度并能看懂同类测试用例的验证逻辑。一、测试场景four_space_rule对 plain writer 的影响在 pandoc 的命令测试套件由 test/Tests/Command.hs 驱动、测试用例存放于 test/command 目录中10812.md专门验证两件事开启four_space_rule后plain输出中的列表项内容会以四空格缩进默认不开启情况下列表项内容保持单空格缩进行为不变。该用例输入一个简单文档一个标题段落、一个过渡段落、一个三项的无序列表a、b、c分别用两种 writer 配置输出并比对结果。它属于典型的golden test——用% pandoc行描述要执行的命令行用^D标记标准输入结束之后紧跟期望的标准输出。二、用例原文开启与默认关闭的完整对照2.1 开启four_space_rule时的输出% pandoc -f markdown -t plainfour_space_rule This is the title Here we fix: - a - b - c ^D期望输出This is the title Here we fix: - a - b - c注意三个列表项从- a变成了- a连字符后跟 3 个空格加上连字符本身共占 4 列这正是四空格规则在输出端的体现列表项内容的起始列被对齐到第 4 列。2.2 默认关闭时的输出% pandoc -f markdown -t plain This is the title Here we fix: - a - b - c ^D期望输出This is the title Here we fix: - a - b - c用例的第二个检查点明确断言four_space_rule默认是关闭的。不加扩展开关时plain 输出保持现代 Markdown 的单空格风格输出与输入完全一致。三、扩展语义与历史背景回到 pandoc ≤ 2.0 的列表规则3.1 官方定义在 MANUAL.txt 的扩展参考章节中官方对four_space_rule的定义是Selects the pandoc 2.0 behavior for parsing lists, so that four spaces indent are needed for list item continuation paragraphs.即选择 pandoc ≤ 2.0 的列表解析行为要求列表项续段continuation paragraphs使用四空格缩进。它的作用并不只限于输出首先是一个影响解析的扩展。3.2 为什么叫规则续段缩进的歧义Markdown 中一个列表项可以包含多个块多个段落、代码块、嵌套列表等。读取器需要根据缩进判断哪些内容属于当前列表项。在 pandoc 2.0 之前规则是列表项内容的续段必须缩进 4 个空格而 pandoc 2.0 之后改为更宽松的规则通常 2 个空格即可具体取决于列表标记宽度。four_space_rule就是把这个旧规则重新启用用于兼容旧文档。3.3 默认关闭属于非默认 Markdown 扩展该扩展在 src/Text/Pandoc/Extensions.hs 中定义| Ext_four_space_rule -- ^ Require 4-space indent for list contents并出现在allMarkdownExtensions列表src/Text/Pandoc/Extensions.hs中——全部 Markdown 扩展集合但它不在pandoc 默认启用的pandocExtensions里因此默认不生效。这也正是测试用例 10812 中第二个检查点默认输出不变存在的意义用测试固化默认关闭这一契约。四、源码级实现扩展如何贯穿 reader 与 writerfour_space_rule并非只影响某一端而是同时影响 Markdown 读取器解析缩进和 Markdown 家族写入器生成缩进包含markdown、commonmark之外的plain。下面按数据流拆解。4.1 Reader 侧列表解析中的四空格判定在 src/Text/Pandoc/Readers/Markdown.hs 中三种列表解析器都会先探测该扩展是否启用得到一个布尔标志fourSpaceRule无序列表L1002-L1007bulletList do fourSpaceRule - (True $ guardEnabled Ext_four_space_rule) | return False items - fmap sequence $ many1 $ listItem fourSpaceRule bulletListStart return $ B.bulletList $ fmap compactify items有序列表L993-L995fourSpaceRule - (True $ guardEnabled Ext_four_space_rule) | return (style Example)这里有一个值得注意的特例当列表样式为Example示例列表ext_example_lists时即使未开启four_space_rulefourSpaceRule也为True——即示例列表始终按四空格规则解析。这与 MANUAL.txt 中示例列表需要四空格缩进的说明一致。定义列表L1023fourSpaceRule - (True $ guardEnabled Ext_four_space_rule) | pure False这个布尔值随后被传入listItem/rawListItemL975用于决定列表项续段至少需要多少缩进才算属于本列表项。开启扩展后4 空格缩进以内的内容不再被接纳为续段从而改变块的归属判定。4.2 Writer 侧plain/markdown 输出的缩进生成pandoc 的plainwriter 与markdownwriter 共用 src/Text/Pandoc/Writers/Markdown.hs 的实现通过envVariant区分PlainText与Markdown等变体。four_space_rule在写入端控制三处缩进① 无序列表项L819-L824Markdown | isEnabled Ext_four_space_rule opts - - T.replicate (writerTabStop opts - 2) PlainText | isEnabled Ext_four_space_rule opts - - T.replicate (writerTabStop opts - 2) _ - - 当扩展启用且writerTabStop为默认值 4 时列表项标记为- 再补4 - 2 2个空格即- ——对应测试 10812 中输出的- a。未启用时仅输出- 单空格。② 有序列表项L849-L851let ind if isEnabled Ext_four_space_rule opts then writerTabStop opts else T.length marker sps开启后续行挂起hang的缩进直接取writerTabStop默认 4 列而不是按标记宽度动态计算。③ 定义列表L877-L879n | variant Markua - 2 | isEnabled Ext_four_space_rule opts , n 2 - n | otherwise - 2同理定义列表的引导缩进在开启扩展时取tabStop4否则取 2。4.3writerTabStop缩进计算的基准值上述所有计算都依赖writerTabStop选项。它的定义与默认值位于 src/Text/Pandoc/Options.hs, writerTabStop :: Int -- ^ Tabstop for conversion btw spaces and tabs默认值为 4L400。因此四空格规则在默认配置下正好等于一个 tab stop若用户通过--tab-stop修改该值four_space_rule的缩进也会随之变化——它是跟随 tab stop 的规则而非字面写死的 4。五、关联测试同一扩展在 markdown 与定义列表上的验证four_space_rule的测试不止 10812 一处仓库中还有两个兄弟用例可以从侧面印证其行为5.1 markdown writer 下的嵌套列表test/command/7172.md% pandoc -t markdown - one - two ^D - one - two% pandoc -t markdownfour_space_rule - one - two ^D - one - two可见开启扩展后不仅顶层项变成- one嵌套子列表也整体右移并保持四空格对齐——与 10812 中 plain 输出的行为完全一致证明该逻辑在Markdown与PlainText两个变体间共享。5.2 定义列表的四空格输出test/command/11542.md该用例先用 native 格式定义了一个包含代码块的定义列表再对比默认输出与four_space_rule输出% pandoc -f native -t markdown [ DefinitionList [ ( [ Str Input ] , [ [ CodeBlock ( , [] , [] ) Term\n\n : Def ] ] ) ] ] ^D Input : Term : Def% pandoc -f native -t markdownfour_space_rule [ DefinitionList [ ( [ Str Input ] , [ [ CodeBlock ( , [] , [] ) Term\n\n : Def ] ] ) ] ] ^D Input : Term : Def同时该用例还验证了按四空格缩进书写定义列表、再读回 native能够保持 AST 一致round-trip说明 reader 与 writer 两侧的规则是对称的。六、实战建议何时开启four_space_rule结合以上实现与测试可以给出如下判断标准场景建议需要与 pandoc ≤ 2.0 时代的文档、脚本保持完全一致的列表缩进开启-t plainfour_space_rule/-t markdownfour_space_rule处理大量手工书写的旧式四空格缩进 Markdown 源文件开启-f markdownfour_space_rule输出需要被其它严格按四空格续段解析的工具消费开启 writer 侧扩展面向新文档、追求更紧凑的输出保持默认关闭使用方法与其它 pandoc 扩展一致用/-后缀在格式名上开关例如pandoc input.md -t plainfour_space_rule -o output.txt pandoc -f markdownfour_space_rule -t native input.md需要注意的是plain输出格式默认不包含该扩展必须显式写出four_space_rule才会生效——这正是 test/command/10812.md 通过两组对照用例固化的行为契约。七、版本沿革与变更记录从仓库的变更记录可以追踪该扩展的演进扩展本身在较早版本中引入用于恢复旧式解析行为changelog.md 附近有-f markdownfour_space_rule的用法说明Ext_four_space_rule构造器同期加入 src/Text/Pandoc/Extensions.hs后来补充了对plain输出的支持对应变更记录为 Support thefour_space_ruleextension forplainoutputchangelog.md发布公告中亦明确 Thefour_space_ruleextension now works forplainoutputrelease-announcements.txt另有修正 Use correct indentation whenfour_space_ruleextension is …changelog.md说明其缩进计算经历了持续打磨。命令行手册 pandoc-cli/man/pandoc.1 中也有该扩展的独立章节与 MANUAL.txt 的说明保持一致可作为查阅入口。结语four_space_rule是一个小而典型的 pandoc 扩展它同时贯穿读取器与写入器两端用一枚布尔标志统一了列表续段解析和输出缩进两套逻辑。通过 test/command/10812.md 这组对照用例可以清晰看到默认关闭 显式开启后四空格对齐的完整行为而 Markdown 读取器 与 写入器 的源码则揭示了writerTabStop在其中扮演的基准角色。无论是兼容旧文档还是生成规整的纯文本列表这个扩展都是值得掌握的一个开关。赞分享文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载相关推荐pandoc 定义列表与代码块往返转换four_space_rule 扩展的缩进语义剖析pandoc 定义列表与代码块往返转换four_space_rule 扩展的缩进语义剖析 导读 本文以仓库中的命令级测试用例 test/command/115文档开发工具CLIPandoc four_space_rule 扩展全解析从 3511 号回归测试看列表续行缩进规则的底层实现Pandoc four_space_rule 扩展全解析从 3511 号回归测试看列表续行缩进规则的底层实现 在 Pandoc 的 Markdown 解析器中文档开发工具CLIpandoc pipe_tables 扩展解析从 3734 命令测试看表格输出策略与相对列宽取舍pandoc pipe_tables 扩展解析从 3734 命令测试看表格输出策略与相对列宽取舍 本篇文章以 pandoc 仓库中的命令测试 test/com文档开发工具CLI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考