curl 项目 curldown 文档格式详解：从 Markdown 式源码到 nroff 手册页的自动化管线

curl 项目 curldown 文档格式详解从 Markdown 式源码到 nroff 手册页的自动化管线【免费下载链接】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/curlcurldown 是 curl 项目中用于编写 libcurl 手册页man pages的一种 Markdown 风格文本格式它在 docs/CURLDOWN.md 中被完整定义。本文以该文档为主线结合仓库内 scripts/cd2nroff、scripts/nroff2cd、scripts/cd2cd、scripts/cdall 四个 Perl 转换脚本的源码实现系统讲解 curldown 的语法规范、元数据约束、转换工具链与已知边界帮助文档贡献者快速上手并为已有 nroff 手册页的维护提供可复用的工程思路。一、为什么需要 curldown设计初衷与目标curl 的历史文档长期以 nroff 格式groff排版语言维护这种格式对普通贡献者极不友好容易写错宏命令、难以阅读源码。curldown 的出现正是为了解决这一系列痛点其目标可以归纳为降低贡献门槛采用人们熟悉的 Markdown 式语法书写 libcurl 文档让贡献者所见即所得不再需要学习 nroff 宏减少语法错误通过受限的、结构化的语法从源头上抑制拼写与排版错误保持输出一致借助脚本自动生成 nroff 手册页生成结果与历史手工编写的 nroff 文件几乎逐字节一致从而让既有的测试用例、HTML 转换流程如roffit和网站基础设施基本不受影响便于修复历史问题nroff 由程序统一生成后诸如转义连字符-防止 man 渲染为 Unicode 破折号这类问题只需在生成器里修一次即可全量生效携带结构化元数据每个文件头部包含结构化字段如 See-also 关联信息、协议范围、引入版本为生成更高质量的 nroff 输出如自动生成 SEE ALSO、PROTOCOLS、AVAILABILITY 段落和让工具链知道这个文件讲什么提供了基础。从 scripts/cd2nroff 的实现可以看出生成器对每一条输出规则都做了精细控制例如-会被转义为\-、单引号转为\(aq、行首的句点会被\转义见 scripts/cd2nroff 中quoted函数与正文处理分支这正是修复 nroff 历史问题目标的具体落地。二、文件扩展名与目录组织由于 curldown 的书写观感与 Markdown 高度相似项目统一使用.md扩展名。仓库中的文档分布情况为命令行工具手册docs/cmdline-opts/*.md如 alt-svc.md、aws-sigv4.md包含以_开头的章节碎片文件如 _NAME.mdlibcurl 函数手册docs/libcurl/*.md如 curl_easy_setopt.md、curl_easy_perform.md选项手册docs/libcurl/opt/目录下的CURLOPT_*.md。各目录的编译清单统一维护在Makefile.inc中例如 docs/cmdline-opts/Makefile.inc 同时被Makefile.am与CMakeLists.txt共享保证 autotools 与 CMake 两套构建系统使用同一份文件列表。三、curldown 与 nroff 的双向转换工具链文档定义了三类转换工具全部为 Perl 脚本位于 scripts/ 目录工具方向用途源码位置cd2nroffcurldown → nroff生成最终 man page是日常发布用主工具scripts/cd2nroffnroff2cdnroff → curldown仅用于历史文档的一次性初始迁移理想情况下不再需要scripts/nroff2cdcd2cdcurldown → curldown对现有 curldown 做规范化、清理、检查scripts/cd2cdcdall批量转换对指定目录下所有 curldown 批量调用cd2nroff生成.3手册页scripts/cdall3.1 cd2nroff主生成器cd2nroff支持的命令行选项Usage: cd2nroff [options] [file.md] -d dir 将输出写到该目录下、以元数据 Title 命名的文件而不是 stdout -e ext 配合 -d 使用时向输出文件名追加任意扩展名文本 -h 显示帮助 -v 显示版本号后退出不指定-d时输出到标准输出方便管道处理。日期通过SOURCE_DATE_EPOCH环境变量若设置或本地时间生成并格式化为YYYY-MM-DD写入.TH宏见 scripts/cd2nroff。值得注意的实现细节头校验严格解析头部时若缺少Title:、Section:、Source:、See-also:、C:版权、SPDX-License-Identifier:任一字段即报错退出Source: libcurl的手册页还必须提供Added-in:且版本号必须匹配^[0-9.][0-9]$或为n/a见 scripts/cd2nroff 头部校验段协议白名单内置%knownprotos哈希表校验Protocol:列表包含全部 URL schemeDICT、FILE、FTP、FTPS、GOPHER、GOPHERS、HTTP、HTTPS、IMAP、IMAPS、LDAP、LDAPS、MQTT、POP3、POP3S、RTSP、SCP、SFTP、SMB、SMBS、SMTP、SMTPS、TELNET、TFTP、WS、WSS以及特殊值TLS、TCP、QUIC、All自动生成段落遇到# %PROTOCOLS%时调用outprotocols根据元数据生成 PROTOCOLS 段落TLS会被展开为 all TLS based protocols: HTTPS, FTPS, IMAPS, POP3S, SMTPS etc.遇到# %AVAILABILITY%时调用 AVAILABILITY 生成 Added in curl x.y.z文件末尾自动追加按字母序排列的 SEE ALSO 段落见 scripts/cd2nroff 中outseealso、outprotocols、outtls三个子程序正文质量检查未转义的或、行内连续两个空格都会触发报错并累计$errors最终以非零状态返回充当 lint 角色。3.2 nroff2cd一次性迁移工具nroff2cd负责把历史 nroff 手册页转换为 curldown。它解析.TH宏提取 Title/Section/Source 生成头部将.SH转为#、.IP转为##、.B/\fB转为**、.I/\fI转为*.nf代码区转为~~~c引块并收集.BR中的 SEE ALSO 条目排序输出。该工具的设计定位是仅用于最初的历史转换理想情况下永不再用见 scripts/nroff2cd 头部注释。3.3 cd2cd规范化与清理cd2cd读取一个 curldown 文件重写头部保持 Title/Section/Source 不变按字母序重新整理See-also:列表并清理正文去掉*curl_symbol(3)*这类包裹 curl 符号的多余星号因为符号会被自动转为斜体压缩连续空行最多保留一个对超过 90 字符的行发出 WARN 提示见 scripts/cd2cd。用法cd2cd file.md # 规范化结果输出到 stdout cd2cd --in-place file.md # 原地覆盖该模式下可一次传入多个文件并忽略单个文件的错误3.4 cdall批量转换cdall接收一个或多个目录参数遍历每个目录下所有.md文件逐个调用./scripts/cd2nroff -d dir file.md生成同名.3手册页cdall [dir1] [dir2] [dir3] ..从源码看它把.md后缀替换为.3作为输出文件名见 scripts/cdall适用于构建流程中的批量文档生成。四、curldown 格式规范详解4.1 头部元数据Front Matter每个 curldown 文件必须以---包围的头部开始示例如下取自 docs/CURLDOWN.md--- c: Copyright (C) Daniel Stenberg, danielhaxx.se, et al. SPDX-License-Identifier: curl Title: CURLOPT_AWS_SIGV4 Section: 3 Source: libcurl Protocol: - HTTP See-also: - CURLOPT_HEADEROPT (3) - CURLOPT_HTTPAUTH (3) TLS-backend: - [name] Added-in: [version or n/a] ---强制约束所有字段必须齐全且至少要有一条See-also:条目Title:将决定-d模式下的输出文件名$dir/$title.$section见 scripts/cd2nroffSection: 3库函数手册时Protocol:列表至少包含一个协议可用*表示几乎适用于一切此时*必须是唯一列出的协议识别的协议为 URL scheme 的大写形式或特殊值TLS、TCP若Protocol:中包含TLS则必须同时提供TLS-backend:列表取值为All或以下后端之一依据 docs/CURLDOWN.md 及 scripts/cd2nroff 中%knowntls白名单TLS 后端说明GnuTLSGnuTLS 后端mbedTLSmbedTLS 后端OpenSSL同时涵盖 AmiSSL、AWS-LC、BoringSSL、LibreSSL 与 quictlsrustlsRust 实现的 rustls 后端SchannelWindows 原生 Schannel 后端wolfSSLwolfSSL 后端All全部 TLS 后端实际库函数手册中可以对照真实文件观察这些字段的写法例如 curl_easy_cleanup.md 的Added-in: 7.1、curl_easy_option_by_id.md 的Added-in: 7.73.0命令行动态选项文件则使用Added:字段记录引入版本如 aws-sigv4.md 中的Added: 7.75.0。4.2 正文排版语法头部之后是正文采用 Markdown 风格语法示例来自 docs/CURLDOWN.md# NAME a page - this is a page describing something # SYNOPSIS ~~~c #include curl/curl.h CURLcode curl_easy_setopt(CURL *handle, CURLOPT_AWS_SIGV4, char *param); ~~~代码块以~~~c开始、~~~结束生成 nroff 的.nf段落普通引用块可用~~~或 4 空格缩进缩进块在 scripts/cd2nroff 中以quote 4状态处理同样输出.nf/.fi标题一级标题#转换为.SH二级标题##转换为.IPnroff2cd同样支持反向转换含空格或无引号的标题在 scripts/cd2nroff 中会按是否需要加双引号分别处理加粗**bold**斜体*italics*反引号由于 man 不支持反引号排版源码中的word在生成的 nroff 中以斜体呈现空行生成时多余的空行会被工具自动剔除因此源码中可以自由使用空行提升可读性尖括号转义为保证 curldown 也能在普通 Markdown 渲染器中正确显示所有字面量、必须用反斜杠转义为\、\scripts/cd2nroff 会对未转义尖括号报错再将其还原为字面字符输出行首点号与引号生成 nroff 时行首的.与会被转义quoted子程序正文行首的.也会被\保护避免与 groff 宏混淆。4.3 内容占位符自动生成段落# %PROTOCOLS%根据头部Protocol:元数据自动插入 PROTOCOLS 段落# %AVAILABILITY%根据头部Added-in:元数据自动插入 AVAILABILITY 段落值为n/a时跳过。对应实现见 scripts/cd2nroffoutprotocols会生成 This functionality affects ... 的协议描述若协议仅有一个且为All则输出 supported protocols、单个普通协议则追加 onlyouttls则根据TLS-backend:生成 All TLS backends support this option. 或 This option works only with the following TLS backends: ... 等文案。若源码中直接书写了PROTOCOLS或AVAILABILITY标题工具会打印 WARN 提示应使用占位符。4.4 符号自动链接Symbols所有拥有独立手册页的 curl 符号如curl_easy_perform(3)无需手工加星号即可在输出中自动渲染为斜体。这一机制确保后续经roffit转 HTML 时这些符号能正确转为链接同时让正文在提到大量符号时依然易读。自动链接的匹配模式为(lib|)curl[^ ]*(3)即匹配curl...或libcurl...且以(3)结尾的令牌。相关实现可见 scripts/cd2nroff 中正则s/((lib|)curl([^ ]*\(3\)))/\fI$1\fP/gi而 scripts/cd2cd 则会反向移除这些符号上多余的手工星号*curl_symbol(3)*保证两种书写方式殊途同归。五、已知限制与注意事项依据 docs/CURLDOWN.md 的 Known issues 部分cd2nroff尚不支持起止标记分处两行的斜体与加粗因此强调标记必须写在同一行内nroff2cd为所有.fi段生成~~~c代码样式引块因为 nroff 源格式本身不区分代码块与普通引块迁移后需要人工判断调整头部校验严格且不可省略字段如See-also:、C:、SPDX-License-Identifier:新增或迁移手册页时应直接以完整模板起步避免反复触发 scripts/cd2nroff 的校验报错尖括号必须转义行内不得出现连续两个空格行宽建议控制在 90 字符以内scripts/cd2cd 会对超长行告警。六、实践路径为 curl 文档贡献一页手册综合以上规范新增或修改手册页的推荐流程是在对应目录命令行选项在docs/cmdline-opts/库函数在docs/libcurl/或docs/libcurl/opt/创建.md文件完整填写头部元数据并确保See-also:非空按 4.2 节语法书写正文#一级标题组织大节、##组织子项代码用~~~c包裹字面量尖括号加反斜杠转义用cd2cd做规范化检查cd2cd file.md查看清理结果或用--in-place直接原地整理用cd2nroff -d dir file.md生成 nroff 验证.SH、.IP、.nf/.fi结构是否符合预期批量场景下用cdall dir1 dir2 ...一次转换整个目录已有 nroff 的历史页面才需要借助nroff2cd做一次性迁移随后按 4.2 节人工复核.fi段的代码/引用分类。整个流程中docs/CURLDOWN.md 是语法总纲四个脚本cd2nroff、nroff2cd、cd2cd、cdall是落地执行器二者配合即可在不改动既有 nroff 生态的前提下用现代、易读、可校验的 Markdown 风格源码持续产出高质量手册页。【免费下载链接】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），仅供参考