用常用示例写出简短的命令说明页面

## 先查找是否已有页面，再按可用的系统决定存放位置 创建任何内容之前，先在所有原文和翻译页面树中搜索该命令。如果页面已存在，就编辑现有页面，不要创建重复页面。如果页面不存在，则确定所记录的语法实际上在哪些环境中可用。 - 只有当相同语法至少可在 2 个平台上使用时，才将命令放入共用目录。 - 仅在 1 个平台上可用的命令应放入该平台的目录。 - 英文页面放在主页面树中，翻译页面放在具有相同平台路径的特定语言环境页面树中。 - 文件名使用小写，除非平台特定策略要求在页面标题或调用方式中保留命令的规范大小写。 不要根据命令的名声或名称选择目录。应先验证其支持的平台和语法。 ## 保持页面简短，把标题和说明放在示例前面 将每个页面编写为小型 Markdown 参考页，并严格遵循以下顺序： 1. 放置 1 个 H1；命令名应与文件名一致，但如果仓库允许，可忽略大小写差异。 2. 放置引用块形式的说明，最好为 1 行或 2 行。 3. 放置必需的“更多信息”行，其中包含用尖括号括起的上游 URL。 4. 放置实用示例；每个示例先用祈使语气的项目符号说明，再另起一行放置内联代码格式的命令。 5. 在文件末尾保留换行符。 默认使用 5 个示例，且绝不能超过 8 个。说明与命令之间以及各示例之间都要留 1 个空行。页面内容中不要使用粗体、斜体或装饰性 Markdown。 ## 选择能解决最常见任务的示例 选择能够解决最常见实际任务的示例。说明应使用祈使语气，例如“列出文件”，而不是第三人称陈述，例如“该命令会列出文件”。保持简短并以操作为中心，不要解释通用的操作系统概念。 对照命令手册、内置帮助或官方文档验证每个示例。保留文档规定的选项与参数间距；除非命令明确要求其他形式，否则使用 `--option arg`。 如果相应调用方式存在，应将“显示帮助”和“显示版本”依次作为最后 2 个示例。它们的优先级较低，因此当需要加入更实用的示例且会超出页面上限时，可以省略其中 1 个。 ## 用双花括号标出需要用户替换的部分 用双花括号包裹可替换值。始终按照含义使用以下占位符形式： - 文件系统输入使用 `{{path/to/file}}`、`{{path/to/directory}}` 和 `{{filename}}`； - 多个参数使用 `{{file1 file2 ...}}`； - 备选项使用 `{{option1|option2}}`； - 数值范围使用 `{{1..5}}`，通配符模式使用 `{{*.ext}}`； - 等效的短选项和长选项使用 `{{[-v|--verbose]}}`； - 成组标志使用 `{{[-it|--interactive --tty]}}`。 如果短形式和长形式都存在，应同时显示两者。绝不要臆造短形式：版本标志和其他常见选项会因命令而异。不要嵌套占位符，也不要用单花括号或方括号替代规定的双花括号语法。 按键使用尖括号表示：`<a>`、`<Enter>`、`<Space>`、`<Ctrl>`、`<Alt>` 和 `<Shift>`。组合键使用空格，例如 `<Ctrl c>`；按键序列使用相邻的分组，例如 `<Esc><u>`。 ## 确认链接能打开后，链接到官方手册 每个页面都必须链接到更多信息。优先使用命令的官方手册、项目文档、持续维护的手册页服务或平台厂商文档。 接受链接前，应跟随重定向并确认最终响应成功。不要依赖仅仅看起来合理的 URL。将尖括号链接放在专用的“更多信息”行中；如果存在主要来源，应避免使用宣传性或非官方来源。 使用相同的权威来源确认命令名、选项形式、参数间距、平台行为、帮助语法和版本语法。 ## 按 Windows 等各系统的习惯书写路径和变量 对于 Windows 命令页面，除非仓库策略另有规定，否则文件名使用小写，但在 H1 和示例中保留命令的规范大小写。路径占位符使用反斜杠。 环境变量应采用所记录 shell 的语法：传统命令解释器使用 `%VARIABLE%`，PowerShell 使用 `$Env:VARIABLE`。面向 PowerShell 的示例必须同时适用于受支持的最旧版本和当前版本，除非页面声明了更窄的适用范围。 对于其他平台，应遵循其原生的路径、shell、环境变量和选项约定。只有当所示命令语法确实可移植时，共享页面才有效。 ## 为命令的别名和子命令分别建立页面 如果仓库提供别名辅助工具，应使用该工具创建别名页面。说明该命令是别名，链接到上游信息，并提供 1 个用于打开原始命令参考页面的示例。通过同一辅助工具保持翻译后的别名页面同步，不要单独编辑其生成结构。 对于包含子命令的命令，如果代表性子命令有单独页面，应在父页面说明中提及它们。为每个有文档记录的子命令创建各自的连字符命名页面，并加入 1 个用于打开相应子命令参考页的示例。 不要在父页面中塞入本应放在各自页面中的详细子命令工作流程。 ## 翻译页面时不改动命令和页面结构 只有在英文页面存在后才进行翻译。保持相同的示例结构、平台路径、命令和占位符。不要更改保留的示例域名；如果仓库策略有要求，占位符中的词语应保留源语言。 应用特定语言环境的写作规则，不要机械照搬英语语法。例如： - 中文应在拉丁文字及数字与中文之间添加空格，并使用全角标点符号。 - 法语的示例说明使用第三人称，并在有此要求的标点符号前添加空格。 - 西班牙语使用第三人称说明和推荐的本地化技术术语。 - 巴西葡萄牙语和欧洲葡萄牙语使用第三人称说明。 - 印度尼西亚语使用简洁的命令说明形式，不添加不必要的动词前缀。 使用与英文源页面相同的结构检查来验证翻译页面。 ## 在交给人审阅前，用检查工具检查页面 请求人工审查之前，对变更文件运行仓库的页面 linter。只有当变更内容或仓库策略要求时，才运行全树 lint。 从以下方面审查页面： - 标题与文件名一致； - 引用块说明简短，并包含有效的信息链接； - 有 5 个首选示例，且不超过 8 个； - 说明使用祈使语气，空行正确； - 选项形式经过验证，并使用双花括号占位符； - 平台目录正确，语法符合原生约定； - 如果包含帮助和版本示例，它们位于最后； - 没有装饰性格式； - 翻译遵循特定语言环境的规则； - 文件末尾有换行符。 如果可用，应使用仓库的维护脚本完成机械式的标题、链接、别名、交叉引用和命令更新。在进行大范围脚本变更前，优先使用 dry-run 模式。 ## 动笔前，把手册和相似页面交给 AI 在起草前提供依据，以降低 AI 成本并减少修改轮次。不要要求代理回忆约定，而应提供命令的帮助或手册输出、2 个或 3 个类似的已批准页面以及页面模板。 先检查现有页面。如果相关页面请求共享上下文，可以批量处理，但每个页面应单独审查。应撰写 5 个或 6 个高价值示例，而不是为了填满 8 个示例的上限。 在人工审查前运行 linter，避免格式错误占用审查者的注意力。成本节省必须来自更好的输入、复用和确定性验证，绝不能通过跳过来源验证或降低页面质量来实现。