概览
命令行帮助（通常通过 --help 提供）是获取
与用户的通信它提供了一种简写形式，用于提供更详细的
文档和功能发现。
指南
帮助文档可能会额外包含以下部分（如果需要）：
示例
本文档后面部分将详细介绍该示例的各个部分。
（请注意，blast 不是真实工具）。
Usage: blast [-f] [-s <scribble>] <command> [<args>]
Destroy the contents of <file>.
Options:
-f force, ignore minor errors. This description
is so long that it wraps to the next line.
-s <scribble> write <scribble> repeatedly
-v, --verbose say more. Defaults to $BLAST_VERBOSE.
Commands:
blow-up explosively separate
grind make smaller by many small cuts
help get help on other commands e.g. `blast help grind`
Examples:
Scribble 'abc' and then run |grind|.
$ blast -s 'abc' grind old.txt taxes.cp
Notes:
Use `blast help <command>` for details on [<args>] for a subcommand.
Error codes:
2 The blade is too dull.
3 Out of fuel.
常规布局和样式
如需了解符合这些要求的示例，请参阅上文。
有几个部分需要英语散文。也就是说，以适当的方式 使用美式英语拼写的英语语法的句子（与英式英语不同） 英语或其他）。在句子之间添加一个空格，并遵循“牛津” 英文逗号”样式。例如：“说明、示例和备注部分用英语撰写 散文。”
布局
- 每个部分由一个空白行分隔。
- 部分内容缩进两个空格。
- 单行内容将与标签在同一行上，以 1
用于分隔冒号和命令名称的空格。例如：“
Usage: blast <file>”。 - 多行部分将紧跟在标签之后（没有 空白行）。标签后面的每一行都会缩进两个空格。
- 除了选项、命令和命令外，所有输出均为单列文本 和错误代码，即两个列表。
- 使用空格进行缩进或对齐。不输出 Tab 字符。
- 设置 80 列文本换行。封装选项或命令说明时，请确保对齐 以说明开头的行（例如，大约 20 字符）。
样式
- 版块标题采用词首字母大写形式：第一个单词和最后一个单词的首字母大写。全部 除了冠词（a、an、the）、 连词（如、and、 But、or）和介词（如 on、in、with）。
- 简短说明片段（选项或命令中的第二列）从 包含小写字母，不一定是完整的句子。任何文本 简短说明之后，应该是完整的句子，在 fragment。
- 尽量确保每个部分的内容简洁明了。如有更多信息，请将用户引导至
在运行
--help时使用--verbose，或将其定向到完整版 文档。 - 描述性文本（段落）中允许使用 Unicode (UTF-8) 字符。通过 命令名称和用法文本将仅包含可移植的 ASCII 字符 （不含 Unicode）。
用法
必须提供，其中包含“Usage:”标头。
Usage: blast [-f] [-s <scribble>] <command> [<args>]
用法通常是单行，但多行可用于 阐明各选项何时相互排斥。如果所需的行数 呈现所有相互排斥的情况都变得过多，限制 一些常见情况，并会在完整的文档中提供更多详细信息。如果有很多 可以考虑创建子命令或单独的工具， 降低复杂性。
用法语法
首先列出命令名称。命令名称不是硬编码的，而是
从命令名称（即 argv[0] 上的最后一个元素）动态拉取的
路径。这使得单个二进制文件可以作为多个不同的工具运行。
名称和用法文本将仅包含可移植的 ASCII 字符。全部长视频 form 命令完全小写，即绝不能全部使用大写或大小写混合。单个 字母开关应首选小写形式，但允许使用大写。
对选项和占位符使用有意义的字词。避免使用缩写。首选
单个字词。如果使用了多个字词，请用连字符分隔各个字词
(-)，即不要使用下划线、驼峰式大小写，或将字词组合在一起。
除了命令名称之外，还有多种参数（如 Fuchsia 工具要求部分）。
- 确切文本
- 参数
- 选项（开关和按键）
- 键控选项
- 选项分隔符
确切文本语法
确切文本按原样在用法行中书写。在示例“Usage: copy
<from> to <destination>”中，to 一词需要完全匹配。如果是确切文本
是可选项，在用法行中用方括号 ([]) 括起来：“Usage:
copy <from> [to] <destination>”。
参数语法
参数用尖括号 (<>) 括起来，以便与
显式文本。在示例 Usage: copy <from> <destination> 中，<from>
和 <destination> 是参数。如果参数是可选的，则其为
用方括号 ([]) 括起来，例如 Usage: copy <from> [<destination>]。请参阅
选项分隔符。
相互排斥的选项语法
在说明互斥选项时，有几个选项可供选择。
如果提供了多个用法行，每个用法行都会显示一个互斥集合 命令的组合。例如：
Usage:
swizzle [-z] <file>
swizzle --reset
表示 --reset 和 <file> 的使用是互斥的
选项。
指定互斥选项的另一种方法是使用竖线（“|”） 。请注意，当使用竖线指示数据流时 称为“管道”。用于分隔选项时， 读作“Or”
例如：
Usage: froth [-y|-z] <file>
表示可以使用-y 或 -z开关（或者两者均不可使用，因为它们
是可选的，但同时使用这两个功能却毫无意义（它们
专有选项）。如需指明必须使用任一值，但不能同时使用两个值，
用括号括住选项，例如“Usage: froth (-a|-b) <file>”意味着
必须传递 -a 或 -b。
请注意，--version 或 --help 导致其他参数
并且很少被列为此类对象。请将它们作为单独的用法行列出
这说明没有必要。
分组（隐式）选项
启用某个选项时，没有具体的语法可指明
影响另一个选项。如果某个选项暗示其他选项已启用，或者
请在“选项”中指定该信息例如：“passing -e implies -f”意味着
如果启用了 -e，则 -f 将启用，就像是在命令中传递的一样
行（无论是否已显式传递 -f）。冗余传递
所有隐含值都无害（不是错误）。
记录主开关的影响。例如：如果-x implies -c and -p
将该备注放在 -x 的说明中，但不放在 -c 和 -p 中。这是为了
使 --help 输出保持简洁（在完整的上下文中，可以放宽此规则
文档）。
可选键
要使用可选键创建键控选项的外观，请创建可选键。
文本格式，后跟一个参数。例如“Usage: copy [from] <from> [to]
<destination>”。在此示例中，以下所有内容均有效：“copy a b”“copy
from a b”“copy from a to b”“copy a to b”。
重复选项
如果相同的位置参数可以重复，请用省略号表示
（“...”）。不要使用 Unicode 省略号，请使用三个连续句点。对于
示例：“Usage: copy <from> [<from>...] <to>”表示最后一个参数是
始终解释为 <to>，而前面的值是多个
<from> 个条目。请注意，“<from> [<from>...]”表示有一个或多个
<from> 个条目，而“Usage: copy [<from>...] <to>”指零个或更多个
已接受 <from> 个参评申请。
对于可能重复的键值对，请用方括号将其分组（如果
可选）或括号（如果对应的成对不是可选），并在末尾添加省略号
群组，例如[--input <file>]... 或 (--input <file>)...。
括号
尖括号 (<>)、大括号 ([]) 和圆括号 (()) 不具有
空格。
[from] # correct
<to> # correct
(-a|-b) # correct
[ from ] # incorrect
< to > # incorrect
( -a|-b ) # incorrect
英文尖括号 (<>) 用于封装参数或键值。
方括号 ([]) 用于封装可选元素。使用嵌套的尖括号，例如
[<file>] 将 <file> 解释为可选参数。嵌套的
“[<”不是单独的括号样式，而是“[”包含“<”。
嵌套时，方括号 ([) 将位于最外层（不要使用 <[file]>）。
圆括号 (()) 用于对元素进行分组。使用括号改进字词
例如，使用所需的互斥选项。
大括号 ({}) 留待将来使用。本指南特意保持开放状态
在未来的修订版中，大括号可能具有特殊含义
文档。
说明
必须提供说明，且不包含标题。例如，说明 区域未标记为“说明”。例如：
Destroy the contents of <file>.
说明采用美式英语散文（使用美式英语的完整句子） 英语语法、拼写和标点符号）。
每种工具都应告诉您它的作用，本部分将介绍如何执行此类操作。
“说明”部分应
- 工具的用途（必填）
- 使用的平台配置
- 架构、数据格式或使用的协议
- 黄金工作流（关键开发者历程）
- 文档内容较宽泛的网址（例如，fuchsia.com/docs 或类似网址，应避免 容易过时的链接）
“说明”部分还可包含“另请参阅”指的是其他工具 指定名称（避免使用网址）。
不应在“说明”部分填写的内容
- 使用的环境变量（选项中已列出的变量除外） （请在“选项”或“备注”中提供此信息）
- 安全危害（在“备注”部分中说明）
- 错误代码（将其放在“错误代码”部分）
- 版权（请勿在
--help中包含此信息） - author（请勿在
--help中包含此信息） - 如何获取有关子命令的帮助（将以下内容添加到
help子命令） - 如何更新该工具（应该在该工具的相关文档中说明） 包，如果适用）
- 版本说明（使用单独的文件）
选项
如果程序接受参数，则必须包含“选项”部分。例如：
Options:
-f force, ignore minor errors
-s <scribble> write <scribble> repeatedly. Defaults to $BLAST_SCRIBBLE.
列出的选项适用于工具本身，而不适用于子命令。选项
系统会在您请求相应子命令的帮助时列出各个子命令，例如
使用 blast help grind 或 blast grind --help 时。
尽量使用单个完整字词的选项。如果需要两个字词，
以连字符 (-) 分隔。避免使用不常见的缩写。
按字母顺序显示选项列表。
选项将分别在各行中列出每个参数、开关和键控选项，
同时具有短格式和长格式的参数除外。如果参数
都有短格式和长格式，它们会在同一行上列出，短格式
开头，并用 ,（逗号）分隔，例如-f, --force。
“选项”部分不会列出确切的文本参数。已显示 选择“使用折扣”
将按原样输入的文本不会用括号括起来，而变量条目
以尖括号 (<>) 显示，可选条目显示在方括号中
（[]）。列出选项时，键从来都不是可选的。例如：
-a a good example
[-b] a bad example, to use -b it must be typed as-is
每个选项后面都配有简短的说明。没有 而且要简明扼要尝试在整体工具中提供更多详细信息 说明、示例或备注，而不必创建冗长的选项 说明。
说明内容
- 简要提醒用户此选项的含义，例如
ignore minor errors - 如果该选项覆盖了其他选项，例如
-x implies -c and -p - 默认值，例如
defaults to $BLAST_SCRIBBLE
说明句子片段的起始列可能会因情况而异 对工具的需求进行改进。如果没问题的话，请使用左边 20 个字符。 然后根据实际情况进行调整
如果有大量选项，请考虑显示有用的子集并
解释如何获取更多帮助来查看所有问题，例如方法是将
--verbose和--help。
命令
如果程序包含子命令，则必须提供命令部分。如果显示 将标记为“命令：”。例如：
Commands:
blow-up explosively separate
grind make smaller by many small cuts
help get help on other commands e.g. `blast help grind`
如果程序没有子命令，则命令部分不会 存在。
如果工具有子命令，还会提供一个 help 命令，供您进一步
子命令的帮助，即 blast help grind。
尽量将子命令控制在单个完整的字词中。如果需要两个字词，
以连字符 (-) 分隔。避免使用不常见的缩写。现在
命令列表（按字母顺序）。
每个命令名称都与简短说明分开显示。对于 命令说明越长，用户就越需要 该命令。此说明是对命令和 来协助发现命令
如果有大量命令，请考虑显示有用的子集并
解释如何获取更多帮助来查看所有问题，例如方法是将
--verbose和--help。
示例
“示例”部分为可选内容。如果包含，则会被标记为“示例：”。 例如：
Examples:
Scribble 'abc' and then run |grind|.
$ blast -s 'abc' grind old.txt taxes.cp
每个示例都将采用美式英语散文（即使用美式英语的完整句子）
英语语法、拼写和标点）来描述示例，后跟
示例命令行。需在命令行中输入的每一行
字面上将带有“$”前缀来模拟命令提示符
如需将过长的示例换行，请用“\”结束上一行和
后续行以“”开头（空格）用于表示接续行。
This example wraps onto multiple lines.
$ blast -s 2332 some/long/path/cats.o \
more/long/path/dogs.o more/long/path/bears.o \
more/long/path/deer.o
如果显示示例命令的部分输出内容很有帮助，可以编写 输出。
请用一个空白行分隔各个示例。
如果“示例”部分太长，请将示例移至帮助文档中。 互动式帮助示例用于快速参考和提高曝光度 而不是详尽的文档
备注
注释是可选的，以“注释：”开头标头。例如：
Notes:
Use `blast help <command>` for details on [<args>] for a subcommand.
笔记采用美式英语散文（即使用美式英语的完整句子） 英语语法、拼写和标点符号）。
备注内容
- 除“选项”中已列出的变量以外（针对 默认值）
- 安全隐患
- 提醒来帮助用户
不应在备注中填写的内容
- 错误代码（将其放在“错误代码”部分）
- 版权（请勿在
--help中包含此信息） - author（请勿在
--help中包含此信息） - 如何获取有关子命令的帮助（将以下内容添加到
help子命令） - 如何更新该工具（应该在该工具的相关文档中说明） 包，如果适用）
- 版本说明（使用单独的文件）
错误代码
如果代码不是 0 或 1，则必须在“错误代码”部分查看
。例如：
Error codes:
2 The blade is too dull.
3 Out of fuel.
如果程序仅生成 0 或 1 结果，则省略此部分。
错误代码 0 始终被视为“无错误”错误代码 1 始终为
“general error”[一般错误]--help 输出中均未记录这两者。每个错误代码
（由工具生成的 0 或 1 除外）必须记录在案。
平台详细信息
某些平台（如 DOS）会使用不同的选项前缀（如 /）或可能允许
不区分大小写。工具将使用短划线前缀 (-)，并且区分大小写
所有平台和选项也就是说，该工具的文档
通常无需考虑所使用的平台。
--help 输出中不可包含的内容
请勿使用等号 (=) 显示键值对，例如--scribble=abc。
键和值使用空格作为分隔符 (--scribble abc) 进行解析。
在帮助中显示等于号可能会让用户感到困惑。
不要实现分页器（类似于会暂停输出的 more 程序）
）。
不包含
- 帮助输出中的版权（将版权置于法律指定的位置）。
- 版本说明（将其放在版本说明中）。
- 完整文档（将其放在 Markdown 文档中）。
- 版本信息（
--version的输出）。 - 关于结果代码
0或1的文档（放入 .md 文档中）。 - 特定于 Shell 的帮助（例如，如何将输出或管道重定向到分页器）。