命令行/ shell帮助文本是否有"标准"格式？

Question

如果没有,是否有事实上的标准？基本上我正在编写命令行帮助文本,如下所示:

usage: app_name [options] required_input required_input2
  options:
    -a, --argument     Does something
    -b required     Does something with "required"
    -c, --command required     Something else
    -d [optlistitem1 optlistitem 2 ... ]     Something with list

我从基本上只是阅读各种工具的帮助文本中做到了这一点,但是有一个指南列表还是什么？例如,我使用方括号还是括号？如何使用间距？如果参数是一个列表怎么办？谢谢!

Answer 1

通常,您的帮助输出应包括:

• 应用程序的功能描述
• 用法语法,其中:
  • 用于[options]指示选项的位置
  • arg_name 对于一个必需的,单一的arg
  • [arg_name] 对于一个可选的,单一的arg
  • arg_name... 对于一个必需的arg,其中可以有很多(这是罕见的)
  • [arg_name...] 对于可以提供任何数量的arg
  • 请注意,这arg_name应该是一个描述性的简短名称,在较低的蛇案例中
• 一个格式良好的选项列表,每个选项:
  • 有一个简短的描述
  • 显示默认值(如果有)
  • 如果适用,则显示可能的值
  • 请注意,如果选项可以接受简短形式(例如-l)或长形式(例如--list),请将它们一起包含在同一行中,因为它们的描述将是相同的
• 可能是命令行参数源的配置文件或环境变量位置的简要指示,例如 GREP_OPTS
• 如果有手册页,请指明,否则,可以找到更详细帮助的简要指示

此外,值得注意的是它的好形式,同时接受-h并--help触发此消息,并说如果用户弄乱的命令行语法,如忽略了一个必要的参数,你应该显示此消息.

Answer 2

看看docopt.它是记录(和自动解析)命令行参数的正式标准.

例如...

Usage:
  my_program command --option <argument>
  my_program [<optional-argument>]
  my_program --another-option=<with-argument>
  my_program (--either-that-option | <or-this-argument>)
  my_program <repeating-argument> <repeating-argument>...

Answer 3

Microsoft有一个命令行语法

• 没有括号或大括号的文本

  您必须键入的项目如图所示
  
  

• <尖括号内的文字>

  您必须为其提供值的占位符
  
  

• [方括号内的文字]

  可选项目
  
  

• {文字里面的大括号}

  一套必需的物品; 选一个
  
  

• 垂直条(|)

  互斥物品的分隔物; 选一个
  
  

• 省略号(...)

  可以重复的项目
  
  

Answer 4

我们正在运行Linux,一个主要是POSIX兼容的操作系统.POSIX标准应该是:Utility Argument Syntax.

Answer 5

GNU编码标准对于这样的事情是一个很好的参考.本节介绍的输出--help.在这种情况下,它不是非常具体.打印显示短期和长期选项以及简洁描述的表格可能不会出错.尝试获取所有参数之间的间距以确保可读性.您可能希望为工具提供一个man页面(可能还有一个info手册),以提供更详细的说明.

Answer 6

Microsoft有自己的命令行标准规范:

本文档主要关注命令行实用程序的开发人员.总的来说,我们的目标是提供一致的,可组合的命令行用户体验.实现这一点允许用户学习一组核心概念(语法,命名,行为等),然后能够将这些知识转化为使用大量命令.这些命令应该能够以标准化格式输出标准化数据流,以便于组合,而无需解析输出文本流.编写本文档独立于shell,一组实用程序或命令创建技术的任何特定实现; 但是,附录J - 使用Windows Powershell实现Microsoft命令行标准显示了如何使用Windows PowerShell免费提供许多这些准则的实现.