概览
命令行帮助（通常通过 --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.
总体布局和样式
如需查看符合这些要求的示例，请参阅上文。
有些部分需要英语散文。也就是说，使用美式英语拼写（而非英式英语或其他）以英语语法撰写合适的句子。在句子之间使用一个空格，并遵循“牛津逗号”样式。例如，“说明、示例和备注部分是用英文书写的。”
布局
- 每个部分均以一个空白行分隔。
- 部分内容缩进两个空格。
- 单行内容将写在标签所在的行中，并以空格分隔冒号和命令名称。例如“
Usage: blast <file>”。 - 多行部分将紧跟在标签后写入（没有空行）。标签后面的每一行都会缩进两个空格。
- 所有输出都是单列文本，但“选项”“命令”和“错误代码”除外，它们是两个列表。
- 使用空格进行缩进或对齐。不输出制表符。
- 第 80 列有文本换行。封装选项说明或命令说明时，请将后续行与说明的开头对齐（例如，大约 20 个字符）。
样式
- 版块标题采用词首字母大写形式：将第一个和最后一个单词的首字母大写。中间的所有单词也采用大写形式，但冠词（a、an、the）、连词（例如，and、 but、or）和介词（例如 on、in、with）除外。
- 简短说明片段（选项或命令中的第二列）以小写字母开头，不需要完整的句子。简短说明以外的任何文本都应是完整的句子，并在片段后添加句点。
- 尽量确保每个部分都简洁明了。如果需要的话，请在运行
--help时让用户使用--verbose，或者引导他们查看完整文档。 - 描述性文本（散文）中允许使用 Unicode (UTF-8) 字符。命令名称和用法文本将仅包含便携式 ASCII 字符（不带 Unicode）。
用法
需要使用此属性，且包含“Usage:”标头。
Usage: blast [-f] [-s <scribble>] <command> [<args>]
通常情况下，使用单行，但可以使用多行来阐明选项是互斥的情况。如果呈现所有互斥场景所需的行数过多，请将这些行限制为一些常见的情况，并在完整文档中提供更多详细信息。如果有许多互斥的选项，请考虑创建子命令或单独的工具以降低复杂性。
用法语法
命令名称列在最前面。命令名称未经过硬编码：系统会从命令名称（即 argv[0] 路径上的最后一个元素）中动态提取该名称。这样一来，单个二进制文件就可以作为多个不同工具运行。
名称和使用文本将仅包含便携式 ASCII 字符。所有长命令均完全采用小写形式，即绝不能采用全大写形式或混合大小写形式。单字母开关应首选小写，但允许使用大写。
使用有意义的字词作为选项和占位符。避免使用缩写。首选单个字词。当使用多个单词时，请使用连字符 (-) 分隔单词，即不要使用下划线、驼峰式大小写或将多个单词组合在一起。
除了命令名称之外，还有几种参数（如 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]>）。
圆括号 (()) 用于对元素进行分组。使用括号提高清晰度，例如使用必需的互斥选项。
大括号 ({}) 已预留以供日后使用。本指南特意在本文档的未来修订版本中，为大括号留出了特殊含义。
说明
说明为必填项，且不包含标题。也就是说，说明区域不带“description”标签。例如
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 时），系统会列出该子命令的相关选项。
尽量保留一个完整字词的选项。如果需要两个单词，请使用连字符 (-) 将其分隔开。避免使用不常用的缩写。
按字母顺序显示选项列表。
Options 会在单独的行中列出每个参数、switch 和键控选项，但参数既有短格式，也有长格式。如果参数既有短格式，也有长格式，它们会列在同一行中，短格式在前，并用 ,（英文逗号）分隔，例如 -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:”标签。例如
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:”标题开头。例如
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 始终是“常规错误”。--help 输出中也不会记录这两种情况。除了 0 或 1 之外，工具可能生成的每个错误代码都必须记录在案。
平台详情
某些平台（例如 DOS）使用其他选项前缀（例如 /），或者可能允许使用不区分大小写的开关。无论平台如何，工具都将使用短划线前缀 (-) 和区分大小写的选项。这意味着工具的文档通常不需要考虑正在使用的平台。
--help 输出中不应包含的内容
不要显示等号 (=) 的键值对，例如 --scribble=abc。
在解析键和值时，会使用空格作为分隔符 (--scribble abc)。在帮助中显示等号可能会让人感到困惑。
请勿实现分页器（类似于 more 程序，它会在每次过滤文本时暂停输出）。
不包含
- 帮助输出（在 legal 指定的位置）中的版权。
- 版本说明（将其放入版本说明）。
- 完整文档（请将其放在 Markdown 文档中）。
- 版本信息（从
--version输出）。 - 有关结果代码
0或1的文档（放在 .md 文档中）。 - 关于 shell 的帮助（例如，如何将输出或管道重定向到分页器）。