Podman 手册页Man Page编写规范全解析从 MANPAGE_SYNTAX 到自动化校验【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podman导读Podman 的命令行体系庞大且命令数量众多为了保证每一条命令的手册页man page格式统一、可读性强、便于自动化校验与多平台渲染Podman 项目在 docs/MANPAGE_SYNTAX.md 中沉淀了一套完整的编写规范。本文以该规范文件为骨架结合仓库内真实的 man page 源文件位于 docs/source/markdown与 CI 校验脚本hack/man-page-checker、hack/man-page-table-check逐节解读章节结构、排版格式、OPTIONS 写法、示例与链接规则并演示如何从零写出一篇通过全部检查的 Podman man page。读完本文读者将掌握 Podman 文档贡献的完整工作流与格式细节。一、为什么需要一套 man page 语法规范Podman 拥有 40 个子命令run、create、ps、pod、volume、network、system等每个命令的手册页都遵循同一套 Markdown 源格式。统一的格式带来三重收益一致性用户无论查看哪条命令的手册章节顺序NAME → SYNOPSIS → DESCRIPTION → OPTIONS → EXAMPLES → SEE ALSO都完全一致降低学习成本可渲染性同一份 Markdown 源需要同时被go-md2man生成 roff 格式的 man page、Sphinx生成 HTML 文档等多种工具消费格式必须严格遵守约定详见 docs/README.md 的构建说明可校验性仓库内置的检查脚本可以自动比对每个文件是否符合规范例如hack/man-page-checker会核对 NAME 与文件名、SYNOPSIS 与--help输出、父命令表格中的描述文本等。每篇 man page 的源文件以% podman-command 1作为首行%后是命令名与手册章节号随后按固定顺序组织各章节。二、章节结构与逐节规范一篇合规的 man page 由以下章节组成顺序固定、缺一不可1. NAME命令名与一句话描述NAME 章节给出命令名与短描述格式为podman\-command - short description注意命令名中的连字符需要转义为\-。## NAME podman\-command - short description该章节有一个隐藏的硬性要求NAME 中的命令名必须与文件名一致。hack/man-page-checker的第一轮检查正是做这件事——它对每个*.1.md文件提取 NAME 章节第一个名字并与文件名比对name$(grep -E -A1 ^#* NAME $md | tail -1 | awk {print $1} | tr -d \\\\) expect$(basename $md .1.md)若不一致如podman-info.1.md的 NAME 写成了podman-system-info会直接报错。同时检查脚本还会把podman-foo.1.md的 NAME 描述与 docs/source/markdown/podman.1.md 命令总表中的描述文本进行比对要求二者完全一致仅容忍末尾句号差异确保父命令表格与子命令手册页不产生漂移。2. SYNOPSIS命令用法骨架SYNOPSIS 展示命令结构。规范要求命令名用**podman command**加粗可选参数用[*optional*]方括号 斜体表示必选参数用*mandatory value*斜体表示若同一命令有两种等价写法两种都必须展示若存在二选一或多个必选值用|竖线分隔竖线前后必须各留一个空格以保证可读性。规范给出了一组典型的组合模式只有可选参数**podman command** [*optional*] *mandatory value* **podman subcommand command** [*optional*] *mandatory value*多个必选值二选一竖线前后留空格**podman command** [*optional*] *value1* | *value2* **podman subcommand command** [*optional*] *value1* | *value2*可选值跟在必选值之后**podman command** [*optional*] *value1* | *value2* [*optional*]接受任意数量值用...表示可重复**podman command** [*optional*] *value* [*value* ...]OPTIONS 占位约定许多 man page 会包含--all/-a或--latest/-l这类无需容器名/ID 的选项。此时 SYNOPSIS 中依然保留[*options*]且规范明确指出即便这些选项不需要container name或ID参数SYNOPSIS 中的container参数也不应用方括号括起来同时必须在 OPTIONS 章节相应 OPTION 的描述中IMPORTANT 段落注明IMPORTANT: This OPTION does not need a container name or ID as input argument.。真实示例来自 podman.1.md## SYNOPSIS **podman** [*options*] *command*而 podman-container-prune.1.md 展示了“无必选参数”的写法## SYNOPSIS **podman container prune** [*options*]hack/man-page-checker的第三轮检查会强制 SYNOPSIS 中的命令名与文件名一致并禁止 SYNOPSIS 中出现大写字符约定用*小写斜体*而非UPPER CASE还会在存在bin/podman时把 SYNOPSIS 与podman foo --help的 Usage 输出做比对例如 man page 中的[*options*]应对应--help中的[options]/[flags]从源头上保证手册与 CLI 帮助信息不脱节。3. DESCRIPTION命令描述DESCRIPTION 章节必须以podman command开头命令名加粗确保全仓库描述风格统一Example for the first sentence:podman commandis an example command.其他规则文中引用本仓库其他命令、配置文件时必须链接到对应 man page非 Podman 命令不得链接。例如规范原文给出的句式Usepodman-runorcontainers.conf(5)for the problem.外部项目的containers.conf(5)属于非 Podman 手册不建立仓库内链接如果命令仅能由 root 运行必须在此说明如果命令、OPTION 或其他内容在远程客户端remote client或与其他命令/OPTION 组合时不可用必须在相应位置末尾追加句式IMPORTANT: This command/OPTION/content is not available with the command/OPTION/content/on the remote Podman client.命令级写在 DESCRIPTION 中OPTION 级写在该 OPTION 的描述里禁止使用人称代词尤其是youH2 标题##之后不得换行另起空行正文直接跟在标题行之后。在 podman-generate-systemd.1.md 中可以同时看到“命令名开头 远程客户端注意事项”的典型写法## DESCRIPTION DEPRECATED: Note: **podman generate systemd** is deprecated. We recommend using Quadlet files when running Podman containers or pods under systemd. ...4. OPTIONS全部选项的详述OPTIONS 是 man page 中最长也最讲究的章节。核心规则如下所有 flag 统一称 OPTIONS禁止使用 flags 一词每个 OPTION 使用 H4 标题####按其完整拼写按字母顺序排序每个 OPTION 都要在其标题下方做最充分的解释若引用其他 Podman man page 或仓库中的 OPTION必须链接到对应锚点例如规范原文Usepodman-generate-systemd(1) 的 --new 选项for the problem若 OPTION 有默认参数必须在描述中说明默认参数相关的句子与 IMPORTANT 句子各占一行且 IMPORTANT 句若存在需放在倒数第二句默认值句紧随其后或按序排列选项在文本中出现时保持原样书写如--exit不得改变格式。长短选项的书写长选项在前短选项用逗号分隔如#### **--version**, **-v**。布尔选项不枚举 true/false默认值按普通默认值格式展示如 The default isfalse.。规范中的示例#### **--version**, **-v** OPTIONS can be put after the command in two different ways. ... The default is **false**. *IMPORTANT: This OPTION is not available with the remote Podman client.*接受枚举参数的 OPTION等号后参数用加粗默认值或斜体非默认值标记默认值必须位于第一个位置。规范示例#### **--answer**, **-a****active** | *disable*其含义是--answer有两种合法写法--answer active/-a active等active为默认值故加粗。若枚举值不超过三个直接列在等号后如--statusgood|better|best若参数数量超过三个则不得在等号后罗列必须改用表格以保证可读性。规范给出的表格样式为ArgumentDescriptionexample oneThis argument is the default argument if the OPTION is not specified.example twoIf one refers to a command, one should useboldmarks.example threeExample: In combination withpodman commandhighly effective.example fourExample: Can be combined with--exit.example fiveThe fifth description表格规范细节默认参数必须作为表格第一行表格内容默认左对齐若影响理解可调整对齐方式。真实仓库案例见 podman-container-prune.1.md 的 --filter 选项它使用三行表格列举annotation、label、until三个过滤器并在表格后用多段文字详解label!/annotation!的否定语义与 AND 组合规则、until支持的时间格式。无默认值的自由参数 OPTION等号后跟一个斜体单词示意参数含义例如#### **--problem***problem*。这类 OPTION 即使写成--problem等号后为空也不会报错但选项会被静默忽略——规范明确要求将这一行为告知用户。表格与列表的选用原则当多个参数各自需要独立定义时用表格当参数无需逐一定义、一段文字即可说明时用列表规范原文给出的参考是podman-commit(1) 的 --change 选项。5. SUBCHAPTER子章节的排版规则对于 man page 中独立成节的子章节SUBCHAPTER前述格式规则全部适用但对段落和表格的使用没有额外限制。字符串或数字可以用反引号高亮所有路径都必须用反引号高亮如$HOME/.config/containers/storage.conf。反引号的使用边界只有不属于前面各类别的字符才能高亮包括标题本身——规范明确不鼓励高亮 OPTION 或命令名它们应使用加粗/斜体等既定标记而非反引号。子标题SUBHEADING用 H3 展示### SUBHEADING Text for SUBHEADINGS.6. EXAMPLES示例区块所有示例集中在 EXAMPLES 章节位于每篇 man page 的末尾。每个示例独占一个代码框代码框从最后一行的行首开始、到最后一行的行尾结束首尾不允许空白行命令前的$表示普通用户可运行#表示仅 root 可运行框内注释以###开头。规范原示例Description of the EXAMPLEExample comment$ podman command $ podman command -o $ cat $HOME/Dockerfile | podman command --optionDescription of the EXAMPLE two# podman command --statusbetter真实示例见 podman-container-prune.1.md 的 EXAMPLES 章节它用三个代码框分别演示普通清理、-f免确认清理、--filter until10m按时间清理并完整保留了真实命令输出删除的容器 ID 列表这正是规范所要求的“每个示例一个框、说明在前、命令与输出原样保留”。7. SEE ALSO交叉引用清单SEE ALSO 必须列出文中提到的所有命令含带 OPTIONS 的命令与配置文件Podman 自己的命令、带 OPTIONS 的命令及配置文件必须链接同一命令即使被多次提到带不同 OPTION也只需链接一次非 Podman 的命令、OPTION、配置文件只需提及名称如subuid(5)、containers-storage.conf(5)不建立仓库内链接外部项目的手册在真实仓库中通常以纯文本命令名(章节)形式给出。规范原文示例**[podman(1)](https://link.gitcode.com/i/762a6e4b94ad78b7ae49f2a2562605e2)**, **podman-run(1)**, **podman-create(1)**真实案例podman-container-prune.1.md 的 SEE ALSO 链接了podman(1)与podman-ps(1)。8. HISTORY变更历史HISTORY 通常记录变更日期、变更内容与提交者。规范强调大多数 man page 并不维护这份记录允许省略。若存在格式如December 2021, Originally compiled by Alexander Richter exampleredhat.com真实的 podman.1.md 的 HISTORY 记载Dec 2016, Originally compiled by Dan Walsh dwalshredhat.com。9. 文件结尾规范明确要求每篇 man page 必须以一个空行结尾Every manpage should end with an empty line.。三、文档源文件组织与预处理机制除了写作格式贡献者还需要理解 man page 源文件在仓库中的组织方式详见 docs/README.md 与 docs/source/markdown/options/README.md源文件位置docs/source/markdown 存放所有*.1.md源文件*.1.md.in是需要预处理的模板文件docs/source/markdown/links 存放.so别名文件构建产物输出到docs/build/man同时为 Linux / darwin / windows 平台生成不同格式。公共选项去重docs/source/markdown/options 目录存放多个 man page 共用的选项描述片段每个文件一个选项。*.md.in模板通过option foo语法引入这些片段hack/markdown-preprocessPython 脚本需在 readthedocs.io 上运行负责在make docs时将其展开为最终.md文件。条件与占位符预处理支持 if variable / else / endif 条件如区分 Quadlet 场景的is_quadlet变量、text for pods|text for containers的 pod/container 差异化文本选择以及subcommand/fullsubcommand子命令名占位符。由于选项片段会被多个命令复用规范对 man page 格式的统一要求在这里就变得更加重要——任何格式瑕疵都会被复制到几十个页面中。渲染限制预处理禁止在一行内同时出现行首与行尾的三反引号会导致编译后的 man page 损坏代码块必须把三个反引号独立成行。四、CI 自动化校验让规范成为可执行的检查规范的价值在于被自动化执行。仓库提供了两个关键检查脚本它们构成了 man page 的“静态检查层”1. hack/man-page-checkerBash 脚本核心逻辑见其 Pass 1~3Pass 1逐文件比对NAME与文件名并处理podman-auto-update、podman system hyperv-prep等连字符特例Pass 2比对子命令 NAME 描述与父命令总表中的描述文本解析podman.1.md命令表格的对应列容忍句号差异并排除podman-remotePass 3解析SYNOPSIS首行校验命令名与文件名一致、无大写字符存在编译产物时进一步调用cmd --help将[*options*]与[flags]、参数占位符等进行规范化比对仅--verbose输出详细差异暂不阻塞。2. hack/man-page-table-checkPerl 脚本针对go-md2man处理表格时的已知 bug——Markdown 表格中若出现星号等特殊字符、竖线错位、或首列超过 31 个字符会产生损坏的 roff 输出。该脚本对docs/build/man下每个 groff 文件调用man -l渲染检查表格是否出现空单元格若有则给出修复指引make -C docs clean; make docs; make docs之后重跑。这与 MANPAGE_SYNTAX 中“表格内容左对齐、默认参数置首行”的写作约定相互配合——在写作时遵守规范才能在编译与检查时零事故。五、实战写一篇合规 man page 的 Checklist结合规范与上述源码证据编写/修改一篇 Podman man page 时建议按以下清单逐项自查文件头首行为% podman-command 1NAMEpodman\-command - 一句话描述命令名与文件名一致描述与父命令表格一致SYNOPSIS命令名加粗[*optional*]与*mandatory*占位符使用正确二选一值用带空格的|分隔重复参数用[ *value* ... ]无大写字母DESCRIPTION以加粗命令名开头提及的本仓库命令/配置已链接非 Podman 命令不链接无you等代词H2 后无空行root-only 与 remote-client 限制已用 IMPORTANT 句式标注OPTIONS按字母序排列每个选项独立 H4布尔选项说明默认值如 The default isfalse.枚举参数 ≤3 个直接列在等号后、3 个用表格且默认值置首行无默认值的自由参数用*word*形式并说明空值行为引用其他页面选项时用带锚点的链接EXAMPLES每个示例一个代码框$/#前缀语义正确框内注释用###框首尾无空行SEE ALSO所有提到的命令与配置文件均已列出Podman 命令已链接且去重HISTORY如有则按日期, 提交人 email格式无则省略结尾文件末尾保留一个空行验证运行make docs构建再依次执行hack/man-page-checker与hack/man-page-table-check确认零错误。构建命令来自 docs/README.md 的 Local Testing 一节标准 man page 用make docs产物在docs/build/manHTML 版用make html需安装python3-sphinx python3-recommonmark及sphinx-markdown-tables myst_parser预览可用python -m http.server 8000 --directory build/html。六、总结M ANPAGE_SYNTAX.md 篇幅不长却精确锁定了 Podman 手册体系的每一个细节从章节顺序、加粗/斜体/反引号三类标记的适用边界到 OPTIONS 默认值的排版、表格与列表的选用阈值、示例框的$/#语义再到 SEE ALSO 的链接去重规则。它既是人类作者的写作指南也是 hack/man-page-checker 等 CI 脚本的事实依据。理解并遵循这份规范不仅能让贡献的手册页一次通过检查也能让用户在man podman、man podman-run乃至在线文档中获得完全一致、高度可信的使用指引。对于希望深入 Podman 文档体系的开发者而言从 docs/source/markdown/podman.1.md 与 docs/source/markdown/options/README.md 入手研读是成本最低的进阶路径。【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Podman 手册页（Man Page）编写规范全解析：从 MANPAGE_SYNTAX 到自动化校验
Podman 手册页Man Page编写规范全解析从 MANPAGE_SYNTAX 到自动化校验【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podman导读Podman 的命令行体系庞大且命令数量众多为了保证每一条命令的手册页man page格式统一、可读性强、便于自动化校验与多平台渲染Podman 项目在 docs/MANPAGE_SYNTAX.md 中沉淀了一套完整的编写规范。本文以该规范文件为骨架结合仓库内真实的 man page 源文件位于 docs/source/markdown与 CI 校验脚本hack/man-page-checker、hack/man-page-table-check逐节解读章节结构、排版格式、OPTIONS 写法、示例与链接规则并演示如何从零写出一篇通过全部检查的 Podman man page。读完本文读者将掌握 Podman 文档贡献的完整工作流与格式细节。一、为什么需要一套 man page 语法规范Podman 拥有 40 个子命令run、create、ps、pod、volume、network、system等每个命令的手册页都遵循同一套 Markdown 源格式。统一的格式带来三重收益一致性用户无论查看哪条命令的手册章节顺序NAME → SYNOPSIS → DESCRIPTION → OPTIONS → EXAMPLES → SEE ALSO都完全一致降低学习成本可渲染性同一份 Markdown 源需要同时被go-md2man生成 roff 格式的 man page、Sphinx生成 HTML 文档等多种工具消费格式必须严格遵守约定详见 docs/README.md 的构建说明可校验性仓库内置的检查脚本可以自动比对每个文件是否符合规范例如hack/man-page-checker会核对 NAME 与文件名、SYNOPSIS 与--help输出、父命令表格中的描述文本等。每篇 man page 的源文件以% podman-command 1作为首行%后是命令名与手册章节号随后按固定顺序组织各章节。二、章节结构与逐节规范一篇合规的 man page 由以下章节组成顺序固定、缺一不可1. NAME命令名与一句话描述NAME 章节给出命令名与短描述格式为podman\-command - short description注意命令名中的连字符需要转义为\-。## NAME podman\-command - short description该章节有一个隐藏的硬性要求NAME 中的命令名必须与文件名一致。hack/man-page-checker的第一轮检查正是做这件事——它对每个*.1.md文件提取 NAME 章节第一个名字并与文件名比对name$(grep -E -A1 ^#* NAME $md | tail -1 | awk {print $1} | tr -d \\\\) expect$(basename $md .1.md)若不一致如podman-info.1.md的 NAME 写成了podman-system-info会直接报错。同时检查脚本还会把podman-foo.1.md的 NAME 描述与 docs/source/markdown/podman.1.md 命令总表中的描述文本进行比对要求二者完全一致仅容忍末尾句号差异确保父命令表格与子命令手册页不产生漂移。2. SYNOPSIS命令用法骨架SYNOPSIS 展示命令结构。规范要求命令名用**podman command**加粗可选参数用[*optional*]方括号 斜体表示必选参数用*mandatory value*斜体表示若同一命令有两种等价写法两种都必须展示若存在二选一或多个必选值用|竖线分隔竖线前后必须各留一个空格以保证可读性。规范给出了一组典型的组合模式只有可选参数**podman command** [*optional*] *mandatory value* **podman subcommand command** [*optional*] *mandatory value*多个必选值二选一竖线前后留空格**podman command** [*optional*] *value1* | *value2* **podman subcommand command** [*optional*] *value1* | *value2*可选值跟在必选值之后**podman command** [*optional*] *value1* | *value2* [*optional*]接受任意数量值用...表示可重复**podman command** [*optional*] *value* [*value* ...]OPTIONS 占位约定许多 man page 会包含--all/-a或--latest/-l这类无需容器名/ID 的选项。此时 SYNOPSIS 中依然保留[*options*]且规范明确指出即便这些选项不需要container name或ID参数SYNOPSIS 中的container参数也不应用方括号括起来同时必须在 OPTIONS 章节相应 OPTION 的描述中IMPORTANT 段落注明IMPORTANT: This OPTION does not need a container name or ID as input argument.。真实示例来自 podman.1.md## SYNOPSIS **podman** [*options*] *command*而 podman-container-prune.1.md 展示了“无必选参数”的写法## SYNOPSIS **podman container prune** [*options*]hack/man-page-checker的第三轮检查会强制 SYNOPSIS 中的命令名与文件名一致并禁止 SYNOPSIS 中出现大写字符约定用*小写斜体*而非UPPER CASE还会在存在bin/podman时把 SYNOPSIS 与podman foo --help的 Usage 输出做比对例如 man page 中的[*options*]应对应--help中的[options]/[flags]从源头上保证手册与 CLI 帮助信息不脱节。3. DESCRIPTION命令描述DESCRIPTION 章节必须以podman command开头命令名加粗确保全仓库描述风格统一Example for the first sentence:podman commandis an example command.其他规则文中引用本仓库其他命令、配置文件时必须链接到对应 man page非 Podman 命令不得链接。例如规范原文给出的句式Usepodman-runorcontainers.conf(5)for the problem.外部项目的containers.conf(5)属于非 Podman 手册不建立仓库内链接如果命令仅能由 root 运行必须在此说明如果命令、OPTION 或其他内容在远程客户端remote client或与其他命令/OPTION 组合时不可用必须在相应位置末尾追加句式IMPORTANT: This command/OPTION/content is not available with the command/OPTION/content/on the remote Podman client.命令级写在 DESCRIPTION 中OPTION 级写在该 OPTION 的描述里禁止使用人称代词尤其是youH2 标题##之后不得换行另起空行正文直接跟在标题行之后。在 podman-generate-systemd.1.md 中可以同时看到“命令名开头 远程客户端注意事项”的典型写法## DESCRIPTION DEPRECATED: Note: **podman generate systemd** is deprecated. We recommend using Quadlet files when running Podman containers or pods under systemd. ...4. OPTIONS全部选项的详述OPTIONS 是 man page 中最长也最讲究的章节。核心规则如下所有 flag 统一称 OPTIONS禁止使用 flags 一词每个 OPTION 使用 H4 标题####按其完整拼写按字母顺序排序每个 OPTION 都要在其标题下方做最充分的解释若引用其他 Podman man page 或仓库中的 OPTION必须链接到对应锚点例如规范原文Usepodman-generate-systemd(1) 的 --new 选项for the problem若 OPTION 有默认参数必须在描述中说明默认参数相关的句子与 IMPORTANT 句子各占一行且 IMPORTANT 句若存在需放在倒数第二句默认值句紧随其后或按序排列选项在文本中出现时保持原样书写如--exit不得改变格式。长短选项的书写长选项在前短选项用逗号分隔如#### **--version**, **-v**。布尔选项不枚举 true/false默认值按普通默认值格式展示如 The default isfalse.。规范中的示例#### **--version**, **-v** OPTIONS can be put after the command in two different ways. ... The default is **false**. *IMPORTANT: This OPTION is not available with the remote Podman client.*接受枚举参数的 OPTION等号后参数用加粗默认值或斜体非默认值标记默认值必须位于第一个位置。规范示例#### **--answer**, **-a****active** | *disable*其含义是--answer有两种合法写法--answer active/-a active等active为默认值故加粗。若枚举值不超过三个直接列在等号后如--statusgood|better|best若参数数量超过三个则不得在等号后罗列必须改用表格以保证可读性。规范给出的表格样式为ArgumentDescriptionexample oneThis argument is the default argument if the OPTION is not specified.example twoIf one refers to a command, one should useboldmarks.example threeExample: In combination withpodman commandhighly effective.example fourExample: Can be combined with--exit.example fiveThe fifth description表格规范细节默认参数必须作为表格第一行表格内容默认左对齐若影响理解可调整对齐方式。真实仓库案例见 podman-container-prune.1.md 的 --filter 选项它使用三行表格列举annotation、label、until三个过滤器并在表格后用多段文字详解label!/annotation!的否定语义与 AND 组合规则、until支持的时间格式。无默认值的自由参数 OPTION等号后跟一个斜体单词示意参数含义例如#### **--problem***problem*。这类 OPTION 即使写成--problem等号后为空也不会报错但选项会被静默忽略——规范明确要求将这一行为告知用户。表格与列表的选用原则当多个参数各自需要独立定义时用表格当参数无需逐一定义、一段文字即可说明时用列表规范原文给出的参考是podman-commit(1) 的 --change 选项。5. SUBCHAPTER子章节的排版规则对于 man page 中独立成节的子章节SUBCHAPTER前述格式规则全部适用但对段落和表格的使用没有额外限制。字符串或数字可以用反引号高亮所有路径都必须用反引号高亮如$HOME/.config/containers/storage.conf。反引号的使用边界只有不属于前面各类别的字符才能高亮包括标题本身——规范明确不鼓励高亮 OPTION 或命令名它们应使用加粗/斜体等既定标记而非反引号。子标题SUBHEADING用 H3 展示### SUBHEADING Text for SUBHEADINGS.6. EXAMPLES示例区块所有示例集中在 EXAMPLES 章节位于每篇 man page 的末尾。每个示例独占一个代码框代码框从最后一行的行首开始、到最后一行的行尾结束首尾不允许空白行命令前的$表示普通用户可运行#表示仅 root 可运行框内注释以###开头。规范原示例Description of the EXAMPLEExample comment$ podman command $ podman command -o $ cat $HOME/Dockerfile | podman command --optionDescription of the EXAMPLE two# podman command --statusbetter真实示例见 podman-container-prune.1.md 的 EXAMPLES 章节它用三个代码框分别演示普通清理、-f免确认清理、--filter until10m按时间清理并完整保留了真实命令输出删除的容器 ID 列表这正是规范所要求的“每个示例一个框、说明在前、命令与输出原样保留”。7. SEE ALSO交叉引用清单SEE ALSO 必须列出文中提到的所有命令含带 OPTIONS 的命令与配置文件Podman 自己的命令、带 OPTIONS 的命令及配置文件必须链接同一命令即使被多次提到带不同 OPTION也只需链接一次非 Podman 的命令、OPTION、配置文件只需提及名称如subuid(5)、containers-storage.conf(5)不建立仓库内链接外部项目的手册在真实仓库中通常以纯文本命令名(章节)形式给出。规范原文示例**[podman(1)](https://link.gitcode.com/i/762a6e4b94ad78b7ae49f2a2562605e2)**, **podman-run(1)**, **podman-create(1)**真实案例podman-container-prune.1.md 的 SEE ALSO 链接了podman(1)与podman-ps(1)。8. HISTORY变更历史HISTORY 通常记录变更日期、变更内容与提交者。规范强调大多数 man page 并不维护这份记录允许省略。若存在格式如December 2021, Originally compiled by Alexander Richter exampleredhat.com真实的 podman.1.md 的 HISTORY 记载Dec 2016, Originally compiled by Dan Walsh dwalshredhat.com。9. 文件结尾规范明确要求每篇 man page 必须以一个空行结尾Every manpage should end with an empty line.。三、文档源文件组织与预处理机制除了写作格式贡献者还需要理解 man page 源文件在仓库中的组织方式详见 docs/README.md 与 docs/source/markdown/options/README.md源文件位置docs/source/markdown 存放所有*.1.md源文件*.1.md.in是需要预处理的模板文件docs/source/markdown/links 存放.so别名文件构建产物输出到docs/build/man同时为 Linux / darwin / windows 平台生成不同格式。公共选项去重docs/source/markdown/options 目录存放多个 man page 共用的选项描述片段每个文件一个选项。*.md.in模板通过option foo语法引入这些片段hack/markdown-preprocessPython 脚本需在 readthedocs.io 上运行负责在make docs时将其展开为最终.md文件。条件与占位符预处理支持 if variable / else / endif 条件如区分 Quadlet 场景的is_quadlet变量、text for pods|text for containers的 pod/container 差异化文本选择以及subcommand/fullsubcommand子命令名占位符。由于选项片段会被多个命令复用规范对 man page 格式的统一要求在这里就变得更加重要——任何格式瑕疵都会被复制到几十个页面中。渲染限制预处理禁止在一行内同时出现行首与行尾的三反引号会导致编译后的 man page 损坏代码块必须把三个反引号独立成行。四、CI 自动化校验让规范成为可执行的检查规范的价值在于被自动化执行。仓库提供了两个关键检查脚本它们构成了 man page 的“静态检查层”1. hack/man-page-checkerBash 脚本核心逻辑见其 Pass 1~3Pass 1逐文件比对NAME与文件名并处理podman-auto-update、podman system hyperv-prep等连字符特例Pass 2比对子命令 NAME 描述与父命令总表中的描述文本解析podman.1.md命令表格的对应列容忍句号差异并排除podman-remotePass 3解析SYNOPSIS首行校验命令名与文件名一致、无大写字符存在编译产物时进一步调用cmd --help将[*options*]与[flags]、参数占位符等进行规范化比对仅--verbose输出详细差异暂不阻塞。2. hack/man-page-table-checkPerl 脚本针对go-md2man处理表格时的已知 bug——Markdown 表格中若出现星号等特殊字符、竖线错位、或首列超过 31 个字符会产生损坏的 roff 输出。该脚本对docs/build/man下每个 groff 文件调用man -l渲染检查表格是否出现空单元格若有则给出修复指引make -C docs clean; make docs; make docs之后重跑。这与 MANPAGE_SYNTAX 中“表格内容左对齐、默认参数置首行”的写作约定相互配合——在写作时遵守规范才能在编译与检查时零事故。五、实战写一篇合规 man page 的 Checklist结合规范与上述源码证据编写/修改一篇 Podman man page 时建议按以下清单逐项自查文件头首行为% podman-command 1NAMEpodman\-command - 一句话描述命令名与文件名一致描述与父命令表格一致SYNOPSIS命令名加粗[*optional*]与*mandatory*占位符使用正确二选一值用带空格的|分隔重复参数用[ *value* ... ]无大写字母DESCRIPTION以加粗命令名开头提及的本仓库命令/配置已链接非 Podman 命令不链接无you等代词H2 后无空行root-only 与 remote-client 限制已用 IMPORTANT 句式标注OPTIONS按字母序排列每个选项独立 H4布尔选项说明默认值如 The default isfalse.枚举参数 ≤3 个直接列在等号后、3 个用表格且默认值置首行无默认值的自由参数用*word*形式并说明空值行为引用其他页面选项时用带锚点的链接EXAMPLES每个示例一个代码框$/#前缀语义正确框内注释用###框首尾无空行SEE ALSO所有提到的命令与配置文件均已列出Podman 命令已链接且去重HISTORY如有则按日期, 提交人 email格式无则省略结尾文件末尾保留一个空行验证运行make docs构建再依次执行hack/man-page-checker与hack/man-page-table-check确认零错误。构建命令来自 docs/README.md 的 Local Testing 一节标准 man page 用make docs产物在docs/build/manHTML 版用make html需安装python3-sphinx python3-recommonmark及sphinx-markdown-tables myst_parser预览可用python -m http.server 8000 --directory build/html。六、总结M ANPAGE_SYNTAX.md 篇幅不长却精确锁定了 Podman 手册体系的每一个细节从章节顺序、加粗/斜体/反引号三类标记的适用边界到 OPTIONS 默认值的排版、表格与列表的选用阈值、示例框的$/#语义再到 SEE ALSO 的链接去重规则。它既是人类作者的写作指南也是 hack/man-page-checker 等 CI 脚本的事实依据。理解并遵循这份规范不仅能让贡献的手册页一次通过检查也能让用户在man podman、man podman-run乃至在线文档中获得完全一致、高度可信的使用指引。对于希望深入 Podman 文档体系的开发者而言从 docs/source/markdown/podman.1.md 与 docs/source/markdown/options/README.md 入手研读是成本最低的进阶路径。【免费下载链接】podmanPodman: A tool for managing OCI containers and pods.项目地址: https://gitcode.com/gh_mirrors/po/podman创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
