Cargo mdman 链接处理全解析Markdown 六类链接到 man 手册的转换原理与测试验证【免费下载链接】cargoThe Rust package manager项目地址: https://gitcode.com/gh_mirrors/car/cargo本篇文章以 cargo 仓库中 mdman crate 的links快照测试输入模板与 期望输出为切入点系统讲解 mdman 如何把 Markdown 中的行内链接、引用式链接、自动链接、邮箱、相对链接与未定义引用等六类链接分别渲染成 manroff、Markdown、纯文本三种格式。读完本文你将掌握 mdman 的链接解析管线、join_url基础 URL 合并规则、{{man}}/{{#options}}等 Handlebars 扩展的渲染策略以及快照测试的验证机制可以直接对照 cargo 真实的手册文档如 doc/man/cargo.md理解其生成原理。mdman 是什么cargo 的 Markdown 到 man 手册转换器mdman 是 cargo 仓库中的一个独立 crate位于 crates/mdman它的职责是把带有 Handlebars 模板语法的 Markdown 文件转换为三种输出格式分别用于不同场景Manroff格式生成etc/man/*.1这类 Unix 手册页Markdown 格式保留模板展开后的 Markdown 文档如 doc/man/cargo.mdText 格式生成纯文本手册如 doc/man/generated_txt/cargo.txt。在 crates/mdman/src/lib.rs 的convert函数中三种格式分别对应三个格式化器ManFormatter、MdFormatter、TextFormatter。转换流程分两步先用hbs::expand展开模板再把展开结果交给对应格式化器渲染。links测试就是专门为验证链接这一核心主题设计的快照测试它用一个只包含各类链接的极简文档确保 mdman 对所有链接形态的处理行为是确定、可回归的。links 快照测试一份输入三份期望输出测试位于 crates/mdman/tests/compare.rs其中test!(links)会读取tests/compare/links.md依次以 Man、Md、Text 三种格式调用mdman::convert并用 snapbox 与tests/compare/expected/links.{1,md,txt}逐字比对。测试运行时传入的关键参数见 compare.rs基础 URLhttps://example.org/用于测试相对链接的合并手册映射表ManMap(other-cmd, 1) → https://example.org/commands/other-cmd.html用于测试{{man}}的已知链接与未知链接两种分支。输入模板刻意覆盖全部链接形态输入模板 的结构非常直白——# links(1)作为第一行标题extract_section依据它解析手册章节号见 lib.rs随后是NAME、DESCRIPTION、OPTIONS三个章节输入写法links.md链接类型说明[inline link](https://example.com/inline)行内链接目标 URL 直接写在链接文本后[this is a link][bar]引用式链接定义在文档末尾[bar]: https://example.com/bar[collapsed][]折叠引用链接文本即引用名[shortcut]快捷引用省略[]后缀文本即定义名https://example.com/auto自动链接尖括号包裹的裸 URLfooexample.com邮箱链接尖括号包裹的邮箱地址relative link相对链接无协议头依赖基础 URL 合并[collapsed unknown][]未定义折叠引用无对应定义[foo][unknown]未定义引用无对应定义[shortcut unknown]未定义快捷引用无对应定义{{man other-cmd 1}}Handlebars 手册链接已知于ManMap{{man local-cmd 1}}Handlebars 手册链接未知于ManMap{{ links-include}}模板 include展开 links-include.md{{#options}}/{{#option}}选项块渲染为各格式的选项定义文档末尾还保留了三条引用定义[bar]: https://example.com/bar [collapsed]: https://example.com/collapsed [shortcut]: https://example.com/shortcut三种输出格式的渲染对照同一行输入三种格式的最终渲染结果如下分别取自 links.1、links.md、links.txt输入man 格式links.1Markdown 格式links.md纯文本格式links.txt[inline link](https://example.com/inline)\fIinline link\fR https://example.com/inline[inline link](https://example.com/inline)inline link https://example.com/inline[this is a link][bar]\fIthis is a link\fR https://example.com/bar[this is a link][bar]this is a link https://example.com/bar[collapsed][]\fIcollapsed\fR https://example.com/collapsed[collapsed][]collapsed https://example.com/collapsed[shortcut]\fIshortcut\fR https://example.com/shortcut[shortcut]shortcut https://example.com/shortcuthttps://example.com/autohttps://example.com/autohttps://example.com/autohttps://example.com/autofooexample.comfooexample.comfooexample.comfooexample.comrelative link\fIrelative link\fR https://example.org/foo/bar.htmlrelative linkrelative link https://example.org/foo/bar.html未定义引用三种保持字面文本[foo][unknown]等保持字面文本保持字面文本三个值得注意的细节相对链接只在 man / text 格式被合并进基础 URLfoo/bar.html在 man 输出中变成了https://example.org/foo/bar.html而 Markdown 格式保持(foo/bar.html)原样——因为 Markdown 输出通常用于 GitHub 等环境相对链接应保持相对。man 格式中链接文本用斜体\fI...\fR链接目标用尖括号url包裹与 roff 手册惯例一致代码inline code则用粗体\fB...\fR见 man.rs。未定义引用不会被当作链接渲染pulldown-cmark 在没有 broken-link 回调时会把它们作为普通文本输出所以三种格式都保留了[collapsed unknown][]、[foo][unknown]、[shortcut unknown]的字面形式。链接解析与 URL 合并的源码实现convert 与 md_parser 的解析管线convert是入口lib.rs先hbs::expand展开模板再把\r\n归一化为\n最后交给格式化器的render。而所有格式共用的 Markdown 解析器是md_parserlib.rs它基于pulldown_cmark::Parser::new_ext并启用了表格、脚注、删除线、智能标点四个扩展options.insert(Options::ENABLE_TABLES); options.insert(Options::ENABLE_FOOTNOTES); options.insert(Options::ENABLE_STRIKETHROUGH); options.insert(Options::ENABLE_SMART_PUNCTUATION);随后对解析事件流做了一次统一改写凡是Link起始事件邮箱链接除外其dest_url都经过join_url处理。这意味着基础 URL 合并发生在所有格式共用的解析层而非某个格式化器内部。join_url相对链接如何被合并join_url的实现lib.rs是链接处理的规则核心没有传入基础 URL 时目标原样返回有基础 URL 时若目标包含:即绝对 URL如https://...或以#开头页内锚点则保持不变否则用base_url.join(dest)合并。合并失败会直接 panic属于开发者可见的硬错误。这就是测试中relative link变成https://example.org/foo/bar.html、Some link变成https://example.org/foo.html的原因——基础 URL 是测试传入的https://example.org/。自动链接、邮箱与未定义引用的特殊处理在ManRenderer的事件循环里man.rs链接按LinkType分支处理Autolink / Email链接文本本身就是 URL 的副本直接消费掉下一个Text事件末尾统一输出urlInline / Reference / Collapsed / Shortcut先推入斜体字体栈push_font(Font::Italic)结束时弹出字体并追加urlReferenceUnknown / CollapsedUnknown / ShortcutUnknown走bail!报错分支。但正如源码注释所写该分支当前未被使用——只有设置了 broken-link 回调才会触发而 mdman 没有设置因此未定义引用以普通文本通过形成上一节的字面输出Imagebail!(images are not currently supported)mdman 明确不支持图片。man 输出还包含完整的 roff 控制序列.TH LINKS 1标题、.nh关闭断字、.ad l左对齐、.ss \n[.ss] 0关闭句间距见 man.rs文本转义则统一经过escape函数man.rs它把-转成\-、--保持、行首.前加\并维护一张 Unicode 字符如破折号、引号、省略号到 roff 序列的翻译表遇到表外字符直接报错。Handlebars 扩展man 链接、选项块与 include模板展开层hbs.rshbs::expandhbs.rs做了四件事开启 Handlebars 严格模式set_strict_mode(true)模板中引用不存在的变量会直接报错注册四个 helperlower、{{#options}}、{{#option}}、{{man}}以及{{*set}}装饰器把文档同目录下的includes/注册为模板目录tpl_extension .md这是{{ links-include}}能展开的原因以源文件名去除扩展名作为man_name注入上下文links.md即得到links供选项块生成锚点 ID 使用。{{man name section}}已知与未知链接的分流ManLinkHelperhbs.rs要求恰好两个参数名称 章节号章节号必须是u8整数然后委托给格式化器的linkify_man_to_mdMan 格式man.rs输出name(section)最终渲染成粗体\fBother\-cmd\fR(1)Markdown 格式md.rs先查ManMap命中则输出[other-cmd(1)](https://example.org/commands/other-cmd.html)未命中则退化为相对链接local-cmd(1)。这正是测试同时写了other-cmd与local-cmd两个用例的原因——分别覆盖映射命中与未命中两条路径。{{#options}} / {{#option}}选项定义块的格式适配选项块是 cargo 手册模板的常用结构。OptionsHelper与OptionHelperhbs.rs强制约束{{#options}}不可嵌套{{#option}}必须位于{{#options}}内option 参数必须是非空字符串block 不能为空渲染前统一把\r\n归一化为\nWindows 换行可能破坏某些格式的输出。各格式的渲染结果差异显著Man 格式render_options_start/end返回![CDATA[/]]标记让 pulldown-cmark 忽略这段内容见 man.rsrender_option把参数与内容拼成.sp\fB...\fR.RS 4/.RE缩进块见 man.rs。对应输出.sp \fB\-\-foo\-bar\fR .RS 4 Example \fIlink\fR https://example.org/bar.html\. See \fBother\-cmd\fR(1), \fBlocal\-cmd\fR(1) .REMarkdown 格式输出 HTMLdl定义列表dt的id由man_name与选项首词拼接而成——--foo-bar得到option-links---foo-bar见 md.rs这也是锚点跳转的依据dt classoption-term idoption-links---foo-bara classoption-anchor href#option-links---foo-barcode--foo-bar/code/a/dt dd classoption-descpExample a hrefbar.htmllink/a. See a hrefhttps://example.org/commands/other-cmd.htmlother-cmd(1)/a, a hreflocal-cmd.htmllocal-cmd(1)/a/p /dd纯文本格式选项名顶格、说明缩进 11 个空格如 links.txt 中的--foo-bar段落。include 展开带来的嵌套选项块links-include.md 内部又含一个{{#options}}块--include选项。它在 DESCRIPTION 章节展开后Man 输出为\fB\-\-include\fR.RS 4/.RE块Markdown 输出为带idoption-links---include的dl。这说明 include 与选项块可以自由组合且man_name始终来自外层文档文件名保证锚点 ID 全局唯一。测试如何运行与验证运行测试只需cargo test -p mdmancompare.rs 中run()的验证逻辑见 compare.rs读取tests/compare/{name}.md作为输入构造https://example.org/基础 URL 与包含other-cmd的ManMap对 Man、Md、Text 三种格式分别调用extract_sectionconvert用snapbox::assert_data_eq!与tests/compare/expected/{name}.{ext}逐字比对任何输出变化都会导致测试失败。同一套run还服务formatting、options、tables、vars四个用例见 compare.rs形成对 mdman 渲染行为的全面回归保障。links用例的价值在于它把链接这一最容易出错的转换主题固化为最小可复现样本任何对join_url、字体栈、URL 转义的改动都能立即暴露。在 cargo 文档体系中的实际应用mdman 并非玩具工具cargo 自身的手册全部由它生成模板源doc/man/*.md例如 doc/man/cargo.md 就是 cargo 主命令的手册模板其中大量使用{{man cargo-xxx 1}}与{{#options}}生成产物roff 手册页etc/man/*.1如 etc/man/cargo.1与纯文本手册doc/man/generated_txt/*.txt如 doc/man/generated_txt/cargo.txt工具文档mdman 自身的说明见 crates/mdman/doc/mdman.md。当你看到 cargo 手册里cargo(1)与cargo-build(1)之间互链、--manifest-path等选项锚点、以及相对链接在网页与终端中表现各异时背后的机制正是本文所述的join_url合并规则、{{man}}的 ManMap 分流与{{#option}}的三种格式渲染策略。links测试用例则是理解这套机制最快的入口一份最小输入、三种期望输出把链接转换的所有边界情况一网打尽。【免费下载链接】cargoThe Rust package manager项目地址: https://gitcode.com/gh_mirrors/car/cargo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Cargo mdman 链接处理全解析：Markdown 六类链接到 man 手册的转换原理与测试验证
Cargo mdman 链接处理全解析Markdown 六类链接到 man 手册的转换原理与测试验证【免费下载链接】cargoThe Rust package manager项目地址: https://gitcode.com/gh_mirrors/car/cargo本篇文章以 cargo 仓库中 mdman crate 的links快照测试输入模板与 期望输出为切入点系统讲解 mdman 如何把 Markdown 中的行内链接、引用式链接、自动链接、邮箱、相对链接与未定义引用等六类链接分别渲染成 manroff、Markdown、纯文本三种格式。读完本文你将掌握 mdman 的链接解析管线、join_url基础 URL 合并规则、{{man}}/{{#options}}等 Handlebars 扩展的渲染策略以及快照测试的验证机制可以直接对照 cargo 真实的手册文档如 doc/man/cargo.md理解其生成原理。mdman 是什么cargo 的 Markdown 到 man 手册转换器mdman 是 cargo 仓库中的一个独立 crate位于 crates/mdman它的职责是把带有 Handlebars 模板语法的 Markdown 文件转换为三种输出格式分别用于不同场景Manroff格式生成etc/man/*.1这类 Unix 手册页Markdown 格式保留模板展开后的 Markdown 文档如 doc/man/cargo.mdText 格式生成纯文本手册如 doc/man/generated_txt/cargo.txt。在 crates/mdman/src/lib.rs 的convert函数中三种格式分别对应三个格式化器ManFormatter、MdFormatter、TextFormatter。转换流程分两步先用hbs::expand展开模板再把展开结果交给对应格式化器渲染。links测试就是专门为验证链接这一核心主题设计的快照测试它用一个只包含各类链接的极简文档确保 mdman 对所有链接形态的处理行为是确定、可回归的。links 快照测试一份输入三份期望输出测试位于 crates/mdman/tests/compare.rs其中test!(links)会读取tests/compare/links.md依次以 Man、Md、Text 三种格式调用mdman::convert并用 snapbox 与tests/compare/expected/links.{1,md,txt}逐字比对。测试运行时传入的关键参数见 compare.rs基础 URLhttps://example.org/用于测试相对链接的合并手册映射表ManMap(other-cmd, 1) → https://example.org/commands/other-cmd.html用于测试{{man}}的已知链接与未知链接两种分支。输入模板刻意覆盖全部链接形态输入模板 的结构非常直白——# links(1)作为第一行标题extract_section依据它解析手册章节号见 lib.rs随后是NAME、DESCRIPTION、OPTIONS三个章节输入写法links.md链接类型说明[inline link](https://example.com/inline)行内链接目标 URL 直接写在链接文本后[this is a link][bar]引用式链接定义在文档末尾[bar]: https://example.com/bar[collapsed][]折叠引用链接文本即引用名[shortcut]快捷引用省略[]后缀文本即定义名https://example.com/auto自动链接尖括号包裹的裸 URLfooexample.com邮箱链接尖括号包裹的邮箱地址relative link相对链接无协议头依赖基础 URL 合并[collapsed unknown][]未定义折叠引用无对应定义[foo][unknown]未定义引用无对应定义[shortcut unknown]未定义快捷引用无对应定义{{man other-cmd 1}}Handlebars 手册链接已知于ManMap{{man local-cmd 1}}Handlebars 手册链接未知于ManMap{{ links-include}}模板 include展开 links-include.md{{#options}}/{{#option}}选项块渲染为各格式的选项定义文档末尾还保留了三条引用定义[bar]: https://example.com/bar [collapsed]: https://example.com/collapsed [shortcut]: https://example.com/shortcut三种输出格式的渲染对照同一行输入三种格式的最终渲染结果如下分别取自 links.1、links.md、links.txt输入man 格式links.1Markdown 格式links.md纯文本格式links.txt[inline link](https://example.com/inline)\fIinline link\fR https://example.com/inline[inline link](https://example.com/inline)inline link https://example.com/inline[this is a link][bar]\fIthis is a link\fR https://example.com/bar[this is a link][bar]this is a link https://example.com/bar[collapsed][]\fIcollapsed\fR https://example.com/collapsed[collapsed][]collapsed https://example.com/collapsed[shortcut]\fIshortcut\fR https://example.com/shortcut[shortcut]shortcut https://example.com/shortcuthttps://example.com/autohttps://example.com/autohttps://example.com/autohttps://example.com/autofooexample.comfooexample.comfooexample.comfooexample.comrelative link\fIrelative link\fR https://example.org/foo/bar.htmlrelative linkrelative link https://example.org/foo/bar.html未定义引用三种保持字面文本[foo][unknown]等保持字面文本保持字面文本三个值得注意的细节相对链接只在 man / text 格式被合并进基础 URLfoo/bar.html在 man 输出中变成了https://example.org/foo/bar.html而 Markdown 格式保持(foo/bar.html)原样——因为 Markdown 输出通常用于 GitHub 等环境相对链接应保持相对。man 格式中链接文本用斜体\fI...\fR链接目标用尖括号url包裹与 roff 手册惯例一致代码inline code则用粗体\fB...\fR见 man.rs。未定义引用不会被当作链接渲染pulldown-cmark 在没有 broken-link 回调时会把它们作为普通文本输出所以三种格式都保留了[collapsed unknown][]、[foo][unknown]、[shortcut unknown]的字面形式。链接解析与 URL 合并的源码实现convert 与 md_parser 的解析管线convert是入口lib.rs先hbs::expand展开模板再把\r\n归一化为\n最后交给格式化器的render。而所有格式共用的 Markdown 解析器是md_parserlib.rs它基于pulldown_cmark::Parser::new_ext并启用了表格、脚注、删除线、智能标点四个扩展options.insert(Options::ENABLE_TABLES); options.insert(Options::ENABLE_FOOTNOTES); options.insert(Options::ENABLE_STRIKETHROUGH); options.insert(Options::ENABLE_SMART_PUNCTUATION);随后对解析事件流做了一次统一改写凡是Link起始事件邮箱链接除外其dest_url都经过join_url处理。这意味着基础 URL 合并发生在所有格式共用的解析层而非某个格式化器内部。join_url相对链接如何被合并join_url的实现lib.rs是链接处理的规则核心没有传入基础 URL 时目标原样返回有基础 URL 时若目标包含:即绝对 URL如https://...或以#开头页内锚点则保持不变否则用base_url.join(dest)合并。合并失败会直接 panic属于开发者可见的硬错误。这就是测试中relative link变成https://example.org/foo/bar.html、Some link变成https://example.org/foo.html的原因——基础 URL 是测试传入的https://example.org/。自动链接、邮箱与未定义引用的特殊处理在ManRenderer的事件循环里man.rs链接按LinkType分支处理Autolink / Email链接文本本身就是 URL 的副本直接消费掉下一个Text事件末尾统一输出urlInline / Reference / Collapsed / Shortcut先推入斜体字体栈push_font(Font::Italic)结束时弹出字体并追加urlReferenceUnknown / CollapsedUnknown / ShortcutUnknown走bail!报错分支。但正如源码注释所写该分支当前未被使用——只有设置了 broken-link 回调才会触发而 mdman 没有设置因此未定义引用以普通文本通过形成上一节的字面输出Imagebail!(images are not currently supported)mdman 明确不支持图片。man 输出还包含完整的 roff 控制序列.TH LINKS 1标题、.nh关闭断字、.ad l左对齐、.ss \n[.ss] 0关闭句间距见 man.rs文本转义则统一经过escape函数man.rs它把-转成\-、--保持、行首.前加\并维护一张 Unicode 字符如破折号、引号、省略号到 roff 序列的翻译表遇到表外字符直接报错。Handlebars 扩展man 链接、选项块与 include模板展开层hbs.rshbs::expandhbs.rs做了四件事开启 Handlebars 严格模式set_strict_mode(true)模板中引用不存在的变量会直接报错注册四个 helperlower、{{#options}}、{{#option}}、{{man}}以及{{*set}}装饰器把文档同目录下的includes/注册为模板目录tpl_extension .md这是{{ links-include}}能展开的原因以源文件名去除扩展名作为man_name注入上下文links.md即得到links供选项块生成锚点 ID 使用。{{man name section}}已知与未知链接的分流ManLinkHelperhbs.rs要求恰好两个参数名称 章节号章节号必须是u8整数然后委托给格式化器的linkify_man_to_mdMan 格式man.rs输出name(section)最终渲染成粗体\fBother\-cmd\fR(1)Markdown 格式md.rs先查ManMap命中则输出[other-cmd(1)](https://example.org/commands/other-cmd.html)未命中则退化为相对链接local-cmd(1)。这正是测试同时写了other-cmd与local-cmd两个用例的原因——分别覆盖映射命中与未命中两条路径。{{#options}} / {{#option}}选项定义块的格式适配选项块是 cargo 手册模板的常用结构。OptionsHelper与OptionHelperhbs.rs强制约束{{#options}}不可嵌套{{#option}}必须位于{{#options}}内option 参数必须是非空字符串block 不能为空渲染前统一把\r\n归一化为\nWindows 换行可能破坏某些格式的输出。各格式的渲染结果差异显著Man 格式render_options_start/end返回![CDATA[/]]标记让 pulldown-cmark 忽略这段内容见 man.rsrender_option把参数与内容拼成.sp\fB...\fR.RS 4/.RE缩进块见 man.rs。对应输出.sp \fB\-\-foo\-bar\fR .RS 4 Example \fIlink\fR https://example.org/bar.html\. See \fBother\-cmd\fR(1), \fBlocal\-cmd\fR(1) .REMarkdown 格式输出 HTMLdl定义列表dt的id由man_name与选项首词拼接而成——--foo-bar得到option-links---foo-bar见 md.rs这也是锚点跳转的依据dt classoption-term idoption-links---foo-bara classoption-anchor href#option-links---foo-barcode--foo-bar/code/a/dt dd classoption-descpExample a hrefbar.htmllink/a. See a hrefhttps://example.org/commands/other-cmd.htmlother-cmd(1)/a, a hreflocal-cmd.htmllocal-cmd(1)/a/p /dd纯文本格式选项名顶格、说明缩进 11 个空格如 links.txt 中的--foo-bar段落。include 展开带来的嵌套选项块links-include.md 内部又含一个{{#options}}块--include选项。它在 DESCRIPTION 章节展开后Man 输出为\fB\-\-include\fR.RS 4/.RE块Markdown 输出为带idoption-links---include的dl。这说明 include 与选项块可以自由组合且man_name始终来自外层文档文件名保证锚点 ID 全局唯一。测试如何运行与验证运行测试只需cargo test -p mdmancompare.rs 中run()的验证逻辑见 compare.rs读取tests/compare/{name}.md作为输入构造https://example.org/基础 URL 与包含other-cmd的ManMap对 Man、Md、Text 三种格式分别调用extract_sectionconvert用snapbox::assert_data_eq!与tests/compare/expected/{name}.{ext}逐字比对任何输出变化都会导致测试失败。同一套run还服务formatting、options、tables、vars四个用例见 compare.rs形成对 mdman 渲染行为的全面回归保障。links用例的价值在于它把链接这一最容易出错的转换主题固化为最小可复现样本任何对join_url、字体栈、URL 转义的改动都能立即暴露。在 cargo 文档体系中的实际应用mdman 并非玩具工具cargo 自身的手册全部由它生成模板源doc/man/*.md例如 doc/man/cargo.md 就是 cargo 主命令的手册模板其中大量使用{{man cargo-xxx 1}}与{{#options}}生成产物roff 手册页etc/man/*.1如 etc/man/cargo.1与纯文本手册doc/man/generated_txt/*.txt如 doc/man/generated_txt/cargo.txt工具文档mdman 自身的说明见 crates/mdman/doc/mdman.md。当你看到 cargo 手册里cargo(1)与cargo-build(1)之间互链、--manifest-path等选项锚点、以及相对链接在网页与终端中表现各异时背后的机制正是本文所述的join_url合并规则、{{man}}的 ManMap 分流与{{#option}}的三种格式渲染策略。links测试用例则是理解这套机制最快的入口一份最小输入、三种期望输出把链接转换的所有边界情况一网打尽。【免费下载链接】cargoThe Rust package manager项目地址: https://gitcode.com/gh_mirrors/car/cargo创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考