尧图网页设计 
qBittorrent 手册页工程实践Markdown 源稿编写、Pandoc 转换与多语言en/ru构建流程【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent导读qBittorrent 的手册页man pages并非直接以 roff 语法编写而是采用Markdown 源稿 Pandoc 自动转换的维护流程源稿与产物同时入库、随构建系统统一安装。本文以仓库中的 doc/README.md 为骨架完整梳理其写作约定、构建命令、内容章节结构与多语言翻译发布全链路并结合 src/app/cmdoptions.cpp、dist/unix/CMakeLists.txt 等源码给出底层实现印证。读完本文你可以熟练地在 qBittorrent 源码仓库中增改手册页、复现转换命令并为新语言添加手册翻译。一、为什么手册页要先写成 Markdown传统 Unix 手册页直接使用 roff/troff 排版指令.TH、.SH、.TP等书写与维护成本高、可读性差。qBittorrent 的解决方案是先在doc/语言/目录下维护可读的 Markdown 源稿.md再借助 Pandoc 将其转换为 roff 格式的最终手册文件无扩展名的.1文件。仓库中当前同时存在两种文件且均被纳入版本管理源稿如 doc/en/qbittorrent-nox.1.md、doc/en/qbittorrent.1.md 及 doc/ru/ 下的俄语对应文件产物doc/en/qbittorrent.1、doc/en/qbittorrent-nox.1 等 roff 文件。这一写 Markdown、出 roff的模式让贡献者无需掌握 roff 语法即可维护高质量手册也使文档正文能够被普通 Markdown 渲染工具预览、diff 与检索。二、Pandoc 转换命令与构建步骤构建手册页需要 Pandoc 支持 Markdown 到man格式的转换。doc/README.md给出的两条标准命令是pandoc -s -f markdown -t man qbittorrent.1.md -o qbittorrent.1 pandoc -s -f markdown -t man qbittorrent-nox.1.md -o qbittorrent-nox.1命令要点拆解参数含义-sstandalone独立文档模式生成带完整 roff 头/尾结构的完整 man 文件而不是 fragment-f markdown输入格式为 Pandocs Markdown其扩展语法与通用 GFM 略有差异-t man输出格式为 roff man page-o指定输出文件名转换时需要注意由于使用了 Pandoc 特定的 Markdown 方言源稿中的标题层级、列表、加粗等写法需遵循Pandoc 的 Markdown 规范才能被正确映射为 roff 排版指令仓库在 README 中也明确要求编辑者先了解该格式约定。2.1 没有本地 Pandoc 时的备选路径若本机安装 Pandoc 有困难可使用 Pandoc 官方提供的在线转换器toman、standalonetrue的预置参数链接。但官方在线转换器的输出存在一个已知陷阱复制结果到本地文件时部分头部信息会丢失因此必须小心——既不要覆盖文件已有的开头头部也不要截掉结尾的尾部头部。稳妥起见仍建议以本地pandoc命令生成的产物为准。2.2 产物必须随源稿一并提交doc/README.md明确要求编辑完成后Markdown 源稿*.md与生成的 man 产物*.1都要提交二者是同步维护的一对文件缺一不可——源稿保证可维护性产物保证用户安装即用。三、手册正文的标准章节结构观察 doc/en/qbittorrent-nox.1.md91 行与 doc/en/qbittorrent.1.md82 行两个英文源稿可总结出 qBittorrent 手册统一的 roff 命名与章节模板% QBITTORRENT-NOX(1) 一行描述 % 空作者行 % 月份年份 # NAME # SYNOPSIS # DESCRIPTION # OPTIONS ## Options when adding new torrents # ENVIRONMENT # BUGS # AUTHORS头部三行%是 Pandoc man 输出所需的标题块对应 roff 的.TH紧随其后是手册标准小节NAME / SYNOPSIS程序名与调用形式。无头模式为qbittorrent-nox [options] [(filename | url)...]GUI 版为qbittorrent均支持--help、--versionDESCRIPTION介绍程序定位——基于 C/Qt、使用 libtorrent-rasterbar 实现、支持 Unicode、UPnP/NAT-PMP 端口映射、加密、FAST extension 与 PeX 等特性。qbittorrent-nox一节还会说明其默认由 Web UIhttp://localhost:8080默认用户名admin未设密码时每次启动在控制台打印临时随机密码控制OPTIONS全部命令行参数详见下一节ENVIRONMENT环境变量等价写法详见第五节BUGS / AUTHORS指向官方 bug 跟踪系统作者署名。四、手册收录的命令行参数清单两个手册源稿中 OPTIONS 部分的参数高度一致其中 GUI 版独有的--no-splash与--skip-dialogGUI 版添加种子时是否弹窗正是两类二进制的功能差异体现选项适用说明-h | --help全部显示帮助并退出-v | --version全部显示版本并退出--confirm-legal-notice全部确认法律声明配合无人值守启动--webui-portport全部修改 WebUI 端口--torrenting-portport全部修改 BT 传输端口--no-splashGUI禁用启动闪屏-d | --daemonnox以守护进程方式后台运行--profiledir全部将配置文件存放于指定目录--configurationname全部使用qBittorrent_name形式的独立配置目录--relative-fastresume全部改写 libtorrent fastresume 文件使文件路径相对于 profile 目录(filename | url)...全部直接下载传入的种子文件或链接4.1 添加新种子时的附加参数两个源稿还用三级小节Options when adding new torrents单独归纳了添加种子场景的选项--save-pathpath种子保存路径--add-stoppedtrue|false以运行还是停止状态添加--seed-mode种子模式只做种不上传数据--categoryname分配给指定分类分类不存在时自动创建--sequential按顺序下载文件--first-and-last优先下载首尾分片--skip-dialogtrue|false添加种子时是否弹出Add New Torrent对话框。4.2 源码侧的参数定义印证上述参数并非文档凭空撰写均可在命令行解析实现中逐一定位。参数解析集中在 src/app/cmdoptions.cpp布尔开关、整型参数分别由BoolOption、IntOption等选项类封装例如第 316319 行就声明了NO_SPLASH_OPTION {no-splash}、WEBUI_PORT_OPTION {webui-port}、TORRENTING_PORT_OPTION {torrenting-port}布尔值的取值判定isTrue()cmdoptions.cpp 第 6265 行只接受字面量1或大小写不敏感的true这与手册 ENVIRONMENT 一节的约定一致。五、环境变量等价写法源码级印证两个手册的 ENVIRONMENT 小节都记载了一条通用映射规则对名为parameter-name的选项环境变量名为QBT_PARAMETER_NAME全大写-替换为_标志类参数置为1或TRUE即表示开启。这一规则的实现位于 src/app/cmdoptions.cpp 第 97101 行的envVarName()return uQBT_ m_name.toString().toUpper().replace(u-, u_);即选项名webui-port→QBT_WEBUI_PORTno-splash→QBT_NO_SPLASH与文档描述完全一致。手册中给出的两个可直接执行的示例QBT_WEBUI_PORT8081 qbittorrent-nox # nox用环境变量改 WebUI 端口 QBT_NO_SPLASH1 qbittorrent # GUI用环境变量禁用闪屏手册同时强调了一条优先级规则命令行参数优先于环境变量。也就是说--webui-port8082与QBT_WEBUI_PORT8081同时出现时以命令行取值 8082 为准。六、多语言翻译流程与 CMake 安装规则将手册页翻译为新语言是doc/README.md着力说明的第二条主线。参考 doc/ru/已含俄语版两对源稿/产物可归纳出标准步骤在doc/下创建以语言代码命名的新子目录如doc/fr/将翻译好的文件放入该目录命名必须与英文版保持一致qbittorrent.1.mdqbittorrent.1、qbittorrent-nox.1.mdqbittorrent-nox.1把该语言代码追加到 dist/unix/CMakeLists.txt 的manPageLanguages列表中。6.1 CMake 中的实际安装逻辑dist/unix/CMakeLists.txt 第 2133 行展示了语言清单与安装细节set(manPageLanguages en ru ) foreach(manPageLanguage ${manPageLanguages}) install(FILES ${PROJECT_SOURCE_DIR}/doc/${manPageLanguage}/$IF:$BOOL:${GUI},qbittorrent.1,qbittorrent-nox.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/$$NOT:$STREQUAL:${manPageLanguage},en:${manPageLanguage}/man1 COMPONENT doc ) endforeach()几点可从中读出的工程约束当前官方维护的语言是en 与 ru新增翻译需同步修改此清单否则不会进入安装产物安装哪个手册文件由构建目标决定构建GUI版时装qbittorrent.1构建nox无头版时装qbittorrent-nox.1安装目录遵循 man 惯例英文版装入mandir/man1其他语言版装入mandir/语言/man1如ru/man1对应第 2930 行注释中English man pages are installed into man1, while other languages into /man1的说明。七、维护自查清单结合全文给出手册维护者的最终检查要点格式源稿用 Pandocs Markdown 撰写保留首部%标题块与 NAME/SYNOPSIS/…/AUTHORS 标准小节转换用pandoc -s -f markdown -t man生成产物若走在线转换器复制输出时注意补齐丢失的头部、勿截断头尾提交*.md源稿与生成的*.1产物必须成对提交翻译新增语言需同时完成doc/lang/下的全部四个文件并在 dist/unix/CMakeLists.txt 的manPageLanguages注册语言代码一致性手册中的参数与 ENVIRONMENT 规则改动时同步核对 src/app/cmdoptions.cpp 中选项定义及envVarName()的命名映射确保文档、实现与安装三处不脱节。【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 qBittorrent 手册页工程实践：Markdown 源稿编写、Pandoc 转换与多语言（en/ru）构建流程
qBittorrent 手册页工程实践Markdown 源稿编写、Pandoc 转换与多语言en/ru构建流程【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent导读qBittorrent 的手册页man pages并非直接以 roff 语法编写而是采用Markdown 源稿 Pandoc 自动转换的维护流程源稿与产物同时入库、随构建系统统一安装。本文以仓库中的 doc/README.md 为骨架完整梳理其写作约定、构建命令、内容章节结构与多语言翻译发布全链路并结合 src/app/cmdoptions.cpp、dist/unix/CMakeLists.txt 等源码给出底层实现印证。读完本文你可以熟练地在 qBittorrent 源码仓库中增改手册页、复现转换命令并为新语言添加手册翻译。一、为什么手册页要先写成 Markdown传统 Unix 手册页直接使用 roff/troff 排版指令.TH、.SH、.TP等书写与维护成本高、可读性差。qBittorrent 的解决方案是先在doc/语言/目录下维护可读的 Markdown 源稿.md再借助 Pandoc 将其转换为 roff 格式的最终手册文件无扩展名的.1文件。仓库中当前同时存在两种文件且均被纳入版本管理源稿如 doc/en/qbittorrent-nox.1.md、doc/en/qbittorrent.1.md 及 doc/ru/ 下的俄语对应文件产物doc/en/qbittorrent.1、doc/en/qbittorrent-nox.1 等 roff 文件。这一写 Markdown、出 roff的模式让贡献者无需掌握 roff 语法即可维护高质量手册也使文档正文能够被普通 Markdown 渲染工具预览、diff 与检索。二、Pandoc 转换命令与构建步骤构建手册页需要 Pandoc 支持 Markdown 到man格式的转换。doc/README.md给出的两条标准命令是pandoc -s -f markdown -t man qbittorrent.1.md -o qbittorrent.1 pandoc -s -f markdown -t man qbittorrent-nox.1.md -o qbittorrent-nox.1命令要点拆解参数含义-sstandalone独立文档模式生成带完整 roff 头/尾结构的完整 man 文件而不是 fragment-f markdown输入格式为 Pandocs Markdown其扩展语法与通用 GFM 略有差异-t man输出格式为 roff man page-o指定输出文件名转换时需要注意由于使用了 Pandoc 特定的 Markdown 方言源稿中的标题层级、列表、加粗等写法需遵循Pandoc 的 Markdown 规范才能被正确映射为 roff 排版指令仓库在 README 中也明确要求编辑者先了解该格式约定。2.1 没有本地 Pandoc 时的备选路径若本机安装 Pandoc 有困难可使用 Pandoc 官方提供的在线转换器toman、standalonetrue的预置参数链接。但官方在线转换器的输出存在一个已知陷阱复制结果到本地文件时部分头部信息会丢失因此必须小心——既不要覆盖文件已有的开头头部也不要截掉结尾的尾部头部。稳妥起见仍建议以本地pandoc命令生成的产物为准。2.2 产物必须随源稿一并提交doc/README.md明确要求编辑完成后Markdown 源稿*.md与生成的 man 产物*.1都要提交二者是同步维护的一对文件缺一不可——源稿保证可维护性产物保证用户安装即用。三、手册正文的标准章节结构观察 doc/en/qbittorrent-nox.1.md91 行与 doc/en/qbittorrent.1.md82 行两个英文源稿可总结出 qBittorrent 手册统一的 roff 命名与章节模板% QBITTORRENT-NOX(1) 一行描述 % 空作者行 % 月份年份 # NAME # SYNOPSIS # DESCRIPTION # OPTIONS ## Options when adding new torrents # ENVIRONMENT # BUGS # AUTHORS头部三行%是 Pandoc man 输出所需的标题块对应 roff 的.TH紧随其后是手册标准小节NAME / SYNOPSIS程序名与调用形式。无头模式为qbittorrent-nox [options] [(filename | url)...]GUI 版为qbittorrent均支持--help、--versionDESCRIPTION介绍程序定位——基于 C/Qt、使用 libtorrent-rasterbar 实现、支持 Unicode、UPnP/NAT-PMP 端口映射、加密、FAST extension 与 PeX 等特性。qbittorrent-nox一节还会说明其默认由 Web UIhttp://localhost:8080默认用户名admin未设密码时每次启动在控制台打印临时随机密码控制OPTIONS全部命令行参数详见下一节ENVIRONMENT环境变量等价写法详见第五节BUGS / AUTHORS指向官方 bug 跟踪系统作者署名。四、手册收录的命令行参数清单两个手册源稿中 OPTIONS 部分的参数高度一致其中 GUI 版独有的--no-splash与--skip-dialogGUI 版添加种子时是否弹窗正是两类二进制的功能差异体现选项适用说明-h | --help全部显示帮助并退出-v | --version全部显示版本并退出--confirm-legal-notice全部确认法律声明配合无人值守启动--webui-portport全部修改 WebUI 端口--torrenting-portport全部修改 BT 传输端口--no-splashGUI禁用启动闪屏-d | --daemonnox以守护进程方式后台运行--profiledir全部将配置文件存放于指定目录--configurationname全部使用qBittorrent_name形式的独立配置目录--relative-fastresume全部改写 libtorrent fastresume 文件使文件路径相对于 profile 目录(filename | url)...全部直接下载传入的种子文件或链接4.1 添加新种子时的附加参数两个源稿还用三级小节Options when adding new torrents单独归纳了添加种子场景的选项--save-pathpath种子保存路径--add-stoppedtrue|false以运行还是停止状态添加--seed-mode种子模式只做种不上传数据--categoryname分配给指定分类分类不存在时自动创建--sequential按顺序下载文件--first-and-last优先下载首尾分片--skip-dialogtrue|false添加种子时是否弹出Add New Torrent对话框。4.2 源码侧的参数定义印证上述参数并非文档凭空撰写均可在命令行解析实现中逐一定位。参数解析集中在 src/app/cmdoptions.cpp布尔开关、整型参数分别由BoolOption、IntOption等选项类封装例如第 316319 行就声明了NO_SPLASH_OPTION {no-splash}、WEBUI_PORT_OPTION {webui-port}、TORRENTING_PORT_OPTION {torrenting-port}布尔值的取值判定isTrue()cmdoptions.cpp 第 6265 行只接受字面量1或大小写不敏感的true这与手册 ENVIRONMENT 一节的约定一致。五、环境变量等价写法源码级印证两个手册的 ENVIRONMENT 小节都记载了一条通用映射规则对名为parameter-name的选项环境变量名为QBT_PARAMETER_NAME全大写-替换为_标志类参数置为1或TRUE即表示开启。这一规则的实现位于 src/app/cmdoptions.cpp 第 97101 行的envVarName()return uQBT_ m_name.toString().toUpper().replace(u-, u_);即选项名webui-port→QBT_WEBUI_PORTno-splash→QBT_NO_SPLASH与文档描述完全一致。手册中给出的两个可直接执行的示例QBT_WEBUI_PORT8081 qbittorrent-nox # nox用环境变量改 WebUI 端口 QBT_NO_SPLASH1 qbittorrent # GUI用环境变量禁用闪屏手册同时强调了一条优先级规则命令行参数优先于环境变量。也就是说--webui-port8082与QBT_WEBUI_PORT8081同时出现时以命令行取值 8082 为准。六、多语言翻译流程与 CMake 安装规则将手册页翻译为新语言是doc/README.md着力说明的第二条主线。参考 doc/ru/已含俄语版两对源稿/产物可归纳出标准步骤在doc/下创建以语言代码命名的新子目录如doc/fr/将翻译好的文件放入该目录命名必须与英文版保持一致qbittorrent.1.mdqbittorrent.1、qbittorrent-nox.1.mdqbittorrent-nox.1把该语言代码追加到 dist/unix/CMakeLists.txt 的manPageLanguages列表中。6.1 CMake 中的实际安装逻辑dist/unix/CMakeLists.txt 第 2133 行展示了语言清单与安装细节set(manPageLanguages en ru ) foreach(manPageLanguage ${manPageLanguages}) install(FILES ${PROJECT_SOURCE_DIR}/doc/${manPageLanguage}/$IF:$BOOL:${GUI},qbittorrent.1,qbittorrent-nox.1 DESTINATION ${CMAKE_INSTALL_MANDIR}/$$NOT:$STREQUAL:${manPageLanguage},en:${manPageLanguage}/man1 COMPONENT doc ) endforeach()几点可从中读出的工程约束当前官方维护的语言是en 与 ru新增翻译需同步修改此清单否则不会进入安装产物安装哪个手册文件由构建目标决定构建GUI版时装qbittorrent.1构建nox无头版时装qbittorrent-nox.1安装目录遵循 man 惯例英文版装入mandir/man1其他语言版装入mandir/语言/man1如ru/man1对应第 2930 行注释中English man pages are installed into man1, while other languages into /man1的说明。七、维护自查清单结合全文给出手册维护者的最终检查要点格式源稿用 Pandocs Markdown 撰写保留首部%标题块与 NAME/SYNOPSIS/…/AUTHORS 标准小节转换用pandoc -s -f markdown -t man生成产物若走在线转换器复制输出时注意补齐丢失的头部、勿截断头尾提交*.md源稿与生成的*.1产物必须成对提交翻译新增语言需同时完成doc/lang/下的全部四个文件并在 dist/unix/CMakeLists.txt 的manPageLanguages注册语言代码一致性手册中的参数与 ENVIRONMENT 规则改动时同步核对 src/app/cmdoptions.cpp 中选项定义及envVarName()的命名映射确保文档、实现与安装三处不脱节。【免费下载链接】qBittorrentqBittorrent BitTorrent client项目地址: https://gitcode.com/GitHub_Trending/qb/qBittorrent创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考