curl 手册页生成器 managen 完全指南从选项文档到 curl.1 的自动化流水线【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl导读managen是 curl 项目内置的手册页man page生成器它把docs/cmdline-opts目录下一份份独立、接近 Markdown 语法的选项文档自动渲染成完整的 nroff 格式curl.1手册、纯文本版curl.txt以及curl --help的 C 源码。本文以 docs/cmdline-opts/MANPAGE.md 为骨架结合 scripts/managen 的 Perl 实现与 docs/cmdline-opts/mainpage.idx 等仓库文件讲清楚选项文档的元数据格式、正文语法、三个内置变量、五种输出模式以及如何手动重生成 curl 手册页。读完你既能看懂 curl 每个--option的手册条目是如何诞生的也能在自己的文档工程里复刻这套单文件写作、统一渲染的流程。一、managen 是什么一套文档即源码的手册页流水线curl 的手册页不是手工维护的单一 nroff 文件而是由生成器managen从一组结构化源文件动态产出的。这套设计把写文档与排版彻底解耦每个命令行选项有一份独立源文件如-v, --verbose对应 docs/cmdline-opts/verbose.md作者只需用接近 Markdown 的语法描述该选项渲染时managen统一读取 docs/cmdline-opts/mainpage.idx 定义的渲染顺序逐文件生成 nroffroff 排版指令输出其中%options是一个特殊关键字位于索引文件中它指示生成器把所有命令行选项文档按长选项名排序后一次性插入从而自动拼出完整的OPTIONS章节。也就是说新增一个 curl 命令行选项的标准动作是往docs/cmdline-opts/放一个.md文件并写清元数据其余排版工作全部交给managen。二、源文件组织mainpage.idx 与 %options2.1 索引文件决定全局顺序mainpage.idx 是一个纯文本索引每一行点名一个要渲染的.md文件#开头的行为注释。当前仓库中它的实际内容节选展示了手册页的章节骨架_NAME.md _SYNOPSIS.md _DESCRIPTION.md _URL.md _GLOBBING.md _VARIABLES.md _OUTPUT.md _PROTOCOLS.md _PROGRESS.md _VERSION.md _OPTIONS.md %options _FILES.md _ENVIRONMENT.md _PROXYPREFIX.md _EXITCODES.md _BUGS.md _AUTHORS.md _WWW.md _SEEALSO.md可以看到以_开头的文件是手册的顶层章节名称、概要、描述、URL 语法、通配、变量、输出、协议、进度、版本等而%options恰好被放在_OPTIONS.md之后保证所有选项说明连续出现在手册的 OPTIONS 区域。2.2 %options 的插入逻辑从 scripts/managen 的mainpage子程序可以看到生成器逐行读取mainpage.idx凡遇到%options行就对调用者传入的选项文件列表按去掉.md后缀后的名称做字典序排序sortnames再逐个调用single子程序渲染if(/^%options/) { # output docs for all options foreach my $f (sort sortnames files) { $ret single($dir, $manpage, $f, 0); } }也就是说无论索引文件怎么写%options展开出来的选项条目顺序始终是按长选项名稳定排序的这保证了不同版本手册页之间选项排列的可预期性。三、选项文件格式元数据 正文3.1 文件命名MANPAGE.md 指出每个选项的文档文件按long name命名、不带前缀破折号。需要留意的是文档正文以.d后缀做示意如verbose.d而当前仓库中实际的源文件统一使用.md扩展名如 verbose.md、output.md文件开头用---包裹元数据区、!-- ... --为注释。非选项类的章节文件如_NAME.md没有元数据部分。3.2 Meta-data 字段详解元数据区位于文件顶部---之间键值不区分大小写。综合 MANPAGE.md 的字段清单与managen源码single子程序的解析逻辑完整的字段含义如下字段取值示例含义Added4.0该选项加入 curl 的版本号早于 7.66.0 的条目在渲染时会被抑制见源码too_oldArgfile选项所带参数会追加到选项名后如-o filec/CCopyright (C) ...版权行必填缺失会报错Example- -o file $URL一个或多个示例命令行不含curl前缀可用$URL占位Experimentalyes标记实验性选项渲染时插入不要在生产环境使用的警告HelpMake the operation more talkative用于--help输出的短文本超过 49 字符会给出警告Longverbose长选项名不带破折号必填Magic—描述魔法选项特殊处理的选项Multisingle/append/boolean/mutex/custom/per-URL选项多次出现时的语义详见下文Mutexedtrace trace-ascii该选项互斥覆盖的其他选项空格分隔、无破折号ProtocolsHTTP HTTPS选项适用的协议managen会对照内置协议表校验拼写RequiresSSL选项生效所依赖的 libcurl 编译特性Scopeglobal标记全局选项配合Category中的global使用See-also- show-headers相关选项列表渲染为 See also 脚注Shortv短选项字母不带破折号SPDX-License-IdentifiercurlSPDX 许可标识必填Tagscurl空格分隔的标签managen在解析完元数据后会对必填字段做硬校验single子程序缺少Long、Category、Example、Added、See-also、C、SPDX-License-Identifier任一字段都会以非零退出码报错防止不完整的文档流入发布版本。3.3 Multi 的六种语义Multi字段控制选项在命令行中重复出现时的行为渲染时由managen自动补写说明文字single重复给出时以最后一次为准the last set value is usedappend可以在命令行中多次使用、语义为追加boolean重复给出无额外效果并用--no-long形式说明如何关闭对以no-开头的选项则反向推导即去掉no-前缀mutex重复给出无额外效果custom行为留给正文描述生成器不自动添加说明per-URL选项与单个 URL 绑定多 URL 命令行中需每个 URL 使用一次。以 verbose.md 为例它的元数据为Multi: boolean因此在生成的手册中会附带多次提供--verbose无额外效果可用--no-verbose关闭的标准说明。3.4 正文语法Body正文部分紧跟在元数据区之后语法接近 Markdown 但经过刻意简化managen的render子程序逐行处理斜体 / 粗体*asterisks*渲染为斜体**asterisks**渲染为粗体等宽示例以空格4 个空格开头的行按示例处理输出为等宽字体nroff 中为.nf/.fi之间的不折行块三个反引号 或~~~也可用于围栏式引用块列表用## item加说明文字描述条目列表在文件末尾自动终止也可用空##显式结束nroff 输出中表现为.IP/.RS/.RE缩进结构尖括号转义正文中的、必须写成\、\生成器在渲染时还原源码中render会对未转义的、输出警告并中止以保证 Markdown 预览与最终手册一致反引号变量%DATE、%VERSION、%GLOBALS需用反引号包裹避免被 CI 拼写检查误报渲染时再替换选项引用正文只允许用长形式如--verbose引用其他选项生成器通过manpageify自动替换成同时展示短/长形式的正确排版隐藏的书写规则正文中不允许出现连续两个空格会被判定为错误、不允许出现###三级标题、不允许直接书写 nroff 指令.SH、.BR等——render都会拦截报错这正是为了把源文件约束在类 Markdown的安全子集内。3.5 Headers# 与 ##的语义差异#一级标题仅在非选项文件顶层章节中产生.SH输出若出现在选项文件中则被忽略仅作为源文件里帮助读者识别选项用途的标注##二级标题用于正文列表条目见 3.4选项文件中渲染为.IP表格项顶层文件中同样适用###三级标题不被支持直接报错退出。3.6 三个内置变量正文中可以使用的变量必须写在反引号内managen在渲染时源码render子程序中的替换逻辑展开如下变量替换内容数据来源%VERSIONcurl 版本字符串当前仓库为8.22.0-DEVinclude/curl/curlver.h 中的LIBCURL_VERSION宏可用环境变量CURL_MAKETGZ_VERSION覆盖用于发布打包%DATE当前日期YYYY-MM-DD默认取系统当前时间若设置SOURCE_DATE_EPOCH环境变量则取其导出的时间保证可复现构建%GLOBALS所有标记Scope: global的选项逗号分隔的列表由listglobals扫描全部选项文件的元数据动态汇总例如 docs/cmdline-opts/_VERSION.md 正文中就使用%VERSION来生成本手册描述 curl 版本 X的章节。四、五种输出模式mainpage / ascii / listhelp 及其余managen的命令行用法为managen [-d dir] [-I include] [-c colwidth] command [files]其中-d指定存放mainpage.idx与.md文件的目录默认.-I指定用于定位curl/curlver.h的 include 根默认../../include-c可覆盖输出列宽默认 79 列。核心命令如下命令输出用途mainpage单个巨型 nroff 文件最终成为curl.1完整手册页ascii单个纯文本文件最终成为curl.txt用于构建tool_hugehelp.ccurl --manual的文本来源listhelpC 源码生成 src/tool_listhelp.c 形式的curl --help帮助表single FILE单个选项的独立 nroff 手册单独查看/调试某个选项条目protos协议统计列出各协议分别被多少个选项使用另有内部用途的listcats从全部选项的Category生成CURLHELP_*位掩码定义供 src/tool_help.h 使用。listhelp模式还会检查每个Category是否存在于tool_help.h的CURLHELP_定义中、选项名是否超过 78 字符等保证生成的 C 代码可直接编译。五、手动重新生成 curl.15.1 前置条件Perl 解释器版本号从 include/curl/curlver.h 的LIBCURL_VERSION宏读取发布时可用CURL_MAKETGZ_VERSION覆盖日期默认取当前日期设置SOURCE_DATE_EPOCH后可复现构建。5.2 生成 nroff 手册页从docs/cmdline-opts目录执行cd docs/cmdline-opts perl ../../scripts/managen -I ../../include mainpage ./*.md curl.1-I ../../include指定 include 根用于定位curl/curlver.hmainpage渲染模式./*.md传入全部选项文档输出重定向到curl.1。5.3 生成纯文本版把mainpage换成ascii即可perl ../../scripts/managen -I ../../include ascii ./*.md curl.txt5.4 在构建系统中自动执行正常开发流程无需手动运行curl 的构建系统Makefile / CMake会在构建时自动调用managen生成curl.1并进一步用mkhelp.pl之类的脚本把文本版打包进tool_hugehelp.c。listhelp输出则用于生成curl --help帮助源码保证帮助文本与手册始终同源。六、从源码看生成流水线的关键细节6.1 渲染管线总览scripts/managen 的执行流程是先解析命令行参数-d/-I/-c→ 读取版本号CURL_MAKETGZ_VERSION优先否则解析curlver.h→indexoptions预扫描所有选项文件收集短名、长名、Help、Arg、Protocols、Category存入%optshort、%optlong、%helplong等哈希→ 按命令分发到getargs。这一步先全量收集再渲染的设计使得See-also、Mutexed里引用的选项可以在渲染前就被校验是否存在源码中会警告see-also a non-existing option。6.2 示例命令行的自动校验元数据中的每条Example都会被managen逐词检查-x形式的短选项必须在%optshort中、--long形式必须在%helplong中未知选项直接报错。渲染时示例中的$URL占位符被替换为https://example.com并自动加上curl前缀输出。ascii 模式下超过 60 字符的长示例会优先在空格或冒号处换行折行保证纯文本排版整齐。6.3 协议与互斥关系校验Protocols字段的值必须落在源码内置的%protexists表中DNS、FILE、FTP、FTPS、GSS/kerberos、HTTP、HTTPS、IMAP、IPFS、LDAP、MQTT、POP3、SCP、SFTP、SMTP、SSL、TELNET、TFTP、TLS 等其中SSL被标记为已废弃识别不了的协议名会导致退出码 2。Mutexed与See-also引用的选项同样会被验证存在性。这些校验让文档错误在构建期暴露而不是漏进发布手册。6.4 一个真实选项文件的完整剖析以 docs/cmdline-opts/verbose.md 为例其元数据区--- c: Copyright (C) Daniel Stenberg, danielhaxx.se, et al. SPDX-License-Identifier: curl Short: v Long: verbose Mutexed: trace trace-ascii Help: Make the operation more talkative Category: important verbose global Added: 4.0 Multi: boolean Scope: global See-also: - show-headers - silent - trace - trace-ascii Example: - --verbose $URL ---Short: vLong: verbose组合出-v, --verboseCategory: important verbose global同时声明了它属于 important / verbose / global 三个帮助分组其中global与Scope: global配对——渲染时会追加该选项是全局选项无需在每次--next使用时重复指定的说明Mutexed与See-also中引用的trace、trace-ascii、show-headers、silent都必须是真实存在的选项文件正文用## 、## 、## }、## {、## *五种前缀逐条解释 verbose 输出行首符号的含义发送的请求头、收到的响应头、发送的数据、接收的数据、附加信息并用空##显式结束列表——这正是 nroff 中.IP缩进列表的源码形态从 8.10 起重复使用-v会分级提升 trace 输出级别-vv增加时间戳、传输 ID 与全协议跟踪第三次加入内容级跟踪第四次覆盖全部网络组件-v或--no-verbose可重置这类版本演进信息也直接写在正文里正文还提示verbose 输出可能包含用户名、凭据等敏感数据分享日志时需谨慎。另一个值得一读的范例是 docs/cmdline-opts/output.md它展示了Multi: per-URL的典型写法-o可多次给出、与 URL 按顺序一一对应以及#1/#2通配文件名替换、-o -强制输出到 stdout、--out-null抑制响应体等实战细节是理解 per-URL 语义与正文组织方式的完整样本。七、质量保障与维护约定构建期校验必填字段缺失、未知协议、未知分类、未转义尖括号、正文出现连续空格或 nroff 指令、示例引用不存在的选项都会让managen以非零码退出——这意味着任何写坏的选项文档都会直接破坏构建CI 拼写检查变量必须用反引号包裹正是为了逃过 CI 的拼写检查任务避免把%VERSION这类占位符误判为拼写错误可复现构建SOURCE_DATE_EPOCH统一驱动日期输出配合CURL_MAKETGZ_VERSION固定版本号使同一源码树在不同时间构建出的手册一致单一事实来源curl --helplisthelp生成的 C 表、curl.1mainpage模式、curl.txtascii模式全部派生自同一批.md源文件杜绝了帮助文本与手册不一致的经典文档漂移问题。结语managen展示了 curl 在文档工程上结构化写作 生成式排版的成熟实践作者只需遵循docs/cmdline-opts/MANPAGE.md定义的元数据与正文规范撰写单文件构建系统即可自动产出 nroff 手册、纯文本手册与帮助 C 源码同时用严格的构建期校验保证文档质量。如果你正在维护一个 CLI 工具的文档这份设计——选项即文件、索引控顺序、生成器统一渲染、校验前置——本身就是一份值得借鉴的参考实现。【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 curl 手册页生成器 managen 完全指南：从选项文档到 curl.1 的自动化流水线
curl 手册页生成器 managen 完全指南从选项文档到 curl.1 的自动化流水线【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl导读managen是 curl 项目内置的手册页man page生成器它把docs/cmdline-opts目录下一份份独立、接近 Markdown 语法的选项文档自动渲染成完整的 nroff 格式curl.1手册、纯文本版curl.txt以及curl --help的 C 源码。本文以 docs/cmdline-opts/MANPAGE.md 为骨架结合 scripts/managen 的 Perl 实现与 docs/cmdline-opts/mainpage.idx 等仓库文件讲清楚选项文档的元数据格式、正文语法、三个内置变量、五种输出模式以及如何手动重生成 curl 手册页。读完你既能看懂 curl 每个--option的手册条目是如何诞生的也能在自己的文档工程里复刻这套单文件写作、统一渲染的流程。一、managen 是什么一套文档即源码的手册页流水线curl 的手册页不是手工维护的单一 nroff 文件而是由生成器managen从一组结构化源文件动态产出的。这套设计把写文档与排版彻底解耦每个命令行选项有一份独立源文件如-v, --verbose对应 docs/cmdline-opts/verbose.md作者只需用接近 Markdown 的语法描述该选项渲染时managen统一读取 docs/cmdline-opts/mainpage.idx 定义的渲染顺序逐文件生成 nroffroff 排版指令输出其中%options是一个特殊关键字位于索引文件中它指示生成器把所有命令行选项文档按长选项名排序后一次性插入从而自动拼出完整的OPTIONS章节。也就是说新增一个 curl 命令行选项的标准动作是往docs/cmdline-opts/放一个.md文件并写清元数据其余排版工作全部交给managen。二、源文件组织mainpage.idx 与 %options2.1 索引文件决定全局顺序mainpage.idx 是一个纯文本索引每一行点名一个要渲染的.md文件#开头的行为注释。当前仓库中它的实际内容节选展示了手册页的章节骨架_NAME.md _SYNOPSIS.md _DESCRIPTION.md _URL.md _GLOBBING.md _VARIABLES.md _OUTPUT.md _PROTOCOLS.md _PROGRESS.md _VERSION.md _OPTIONS.md %options _FILES.md _ENVIRONMENT.md _PROXYPREFIX.md _EXITCODES.md _BUGS.md _AUTHORS.md _WWW.md _SEEALSO.md可以看到以_开头的文件是手册的顶层章节名称、概要、描述、URL 语法、通配、变量、输出、协议、进度、版本等而%options恰好被放在_OPTIONS.md之后保证所有选项说明连续出现在手册的 OPTIONS 区域。2.2 %options 的插入逻辑从 scripts/managen 的mainpage子程序可以看到生成器逐行读取mainpage.idx凡遇到%options行就对调用者传入的选项文件列表按去掉.md后缀后的名称做字典序排序sortnames再逐个调用single子程序渲染if(/^%options/) { # output docs for all options foreach my $f (sort sortnames files) { $ret single($dir, $manpage, $f, 0); } }也就是说无论索引文件怎么写%options展开出来的选项条目顺序始终是按长选项名稳定排序的这保证了不同版本手册页之间选项排列的可预期性。三、选项文件格式元数据 正文3.1 文件命名MANPAGE.md 指出每个选项的文档文件按long name命名、不带前缀破折号。需要留意的是文档正文以.d后缀做示意如verbose.d而当前仓库中实际的源文件统一使用.md扩展名如 verbose.md、output.md文件开头用---包裹元数据区、!-- ... --为注释。非选项类的章节文件如_NAME.md没有元数据部分。3.2 Meta-data 字段详解元数据区位于文件顶部---之间键值不区分大小写。综合 MANPAGE.md 的字段清单与managen源码single子程序的解析逻辑完整的字段含义如下字段取值示例含义Added4.0该选项加入 curl 的版本号早于 7.66.0 的条目在渲染时会被抑制见源码too_oldArgfile选项所带参数会追加到选项名后如-o filec/CCopyright (C) ...版权行必填缺失会报错Example- -o file $URL一个或多个示例命令行不含curl前缀可用$URL占位Experimentalyes标记实验性选项渲染时插入不要在生产环境使用的警告HelpMake the operation more talkative用于--help输出的短文本超过 49 字符会给出警告Longverbose长选项名不带破折号必填Magic—描述魔法选项特殊处理的选项Multisingle/append/boolean/mutex/custom/per-URL选项多次出现时的语义详见下文Mutexedtrace trace-ascii该选项互斥覆盖的其他选项空格分隔、无破折号ProtocolsHTTP HTTPS选项适用的协议managen会对照内置协议表校验拼写RequiresSSL选项生效所依赖的 libcurl 编译特性Scopeglobal标记全局选项配合Category中的global使用See-also- show-headers相关选项列表渲染为 See also 脚注Shortv短选项字母不带破折号SPDX-License-IdentifiercurlSPDX 许可标识必填Tagscurl空格分隔的标签managen在解析完元数据后会对必填字段做硬校验single子程序缺少Long、Category、Example、Added、See-also、C、SPDX-License-Identifier任一字段都会以非零退出码报错防止不完整的文档流入发布版本。3.3 Multi 的六种语义Multi字段控制选项在命令行中重复出现时的行为渲染时由managen自动补写说明文字single重复给出时以最后一次为准the last set value is usedappend可以在命令行中多次使用、语义为追加boolean重复给出无额外效果并用--no-long形式说明如何关闭对以no-开头的选项则反向推导即去掉no-前缀mutex重复给出无额外效果custom行为留给正文描述生成器不自动添加说明per-URL选项与单个 URL 绑定多 URL 命令行中需每个 URL 使用一次。以 verbose.md 为例它的元数据为Multi: boolean因此在生成的手册中会附带多次提供--verbose无额外效果可用--no-verbose关闭的标准说明。3.4 正文语法Body正文部分紧跟在元数据区之后语法接近 Markdown 但经过刻意简化managen的render子程序逐行处理斜体 / 粗体*asterisks*渲染为斜体**asterisks**渲染为粗体等宽示例以空格4 个空格开头的行按示例处理输出为等宽字体nroff 中为.nf/.fi之间的不折行块三个反引号 或~~~也可用于围栏式引用块列表用## item加说明文字描述条目列表在文件末尾自动终止也可用空##显式结束nroff 输出中表现为.IP/.RS/.RE缩进结构尖括号转义正文中的、必须写成\、\生成器在渲染时还原源码中render会对未转义的、输出警告并中止以保证 Markdown 预览与最终手册一致反引号变量%DATE、%VERSION、%GLOBALS需用反引号包裹避免被 CI 拼写检查误报渲染时再替换选项引用正文只允许用长形式如--verbose引用其他选项生成器通过manpageify自动替换成同时展示短/长形式的正确排版隐藏的书写规则正文中不允许出现连续两个空格会被判定为错误、不允许出现###三级标题、不允许直接书写 nroff 指令.SH、.BR等——render都会拦截报错这正是为了把源文件约束在类 Markdown的安全子集内。3.5 Headers# 与 ##的语义差异#一级标题仅在非选项文件顶层章节中产生.SH输出若出现在选项文件中则被忽略仅作为源文件里帮助读者识别选项用途的标注##二级标题用于正文列表条目见 3.4选项文件中渲染为.IP表格项顶层文件中同样适用###三级标题不被支持直接报错退出。3.6 三个内置变量正文中可以使用的变量必须写在反引号内managen在渲染时源码render子程序中的替换逻辑展开如下变量替换内容数据来源%VERSIONcurl 版本字符串当前仓库为8.22.0-DEVinclude/curl/curlver.h 中的LIBCURL_VERSION宏可用环境变量CURL_MAKETGZ_VERSION覆盖用于发布打包%DATE当前日期YYYY-MM-DD默认取系统当前时间若设置SOURCE_DATE_EPOCH环境变量则取其导出的时间保证可复现构建%GLOBALS所有标记Scope: global的选项逗号分隔的列表由listglobals扫描全部选项文件的元数据动态汇总例如 docs/cmdline-opts/_VERSION.md 正文中就使用%VERSION来生成本手册描述 curl 版本 X的章节。四、五种输出模式mainpage / ascii / listhelp 及其余managen的命令行用法为managen [-d dir] [-I include] [-c colwidth] command [files]其中-d指定存放mainpage.idx与.md文件的目录默认.-I指定用于定位curl/curlver.h的 include 根默认../../include-c可覆盖输出列宽默认 79 列。核心命令如下命令输出用途mainpage单个巨型 nroff 文件最终成为curl.1完整手册页ascii单个纯文本文件最终成为curl.txt用于构建tool_hugehelp.ccurl --manual的文本来源listhelpC 源码生成 src/tool_listhelp.c 形式的curl --help帮助表single FILE单个选项的独立 nroff 手册单独查看/调试某个选项条目protos协议统计列出各协议分别被多少个选项使用另有内部用途的listcats从全部选项的Category生成CURLHELP_*位掩码定义供 src/tool_help.h 使用。listhelp模式还会检查每个Category是否存在于tool_help.h的CURLHELP_定义中、选项名是否超过 78 字符等保证生成的 C 代码可直接编译。五、手动重新生成 curl.15.1 前置条件Perl 解释器版本号从 include/curl/curlver.h 的LIBCURL_VERSION宏读取发布时可用CURL_MAKETGZ_VERSION覆盖日期默认取当前日期设置SOURCE_DATE_EPOCH后可复现构建。5.2 生成 nroff 手册页从docs/cmdline-opts目录执行cd docs/cmdline-opts perl ../../scripts/managen -I ../../include mainpage ./*.md curl.1-I ../../include指定 include 根用于定位curl/curlver.hmainpage渲染模式./*.md传入全部选项文档输出重定向到curl.1。5.3 生成纯文本版把mainpage换成ascii即可perl ../../scripts/managen -I ../../include ascii ./*.md curl.txt5.4 在构建系统中自动执行正常开发流程无需手动运行curl 的构建系统Makefile / CMake会在构建时自动调用managen生成curl.1并进一步用mkhelp.pl之类的脚本把文本版打包进tool_hugehelp.c。listhelp输出则用于生成curl --help帮助源码保证帮助文本与手册始终同源。六、从源码看生成流水线的关键细节6.1 渲染管线总览scripts/managen 的执行流程是先解析命令行参数-d/-I/-c→ 读取版本号CURL_MAKETGZ_VERSION优先否则解析curlver.h→indexoptions预扫描所有选项文件收集短名、长名、Help、Arg、Protocols、Category存入%optshort、%optlong、%helplong等哈希→ 按命令分发到getargs。这一步先全量收集再渲染的设计使得See-also、Mutexed里引用的选项可以在渲染前就被校验是否存在源码中会警告see-also a non-existing option。6.2 示例命令行的自动校验元数据中的每条Example都会被managen逐词检查-x形式的短选项必须在%optshort中、--long形式必须在%helplong中未知选项直接报错。渲染时示例中的$URL占位符被替换为https://example.com并自动加上curl前缀输出。ascii 模式下超过 60 字符的长示例会优先在空格或冒号处换行折行保证纯文本排版整齐。6.3 协议与互斥关系校验Protocols字段的值必须落在源码内置的%protexists表中DNS、FILE、FTP、FTPS、GSS/kerberos、HTTP、HTTPS、IMAP、IPFS、LDAP、MQTT、POP3、SCP、SFTP、SMTP、SSL、TELNET、TFTP、TLS 等其中SSL被标记为已废弃识别不了的协议名会导致退出码 2。Mutexed与See-also引用的选项同样会被验证存在性。这些校验让文档错误在构建期暴露而不是漏进发布手册。6.4 一个真实选项文件的完整剖析以 docs/cmdline-opts/verbose.md 为例其元数据区--- c: Copyright (C) Daniel Stenberg, danielhaxx.se, et al. SPDX-License-Identifier: curl Short: v Long: verbose Mutexed: trace trace-ascii Help: Make the operation more talkative Category: important verbose global Added: 4.0 Multi: boolean Scope: global See-also: - show-headers - silent - trace - trace-ascii Example: - --verbose $URL ---Short: vLong: verbose组合出-v, --verboseCategory: important verbose global同时声明了它属于 important / verbose / global 三个帮助分组其中global与Scope: global配对——渲染时会追加该选项是全局选项无需在每次--next使用时重复指定的说明Mutexed与See-also中引用的trace、trace-ascii、show-headers、silent都必须是真实存在的选项文件正文用## 、## 、## }、## {、## *五种前缀逐条解释 verbose 输出行首符号的含义发送的请求头、收到的响应头、发送的数据、接收的数据、附加信息并用空##显式结束列表——这正是 nroff 中.IP缩进列表的源码形态从 8.10 起重复使用-v会分级提升 trace 输出级别-vv增加时间戳、传输 ID 与全协议跟踪第三次加入内容级跟踪第四次覆盖全部网络组件-v或--no-verbose可重置这类版本演进信息也直接写在正文里正文还提示verbose 输出可能包含用户名、凭据等敏感数据分享日志时需谨慎。另一个值得一读的范例是 docs/cmdline-opts/output.md它展示了Multi: per-URL的典型写法-o可多次给出、与 URL 按顺序一一对应以及#1/#2通配文件名替换、-o -强制输出到 stdout、--out-null抑制响应体等实战细节是理解 per-URL 语义与正文组织方式的完整样本。七、质量保障与维护约定构建期校验必填字段缺失、未知协议、未知分类、未转义尖括号、正文出现连续空格或 nroff 指令、示例引用不存在的选项都会让managen以非零码退出——这意味着任何写坏的选项文档都会直接破坏构建CI 拼写检查变量必须用反引号包裹正是为了逃过 CI 的拼写检查任务避免把%VERSION这类占位符误判为拼写错误可复现构建SOURCE_DATE_EPOCH统一驱动日期输出配合CURL_MAKETGZ_VERSION固定版本号使同一源码树在不同时间构建出的手册一致单一事实来源curl --helplisthelp生成的 C 表、curl.1mainpage模式、curl.txtascii模式全部派生自同一批.md源文件杜绝了帮助文本与手册不一致的经典文档漂移问题。结语managen展示了 curl 在文档工程上结构化写作 生成式排版的成熟实践作者只需遵循docs/cmdline-opts/MANPAGE.md定义的元数据与正文规范撰写单文件构建系统即可自动产出 nroff 手册、纯文本手册与帮助 C 源码同时用严格的构建期校验保证文档质量。如果你正在维护一个 CLI 工具的文档这份设计——选项即文件、索引控顺序、生成器统一渲染、校验前置——本身就是一份值得借鉴的参考实现。【免费下载链接】curlA command line tool and library for transferring data with URL syntax, supporting DICT, FILE, FTP, FTPS, GOPHER, GOPHERS, HTTP, HTTPS, IMAP, IMAPS, LDAP, LDAPS, MQTT, MQTTS, POP3, POP3S, RTSP, SCP, SFTP, SMB, SMBS, SMTP, SMTPS, TELNET, TFTP, WS and WSS. libcurl offers a myriad of powerful features项目地址: https://gitcode.com/GitHub_Trending/cu/curl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考