Shell 是否有记录命令行界面的最佳实践？

我设计了一些具有CLI的程序，并希望尽可能将它们作为标准文档记录下来。关于这方面的最佳方式，是否有任何协议

例如：

假设程序是“sayHello”，它接受几个参数：name和message。因此，一个标准的呼叫应该是这样的：

> sayHello "Bob" "You look great" 

sayHello [name] [message]

好的，我的命令用法如下所示：

> sayHello "Bob" "You look great" 

sayHello [name] [message]

如果括号在用法命令中具有特定含义，那么这可能已经是一个错误。但让我们更进一步，说“消息”是可选的：

sayHello [name] [message (optional)]

还有一个褶皱，如果有一个默认值，我们想表示：

sayHello [name] [message (optional: default 'you look good')]

---

我意识到这个用法声明在这一点上看起来有点迟钝。我真的在问，在如何编写这些文档方面，是否有一些一致的标准。我暗自怀疑括号和方括号都有特定的含义。

您可能希望查看常用Unix命令的手册（例如

man grep

）或Windows命令的帮助文档（例如

find/？

），并将其用作一般指南。如果你选择了这两种模式中的任何一种（或者使用了两者共有的元素），你至少会让最少的人感到惊讶

ApacheCommons在包中还包含一个用于打印特定命令行选项集的使用信息的包

Options options = new Options();
options.addOption(OptionBuilder.withLongOpt("file")
                      .withDescription("The file to be processed")
                      .hasArg()
                      .withArgName("FILE")
                      .isRequired()
                      .create('f'));
options.addOption(OptionBuilder.withLongOpt("version")
                      .withDescription("Print the version of the application")
                      .create('v'));
options.addOption(OptionBuilder.withLongOpt("help").create('h'));

String header = "Do something useful with an input file\n\n";
String footer = "\nPlease report issues at http://example.com/issues";

HelpFormatter formatter = new HelpFormatter();
formatter.printHelp("myapp", header, options, footer, true);

使用上述命令将生成如下所示的帮助输出：

usage: myapp -f  [-h] [-v]
Do something useful with an input file

 -f,--file <FILE>   The file to be processed
 -h,--help
 -v,--version       Print the version of the application

Please report issues at http://example.com/issues

用法：myapp-f[-h][-v]
对输入文件执行一些有用的操作
-f、 --将要处理的文件归档
-h、 “救命
-v、 --版本打印应用程序的版本
请于http://example.com/issues

您可能希望查看常用Unix命令的手册（例如

man grep

）或Windows命令的帮助文档（例如

find/？

），并将其用作一般指南。如果你选择了这两种模式中的任何一种（或者使用了两者共有的元素），你至少会让最少的人感到惊讶

ApacheCommons在包中还包含一个用于打印特定命令行选项集的使用信息的包

Options options = new Options();
options.addOption(OptionBuilder.withLongOpt("file")
                      .withDescription("The file to be processed")
                      .hasArg()
                      .withArgName("FILE")
                      .isRequired()
                      .create('f'));
options.addOption(OptionBuilder.withLongOpt("version")
                      .withDescription("Print the version of the application")
                      .create('v'));
options.addOption(OptionBuilder.withLongOpt("help").create('h'));

String header = "Do something useful with an input file\n\n";
String footer = "\nPlease report issues at http://example.com/issues";

HelpFormatter formatter = new HelpFormatter();
formatter.printHelp("myapp", header, options, footer, true);

使用上述命令将生成如下所示的帮助输出：

usage: myapp -f  [-h] [-v]
Do something useful with an input file

 -f,--file <FILE>   The file to be processed
 -h,--help
 -v,--version       Print the version of the application

Please report issues at http://example.com/issues

用法：myapp-f[-h][-v]
对输入文件执行一些有用的操作
-f、 --将要处理的文件归档
-h、 “救命
-v、 --版本打印应用程序的版本
请于http://example.com/issues

虽然我不知道有任何官方标准，但仍有一些努力通过框架提供约定。就是这样一个框架，可能适合您的需要。用他们自己的话来说：

docopt帮助您：

• 定义命令行应用程序的界面，以及
• 自动为它生成解析器

---

有针对的实现，包括。

虽然我不知道有任何官方标准，但也有一些努力通过框架提供约定。就是这样一个框架，可能适合您的需要。用他们自己的话来说：

docopt帮助您：

• 定义命令行应用程序的界面，以及
• 自动为它生成解析器

---

有一些实现，包括。

遵循最适用的

man

或（PowerShell

帮助

）或其他参考文档中列出的约定。。或者只是按照你喜欢的方式写。然而，

[SquareBracketSnromallymanOptional]

在谈论期权本身时，经常会讨论默认值。如上所述，但我通常看到

progname arg1 arg2[opt_arg3（默认值：someval），opt_arg4，…]

我确实理解这个问题上的“保持”含义，这是公平的。我希望有一种商定的方式来展开这样的讨论，因为它们可能会导致（在本例中）一个更普遍的标准，而这个标准还没有定义。此外，提供的答案实际上提供了解决该问题的具体示例和资源。请遵循最适用的

man

或（PowerShell

帮助

）或其他参考文档中列出的约定。。或者只是按照你喜欢的方式写。然而，

[SquareBracketSnromallymanOptional]

在谈论期权本身时，经常会讨论默认值。如上所述，但我通常看到

progname arg1 arg2[opt_arg3（默认值：someval），opt_arg4，…]

我确实理解这个问题上的“保持”含义，这是公平的。我希望有一种商定的方式来展开这样的讨论，因为它们可能会导致（在本例中）一个更普遍的标准，而这个标准还没有定义。此外，所提供的答案确实提供了解决该问题的具体例子和资源。