文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载导读本文以 pandoc 仓库中的命令行测试用例 test/command/4420.md 为切入点深入讲解 pandoc 的 RSTreStructuredText写入器将带align-right类与固定宽度属性的内联图片转换为 RST 图片替换引用substitution reference语法的完整机制。读完本文你将掌握 pandoc 从 Native AST 输入到 RST 输出的图片转换规则、替换引用标签的生成与复用逻辑以及:width:、:align:、:target:等 RST 图片指令选项在源码中的对应实现。一、测试用例全景一份可复现的最小实验test/command/4420.md 是 pandoc 测试套件test/command目录下的 golden 命令测试中的一个典型用例它通过% pandoc ...前缀声明要执行的命令行随后给出输入与期望输出% pandoc -f native -t rst [Para [Image (,[align-right],[(width,100px)]) [Str image] (foo.png,fig:test)]] ^D |image| .. |image| image:: foo.png :width: 100px输入一条% pandoc -f native -t rst命令从标准输入读取一段 Nativepandoc 内部 AST 的文本表示以^D结束。Native 输入的含义Para段落中包含一个Image其Attr为(, [align-right], [(width,100px)])——即空标识符id、align-right样式类、以及键值对width100px图片的替代文本alt text为Str image目标target为(foo.png, fig:test)其中foo.png是图片路径fig:test是标题。期望输出正文中只有一行|image|替换引用随后是 RST 的替换定义指令.. |image| image:: foo.png以及缩进对齐的选项:width: 100px。注意两个细节fig:test标题没有被输出RST 替换引用不承载 titlealign-right类也没有生成:align:选项。这正是接下来要解释的实现行为。二、图片转换的主流程从 Inline 到替换引用RST 写入器位于 src/Text/Pandoc/Writers/RST.hs。当遇到内联图片时写入器并不像 HTML/LaTeX 写入器那样直接输出img或\includegraphics而是采用 RST 的替换引用substitution reference机制正文位置仅输出|label|形式的引用在文档末尾统一输出.. |label| image:: path的替换定义。这一设计的好处是RST 的替换定义可以复用——同一张图多次出现时只需在正文中重复引用同一个标签。相关的两个入口在 inlineToRST普通图片inlineToRST (Image attr alternate (source, tit))第 875 行调用registerImage登记图片并拿到标签返回| label |。链接包裹的图片Link _ [Image ...] ...第 857 行额外把链接地址作为mbtargettarget传入使 RST 输出带:target:选项的可点击图片。三、registerImage标签的生成与去重复用registerImage 负责为每张图片分配替换引用标签其逻辑清晰且值得细读标签优先取自替代文本若替代文本alt非空null alt || alt [Str ]不成立直接以替代文本作为标签例如本文用例中的image。空替代文本自动编号若alt为空则用状态中的计数器stImageId生成image1、image2这类递增标签见getImageName第 889-891 行。同图去重lookup alt pics会先查状态stImages列表若已登记过完全相同属性、源路径、标题、target 均一致的图片则复用已有标签避免文档中出现重复的替换定义若替代文本相同但属性不同则改用编号标签区分。登记入状态新图片会被追加进stImages :: [([Inline], (Attr, Text, Text, Maybe Text))]第 48 行供文档末尾统一输出。每个RST状态实例的初始stImageId 1第 64 行因此在同一文档中编号标签从image1开始。四、替换定义输出pictToRST与选项映射文档末尾写入器从状态中取出全部已登记图片reverse . stImages第 86 行由 pictRefsToRST 逐条交给 pictToRST 生成替换定义.. |image| image:: foo.png :width: 100px关键行为第 152-170 行image::指令格式为.. |label| image:: src。imageDimsToRST输出尺寸第 912-926 行属性中的键值对width100px被解析为Percent/像素等维度输出:width: 100px高度:height:同理。宽度为百分比时输出:width: NN%而高度的百分比会被忽略Height - empty第 922 行只有:name:来自 attr 的 id会按需输出。类的映射规则第 157-165 行这是本用例输出中看不到align-right的原因——源码对align-top、align-middle、align-bottom分别映射为:align: top|middle|bottom而align-center、align-right、align-left均映射为空即 RST 的图片替换引用不支持左右/居中对其选项写入器选择直接丢弃其余未知类则回退输出:class: ...。target 可选输出第 168-170 行仅当图片被链接包裹时mbtarget为Just t才输出:target: t本用例的fig:test是图片标题而非链接目标故不产生该行。这也是测试文件 test/command/4420.md 期望输出中:width: 100px存在、而 align 与 title 均未出现的原因。五、对比独立图片Figure走不同的输出路径需要区分的是上述替换引用机制只用于内联图片Inline中的Image。当图片作为独立块block-level figure出现时写入器在 blockToRST (Figure ...) 中走完全不同的路径输出.. figure:: path指令并支持:alt:、:name:、:align: right|left|center这里align-right会被映射为:align: right与内联图片的处理相反、:figclass:以及尺寸选项替代文本缺失时退而使用图片标题tit作为 alt第 402-405 行。也就是说图片是否作为段落中的内联元素出现直接决定了 RST 输出采用替换引用还是figure::块指令这是阅读 src/Text/Pandoc/Writers/RST.hs 时最容易混淆的分叉点。六、动手验证在本地复现该测试test/command目录下的*.md文件本身就是可执行的 golden 测试。手动复现 test/command/4420.md 的最简方式# 1. 在仓库根目录构建 pandoc需 GHC/cabal详见 INSTALL.md cabal build pandoc-cli # 2. 用 cabal exec 复现用例中的命令 cabal exec -- pandoc -f native -t rst EOF [Para [Image (,[align-right],[(width,100px)]) [Str image] (foo.png,fig:test)]] EOF输出应当与测试期望一致|image| .. |image| image:: foo.png :width: 100px也可以替换输入做交叉验证例如去掉align-right类并把width改为50%观察:width: 50%的输出或在 Native 中把图片包进Link观察:target:选项的生成——这些行为都能在上文对应的源码分支中找到依据。七、小结test/command/4420.md 虽然只有短短 9 行却完整覆盖了 pandoc RST 写入器图片处理的三个核心设计替换引用机制正文只输出|label|定义统一收尾属性映射策略width/height走:width:/:height:align-*类按 RST 能力选择性映射或丢弃链接目标映射为:target:标签生命周期优先复用替代文本、同名同属性去重、空 alt 自动编号。理解这份测试等于同时读懂了 src/Text/Pandoc/Writers/RST.hs 中registerImage、pictToRST、imageDimsToRST三个关键函数也就能准确预判任何一张带属性的图片经-t rst转换后的输出形态。赞分享文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载相关推荐Pandoc RST 输出中的图片替换引用Substitution Reference机制解析以 test/command/6194.md 为例Pandoc RST 输出中的图片替换引用Substitution Reference机制解析以 test/command/6194.md 为例 导读 本文档开发工具CLIPDF Arranger图像导入教程如何将图片转换为PDF文档PDF Arranger图像导入教程如何将图片转换为PDF文档 想要将多张图片快速转换为一个整洁的PDF文档吗PDF Arranger为您提供了一个简单高效桌面应用开源AI数字人Duix.Avatar本地克隆与离线视频生成完整指南开源AI数字人Duix.Avatar本地克隆与离线视频生成完整指南 Duix.Avatar是Duix.com出品的免费开源AI数字人工具包装在自己的电脑上就文档开发工具CLI上一篇Lawnicons与Lawnchair的完美结合提升用户体验的终极方案下一篇Soul 开源项目实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 pandoc 源码解析：RST 写入器如何将带属性图片转换为 reStructuredText 图片替换引用
文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载导读本文以 pandoc 仓库中的命令行测试用例 test/command/4420.md 为切入点深入讲解 pandoc 的 RSTreStructuredText写入器将带align-right类与固定宽度属性的内联图片转换为 RST 图片替换引用substitution reference语法的完整机制。读完本文你将掌握 pandoc 从 Native AST 输入到 RST 输出的图片转换规则、替换引用标签的生成与复用逻辑以及:width:、:align:、:target:等 RST 图片指令选项在源码中的对应实现。一、测试用例全景一份可复现的最小实验test/command/4420.md 是 pandoc 测试套件test/command目录下的 golden 命令测试中的一个典型用例它通过% pandoc ...前缀声明要执行的命令行随后给出输入与期望输出% pandoc -f native -t rst [Para [Image (,[align-right],[(width,100px)]) [Str image] (foo.png,fig:test)]] ^D |image| .. |image| image:: foo.png :width: 100px输入一条% pandoc -f native -t rst命令从标准输入读取一段 Nativepandoc 内部 AST 的文本表示以^D结束。Native 输入的含义Para段落中包含一个Image其Attr为(, [align-right], [(width,100px)])——即空标识符id、align-right样式类、以及键值对width100px图片的替代文本alt text为Str image目标target为(foo.png, fig:test)其中foo.png是图片路径fig:test是标题。期望输出正文中只有一行|image|替换引用随后是 RST 的替换定义指令.. |image| image:: foo.png以及缩进对齐的选项:width: 100px。注意两个细节fig:test标题没有被输出RST 替换引用不承载 titlealign-right类也没有生成:align:选项。这正是接下来要解释的实现行为。二、图片转换的主流程从 Inline 到替换引用RST 写入器位于 src/Text/Pandoc/Writers/RST.hs。当遇到内联图片时写入器并不像 HTML/LaTeX 写入器那样直接输出img或\includegraphics而是采用 RST 的替换引用substitution reference机制正文位置仅输出|label|形式的引用在文档末尾统一输出.. |label| image:: path的替换定义。这一设计的好处是RST 的替换定义可以复用——同一张图多次出现时只需在正文中重复引用同一个标签。相关的两个入口在 inlineToRST普通图片inlineToRST (Image attr alternate (source, tit))第 875 行调用registerImage登记图片并拿到标签返回| label |。链接包裹的图片Link _ [Image ...] ...第 857 行额外把链接地址作为mbtargettarget传入使 RST 输出带:target:选项的可点击图片。三、registerImage标签的生成与去重复用registerImage 负责为每张图片分配替换引用标签其逻辑清晰且值得细读标签优先取自替代文本若替代文本alt非空null alt || alt [Str ]不成立直接以替代文本作为标签例如本文用例中的image。空替代文本自动编号若alt为空则用状态中的计数器stImageId生成image1、image2这类递增标签见getImageName第 889-891 行。同图去重lookup alt pics会先查状态stImages列表若已登记过完全相同属性、源路径、标题、target 均一致的图片则复用已有标签避免文档中出现重复的替换定义若替代文本相同但属性不同则改用编号标签区分。登记入状态新图片会被追加进stImages :: [([Inline], (Attr, Text, Text, Maybe Text))]第 48 行供文档末尾统一输出。每个RST状态实例的初始stImageId 1第 64 行因此在同一文档中编号标签从image1开始。四、替换定义输出pictToRST与选项映射文档末尾写入器从状态中取出全部已登记图片reverse . stImages第 86 行由 pictRefsToRST 逐条交给 pictToRST 生成替换定义.. |image| image:: foo.png :width: 100px关键行为第 152-170 行image::指令格式为.. |label| image:: src。imageDimsToRST输出尺寸第 912-926 行属性中的键值对width100px被解析为Percent/像素等维度输出:width: 100px高度:height:同理。宽度为百分比时输出:width: NN%而高度的百分比会被忽略Height - empty第 922 行只有:name:来自 attr 的 id会按需输出。类的映射规则第 157-165 行这是本用例输出中看不到align-right的原因——源码对align-top、align-middle、align-bottom分别映射为:align: top|middle|bottom而align-center、align-right、align-left均映射为空即 RST 的图片替换引用不支持左右/居中对其选项写入器选择直接丢弃其余未知类则回退输出:class: ...。target 可选输出第 168-170 行仅当图片被链接包裹时mbtarget为Just t才输出:target: t本用例的fig:test是图片标题而非链接目标故不产生该行。这也是测试文件 test/command/4420.md 期望输出中:width: 100px存在、而 align 与 title 均未出现的原因。五、对比独立图片Figure走不同的输出路径需要区分的是上述替换引用机制只用于内联图片Inline中的Image。当图片作为独立块block-level figure出现时写入器在 blockToRST (Figure ...) 中走完全不同的路径输出.. figure:: path指令并支持:alt:、:name:、:align: right|left|center这里align-right会被映射为:align: right与内联图片的处理相反、:figclass:以及尺寸选项替代文本缺失时退而使用图片标题tit作为 alt第 402-405 行。也就是说图片是否作为段落中的内联元素出现直接决定了 RST 输出采用替换引用还是figure::块指令这是阅读 src/Text/Pandoc/Writers/RST.hs 时最容易混淆的分叉点。六、动手验证在本地复现该测试test/command目录下的*.md文件本身就是可执行的 golden 测试。手动复现 test/command/4420.md 的最简方式# 1. 在仓库根目录构建 pandoc需 GHC/cabal详见 INSTALL.md cabal build pandoc-cli # 2. 用 cabal exec 复现用例中的命令 cabal exec -- pandoc -f native -t rst EOF [Para [Image (,[align-right],[(width,100px)]) [Str image] (foo.png,fig:test)]] EOF输出应当与测试期望一致|image| .. |image| image:: foo.png :width: 100px也可以替换输入做交叉验证例如去掉align-right类并把width改为50%观察:width: 50%的输出或在 Native 中把图片包进Link观察:target:选项的生成——这些行为都能在上文对应的源码分支中找到依据。七、小结test/command/4420.md 虽然只有短短 9 行却完整覆盖了 pandoc RST 写入器图片处理的三个核心设计替换引用机制正文只输出|label|定义统一收尾属性映射策略width/height走:width:/:height:align-*类按 RST 能力选择性映射或丢弃链接目标映射为:target:标签生命周期优先复用替代文本、同名同属性去重、空 alt 自动编号。理解这份测试等于同时读懂了 src/Text/Pandoc/Writers/RST.hs 中registerImage、pictToRST、imageDimsToRST三个关键函数也就能准确预判任何一张带属性的图片经-t rst转换后的输出形态。赞分享文档开发工具CLI【免费下载链接】pandocUniversal markup converter项目地址https://gitcode.com/gh_mirrors/pa/pandoc点击查看免费下载相关推荐Pandoc RST 输出中的图片替换引用Substitution Reference机制解析以 test/command/6194.md 为例Pandoc RST 输出中的图片替换引用Substitution Reference机制解析以 test/command/6194.md 为例 导读 本文档开发工具CLIPDF Arranger图像导入教程如何将图片转换为PDF文档PDF Arranger图像导入教程如何将图片转换为PDF文档 想要将多张图片快速转换为一个整洁的PDF文档吗PDF Arranger为您提供了一个简单高效桌面应用开源AI数字人Duix.Avatar本地克隆与离线视频生成完整指南开源AI数字人Duix.Avatar本地克隆与离线视频生成完整指南 Duix.Avatar是Duix.com出品的免费开源AI数字人工具包装在自己的电脑上就文档开发工具CLI上一篇Lawnicons与Lawnchair的完美结合提升用户体验的终极方案下一篇Soul 开源项目实战指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考