pandoc Textile 写入器 Figure 块渲染规则基于 command 测试用例的深度解析【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本文以 pandoc 仓库中的命令测试文件 figures-textile.md 为切入点完整拆解 pandoc 将 Pandoc AST 中的Figure块转换为 Textile 标记的具体规则——包括figure标签、id属性、figcaption标题段落的生成与省略逻辑并结合 Textile 写入器源码 与 命令测试框架 说明其底层实现原理。读完本文你将能理解并复现任意Figure结构在-t textile输出下的渲染结果并学会自行编写与运行 pandoc 命令测试。一、测试用例原文速览test/command/figures-textile.md是 pandoc 仓库test/command/目录下的一个命令测试command test文件全文由两个等价的代码块组成每个代码块描述一条命令 标准输入 期望输出的完整测试% pandoc -f native -t textile [Figure (fig-id,[],[]) (Caption Nothing [Para [Str Caption]]) [Para [Image (,[],[]) [] (foo.png, )]]] ^D figure idfig-id figcaption Caption /figcaption !foo.png! /figure% pandoc -f native -t textile [Figure (fig-id,[],[]) (Caption Nothing []) [Para [Image (,[],[]) [] (foo.png, )]]] ^D figure idfig-id !foo.png! /figure这两个用例分别覆盖了带标题的 Figure与无标题的 Figure两种情形是理解 pandoc Textile 写入器图片/图形渲染行为的最直接证据。下文逐一拆解其含义与实现。二、命令测试的格式约定要读懂该文件先理解 pandoc 命令测试的通用格式详见 test/Tests/Command.hs每个测试是一个 Markdown 代码块包裹块内第一行以%开头是待执行的 shell 命令例如pandoc -f native -t textile%之后的行会通过标准输入stdin传给命令直到遇到单独的^D行模拟 EOF^D之后的内容是命令的期望输出测试框架遍历test/command/目录下所有.md文件源码中通过getDirectoryContents command与.md后缀过滤逐条执行并与期望输出比对作为回归测试保障。因此第一条测试的语义是把 native 格式的 AST 描述[Figure ...]通过 stdin 喂给pandoc -f native -t textile期望它输出如下 HTML 风格的 Textile 片段figure idfig-id figcaption Caption /figcaption !foo.png! /figure第二条测试的语义相同只是输入中的Caption为空期望输出中没有figcaption块。三、Figure 块的 Textile 渲染规则源码级解析Figure是 pandoc 块级元素之一在 pandoc-types 中定义为Figure Attr Caption [Block]包含三个组成部分属性Attr含id、classes、key-value 属性、Caption含可选的ShortCaption与若干Block、以及图形主体[Block]通常是一个只包含Image的Para块。Textile 写入器对Figure的处理集中在 src/Text/Pandoc/Writers/Textile.hsblockToTextile opts (Figure attr (Caption _ caption) body) do let startTag render Nothing $ tagWithAttrs figure attr let endTag /figure let captionInlines blocksToInlines caption captionMarkup - if null captionInlines then return else (( \n\n/figcaption\n\n) . (figcaption\n\n )) $ inlineListToTextile opts (blocksToInlines caption) contents - blockListToTextile opts body return $ startTag \n\n captionMarkup contents \n\n endTag \n逐行解读这段实现开始标签tagWithAttrs figure attr将Figure的Attr如(fig-id,[],[])序列化为 HTML 属性。第一个用例中attr (fig-id,[],[])于是生成figure idfig-id。若id为空、classes 或键值属性非空它们也会按 HTML 属性语法拼入开标签。标题内联化captionInlines blocksToInlines caption把标题中的块级内容拍平为内联内容blocksToInlines定义于 src/Text/Pandoc/Shared.hs对Figure的处理是取其body再拍平。标题判空null captionInlines为真时captionMarkup为空字符串完全省略figcaption否则将标题内联内容用inlineListToTextile渲染并包裹为figcaption\n\n ... \n\n/figcaption\n\n。主体渲染contents - blockListToTextile opts body递归渲染图形主体即含图片的段落。拼接最终输出startTag \n\n captionMarkup contents \n\n endTag \n——即开标签后空一行、标题块、图片块、空一行、闭标签。3.1 用例一带标题的 Figure输入[Figure (fig-id,[],[]) (Caption Nothing [Para [Str Caption]]) [Para [Image (,[],[]) [] (foo.png, )]]]对应结构attr (fig-id,[],[])→ 开标签figure idfig-idCaption Nothing [Para [Str Caption]]→ 标题非空blocksToInlines得到[Str Caption]渲染为Caption文本包进figcaption\n\nCaption\n\n/figcaption\n\nbody [Para [Image ...]]→ 图片段落渲染为!foo.png!最终拼出测试文件中的完整输出。3.2 用例二无标题的 Figure输入[Figure (fig-id,[],[]) (Caption Nothing []) [Para [Image (,[],[]) [] (foo.png, )]]]区别仅在Caption Nothing []——标题列表为空blocksToInlines []得到空列表null captionInlines成立captionMarkup为空。因此输出中只有figure idfig-id、!foo.png!与/figurefigcaption整段被省略。这就是有标题渲染 figcaption、无标题不渲染这一规则的直接验证。四、Textile 中图片内联元素的表示两个用例输出的核心都是!foo.png!这来自 Textile 写入器对Image内联元素的渲染见 src/Text/Pandoc/Writers/Textile.hsinlineToTextile opts (Image attr(_, cls, _) alt (source, tit)) do ... return $ ! classes styles source txt !要点图片以!包裹source文件路径放在中间即!foo.png!classes非空时渲染为(class1 class2)如!(foo bar)!styles根据图片的width/height属性生成 CSS 内联样式{width:...;height:...;}showDim通过dimension读取ImageSize信息百分比或像素均可见 src/Text/Pandoc/ImageSize.hstxt优先取图片titletitle 为空时回退到alt即inlineListToTextile opts alt的渲染结果放在第二个括号中如!foo.png(Title)!。由于用例中attr (,[],[])、tit 、alt []最终恰好输出最简形式!foo.png!。五、Figure 的来源implicit_figures扩展Figure块在真实使用中通常并非手写 native AST而是由 Markdown 阅读器在启用implicit_figures扩展时自动生成。MANUAL.txt 的 Extension:implicit_figures一节对此有明确说明An image with nonempty alt text, occurring by itself in a paragraph, will be rendered as a figure with a caption. The images description will be used as the caption.即段落中单独出现、且 alt 文本非空的图片会被提升为带标题的 Figurealt 文本成为标题。例如This is the caption.会被解析为Figure标题为 This is the caption.再经 Textile 写入器输出为figurefigcaptionThis is the caption./figcaption!image.png!的形式。反过来说如果不希望图片成为 Figure只需让它不在段落中单独出现——例如在其后紧跟一个非断行空格\图片就会保持普通内联图片的渲染。这正是阅读器/写入器之间AST 中间表示 格式相关渲染设计的一个典型体现格式无关的语义结构Figure由阅读器统一产生由各格式写入器按各自语法输出。六、如何复现与扩展验证你可以在本仓库环境下直接复现这两条测试需先按 INSTALL.md 构建 pandoc或用系统安装的 pandoc 配合本仓库的测试数据# 用例一带标题的 Figure printf %s\n [Figure (fig-id,[],[]) (Caption Nothing [Para [Str Caption]]) [Para [Image (,[],[]) [] (foo.png, )]]] \ | pandoc -f native -t textile # 用例二无标题的 Figure printf %s\n [Figure (fig-id,[],[]) (Caption Nothing []) [Para [Image (,[],[]) [] (foo.png, )]]] \ | pandoc -f native -t textile也可以自行修改输入做边界探索例如给attr添加 class[Figure (,[myclass],[]) ...]观察开标签变为figure classmyclass给图片加 title[Figure ... [Para [Image (,[],[]) [] (foo.png, A title)]]]观察!foo.png!变为!foo.png(A title)!给图片加宽度[Figure ... [Para [Image (,[,width:50%],[]) [] (foo.png, )]]]观察内联样式{width:50%;}的出现。修改后的期望输出应遵循 3.1/3.2 节归纳的拼接模板figure... 空行 可选figcaption... 图片行 空行 /figure。若需将新场景固化为回归测试只需仿照 figures-textile.md 的格式在test/command/下新增.md文件第一行% pandoc -f native -t textile后续为输入^D后为期望输出运行命令测试套件即可自动纳入校验——测试框架会从test/command/目录自动发现所有.md用例。七、小结通过test/command/figures-textile.md两条测试与 Textile 写入器 源码的对照可以确认 pandoc 对Figure块转 Textile 的完整规则输入要素渲染结果Figure的Attr经tagWithAttrs渲染为figure开标签属性如id非空Caption输出figcaption\n\n标题内容\n\n/figcaption\n\n空Caption完全省略figcaption块主体中的Image渲染为!source!可含 classes、样式、title/alt整体排版figure 空行 标题可选 主体 空行 /figure这条规则链同时展示了 pandoc 命令测试.md文件驱动的黑盒回归、写入器模块化实现blockToTextile/inlineToTextile分派与implicit_figures扩展联动的工作方式是理解 pandoc 统一 AST 多格式写入器架构的一个小而完整的范例。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pandoc Textile 写入器 Figure 块渲染规则：基于 command 测试用例的深度解析
pandoc Textile 写入器 Figure 块渲染规则基于 command 测试用例的深度解析【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc导读本文以 pandoc 仓库中的命令测试文件 figures-textile.md 为切入点完整拆解 pandoc 将 Pandoc AST 中的Figure块转换为 Textile 标记的具体规则——包括figure标签、id属性、figcaption标题段落的生成与省略逻辑并结合 Textile 写入器源码 与 命令测试框架 说明其底层实现原理。读完本文你将能理解并复现任意Figure结构在-t textile输出下的渲染结果并学会自行编写与运行 pandoc 命令测试。一、测试用例原文速览test/command/figures-textile.md是 pandoc 仓库test/command/目录下的一个命令测试command test文件全文由两个等价的代码块组成每个代码块描述一条命令 标准输入 期望输出的完整测试% pandoc -f native -t textile [Figure (fig-id,[],[]) (Caption Nothing [Para [Str Caption]]) [Para [Image (,[],[]) [] (foo.png, )]]] ^D figure idfig-id figcaption Caption /figcaption !foo.png! /figure% pandoc -f native -t textile [Figure (fig-id,[],[]) (Caption Nothing []) [Para [Image (,[],[]) [] (foo.png, )]]] ^D figure idfig-id !foo.png! /figure这两个用例分别覆盖了带标题的 Figure与无标题的 Figure两种情形是理解 pandoc Textile 写入器图片/图形渲染行为的最直接证据。下文逐一拆解其含义与实现。二、命令测试的格式约定要读懂该文件先理解 pandoc 命令测试的通用格式详见 test/Tests/Command.hs每个测试是一个 Markdown 代码块包裹块内第一行以%开头是待执行的 shell 命令例如pandoc -f native -t textile%之后的行会通过标准输入stdin传给命令直到遇到单独的^D行模拟 EOF^D之后的内容是命令的期望输出测试框架遍历test/command/目录下所有.md文件源码中通过getDirectoryContents command与.md后缀过滤逐条执行并与期望输出比对作为回归测试保障。因此第一条测试的语义是把 native 格式的 AST 描述[Figure ...]通过 stdin 喂给pandoc -f native -t textile期望它输出如下 HTML 风格的 Textile 片段figure idfig-id figcaption Caption /figcaption !foo.png! /figure第二条测试的语义相同只是输入中的Caption为空期望输出中没有figcaption块。三、Figure 块的 Textile 渲染规则源码级解析Figure是 pandoc 块级元素之一在 pandoc-types 中定义为Figure Attr Caption [Block]包含三个组成部分属性Attr含id、classes、key-value 属性、Caption含可选的ShortCaption与若干Block、以及图形主体[Block]通常是一个只包含Image的Para块。Textile 写入器对Figure的处理集中在 src/Text/Pandoc/Writers/Textile.hsblockToTextile opts (Figure attr (Caption _ caption) body) do let startTag render Nothing $ tagWithAttrs figure attr let endTag /figure let captionInlines blocksToInlines caption captionMarkup - if null captionInlines then return else (( \n\n/figcaption\n\n) . (figcaption\n\n )) $ inlineListToTextile opts (blocksToInlines caption) contents - blockListToTextile opts body return $ startTag \n\n captionMarkup contents \n\n endTag \n逐行解读这段实现开始标签tagWithAttrs figure attr将Figure的Attr如(fig-id,[],[])序列化为 HTML 属性。第一个用例中attr (fig-id,[],[])于是生成figure idfig-id。若id为空、classes 或键值属性非空它们也会按 HTML 属性语法拼入开标签。标题内联化captionInlines blocksToInlines caption把标题中的块级内容拍平为内联内容blocksToInlines定义于 src/Text/Pandoc/Shared.hs对Figure的处理是取其body再拍平。标题判空null captionInlines为真时captionMarkup为空字符串完全省略figcaption否则将标题内联内容用inlineListToTextile渲染并包裹为figcaption\n\n ... \n\n/figcaption\n\n。主体渲染contents - blockListToTextile opts body递归渲染图形主体即含图片的段落。拼接最终输出startTag \n\n captionMarkup contents \n\n endTag \n——即开标签后空一行、标题块、图片块、空一行、闭标签。3.1 用例一带标题的 Figure输入[Figure (fig-id,[],[]) (Caption Nothing [Para [Str Caption]]) [Para [Image (,[],[]) [] (foo.png, )]]]对应结构attr (fig-id,[],[])→ 开标签figure idfig-idCaption Nothing [Para [Str Caption]]→ 标题非空blocksToInlines得到[Str Caption]渲染为Caption文本包进figcaption\n\nCaption\n\n/figcaption\n\nbody [Para [Image ...]]→ 图片段落渲染为!foo.png!最终拼出测试文件中的完整输出。3.2 用例二无标题的 Figure输入[Figure (fig-id,[],[]) (Caption Nothing []) [Para [Image (,[],[]) [] (foo.png, )]]]区别仅在Caption Nothing []——标题列表为空blocksToInlines []得到空列表null captionInlines成立captionMarkup为空。因此输出中只有figure idfig-id、!foo.png!与/figurefigcaption整段被省略。这就是有标题渲染 figcaption、无标题不渲染这一规则的直接验证。四、Textile 中图片内联元素的表示两个用例输出的核心都是!foo.png!这来自 Textile 写入器对Image内联元素的渲染见 src/Text/Pandoc/Writers/Textile.hsinlineToTextile opts (Image attr(_, cls, _) alt (source, tit)) do ... return $ ! classes styles source txt !要点图片以!包裹source文件路径放在中间即!foo.png!classes非空时渲染为(class1 class2)如!(foo bar)!styles根据图片的width/height属性生成 CSS 内联样式{width:...;height:...;}showDim通过dimension读取ImageSize信息百分比或像素均可见 src/Text/Pandoc/ImageSize.hstxt优先取图片titletitle 为空时回退到alt即inlineListToTextile opts alt的渲染结果放在第二个括号中如!foo.png(Title)!。由于用例中attr (,[],[])、tit 、alt []最终恰好输出最简形式!foo.png!。五、Figure 的来源implicit_figures扩展Figure块在真实使用中通常并非手写 native AST而是由 Markdown 阅读器在启用implicit_figures扩展时自动生成。MANUAL.txt 的 Extension:implicit_figures一节对此有明确说明An image with nonempty alt text, occurring by itself in a paragraph, will be rendered as a figure with a caption. The images description will be used as the caption.即段落中单独出现、且 alt 文本非空的图片会被提升为带标题的 Figurealt 文本成为标题。例如This is the caption.会被解析为Figure标题为 This is the caption.再经 Textile 写入器输出为figurefigcaptionThis is the caption./figcaption!image.png!的形式。反过来说如果不希望图片成为 Figure只需让它不在段落中单独出现——例如在其后紧跟一个非断行空格\图片就会保持普通内联图片的渲染。这正是阅读器/写入器之间AST 中间表示 格式相关渲染设计的一个典型体现格式无关的语义结构Figure由阅读器统一产生由各格式写入器按各自语法输出。六、如何复现与扩展验证你可以在本仓库环境下直接复现这两条测试需先按 INSTALL.md 构建 pandoc或用系统安装的 pandoc 配合本仓库的测试数据# 用例一带标题的 Figure printf %s\n [Figure (fig-id,[],[]) (Caption Nothing [Para [Str Caption]]) [Para [Image (,[],[]) [] (foo.png, )]]] \ | pandoc -f native -t textile # 用例二无标题的 Figure printf %s\n [Figure (fig-id,[],[]) (Caption Nothing []) [Para [Image (,[],[]) [] (foo.png, )]]] \ | pandoc -f native -t textile也可以自行修改输入做边界探索例如给attr添加 class[Figure (,[myclass],[]) ...]观察开标签变为figure classmyclass给图片加 title[Figure ... [Para [Image (,[],[]) [] (foo.png, A title)]]]观察!foo.png!变为!foo.png(A title)!给图片加宽度[Figure ... [Para [Image (,[,width:50%],[]) [] (foo.png, )]]]观察内联样式{width:50%;}的出现。修改后的期望输出应遵循 3.1/3.2 节归纳的拼接模板figure... 空行 可选figcaption... 图片行 空行 /figure。若需将新场景固化为回归测试只需仿照 figures-textile.md 的格式在test/command/下新增.md文件第一行% pandoc -f native -t textile后续为输入^D后为期望输出运行命令测试套件即可自动纳入校验——测试框架会从test/command/目录自动发现所有.md用例。七、小结通过test/command/figures-textile.md两条测试与 Textile 写入器 源码的对照可以确认 pandoc 对Figure块转 Textile 的完整规则输入要素渲染结果Figure的Attr经tagWithAttrs渲染为figure开标签属性如id非空Caption输出figcaption\n\n标题内容\n\n/figcaption\n\n空Caption完全省略figcaption块主体中的Image渲染为!source!可含 classes、样式、title/alt整体排版figure 空行 标题可选 主体 空行 /figure这条规则链同时展示了 pandoc 命令测试.md文件驱动的黑盒回归、写入器模块化实现blockToTextile/inlineToTextile分派与implicit_figures扩展联动的工作方式是理解 pandoc 统一 AST 多格式写入器架构的一个小而完整的范例。【免费下载链接】pandocUniversal markup converter项目地址: https://gitcode.com/gh_mirrors/pa/pandoc创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考