有没有一个“标准”?命令行/shell帮助文本的格式?

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

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

我基本上只是阅读了各种工具的帮助文本，但是否有指南列表或其他内容?例如，我是用方括号还是圆括号?如何使用空格?如果参数是一个列表呢?谢谢!

160648 次浏览
小开

GNU编码标准是一个很好的参考。本节处理--help的输出。在这种情况下，它不是很具体。打印一个表，显示短选项和长选项，并给出简洁的描述，可能不会出错。为了可读性，尽量让所有参数之间的间距合适。你可能想为你的工具提供一个man页面(可能还有一个info手册)来提供更详细的解释。

小开

是的，你的思路是对的。

是的，方括号是可选项目的常用指示符。

通常，正如您所勾勒的那样，在顶部有一个命令行摘要，后面是详细信息，理想情况下每个选项都有示例。(您的示例显示了每个选项描述之间的行，但我假设这是一个编辑问题，并且您的实际程序输出的是缩进的选项列表，中间没有空行。这将是在任何情况下都要遵循的标准。)

一个更新的趋势(也许有一个POSIX规范解决这个问题?)是消除手册页系统的文档，并包括所有信息将在手册页作为program --help输出的一部分。这个额外的内容将包括更长的描述，解释的概念，使用示例，已知的限制和错误，如何报告错误，以及可能的相关命令的“参见”部分。

我希望这能有所帮助。

小开

我会以官方项目为例，比如tar。在我看来，帮助味精。需要尽可能的简单和描述性。使用的例子也很好。对“标准帮助”没有真正的需求。

小开
最佳答案

通常，你的帮助输出应该包括:

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

      进一步注意，同时接受-h和--help来触发这条消息而且是很好的形式，如果用户弄乱了命令行语法，例如遗漏了一个必需的参数，你应该显示这条消息。

小开

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

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

小开

看看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>...
小开

我们运行的是Linux，一个基本符合posix的操作系统。POSIX标准它应该是:实用程序参数语法。

  • 选项是一个连字符后跟一个字母数字字符， 像这样:-o。李< / >
  • 选项可能需要参数(必须出现) 紧接在选项之后);例如，-o argument或 -oargument。李< / >
  • 不需要参数的选项可以用连字符分组，例如，-lst等价于-t -l -s。
  • 选项可以以任何顺序出现;因此-lst等价于-tls。
  • 选项可以出现多次。
  • 选项在其他非选项之前 参数:-lst nonoption.
  • --参数终止选项。
    • -选项通常用于表示一个标准输入 李流。< / >
小开

我认为命令行使用没有标准的语法，但大多数人都使用这样的约定:

微软命令行语法, IBM有类似的命令行语法

  • < h3 > Text without brackets or braces

    必须按显示输入的项目
    < br > < / p >

  • < h3 > <Text inside angle brackets>

    占位符，必须为其提供一个值
    < br > < / p >

  • < h3 > [Text inside square brackets] < p >可选项目
    < br > < / p >
  • < h3 > {Text inside braces}

    必需项目集;选择一个
    < br > < / p >

  • 竖条{a|b}

    互斥项的分隔符;选择一个
    < br > < / p >

  • < h3 >省略号<file> …

    可重复的项
    < br > < / p >

小开

这可能是一个位离题，但我曾经写过两个小工具，使创建和维护命令行工具帮助页面更有效:

  • 通过处理源代码中的Javadoc注释，为Java程序的主方法生成HTML文档的主要DOCLET
  • HTML2TXT工具将HTML文档格式化为纯文本(这是我们想要的帮助文本)

我将这两个工具集成到程序的MAVEN构建过程中，以便它们在每次构建时自动执行。

例如:

希望这对其他人有用!?

小开

没有标准，但是http://docopt.org/已经为命令行工具创建了他们版本的帮助文本规范。

小开

为此我使用CSS形式符号。

组件值可以按如下方式排列成属性值:

  • 几个并列的单词意味着它们都必须按照给定的顺序出现。
  • 条(|)分隔两个或多个选项:其中一个必须出现。
  • 双条(||)分隔两个或多个选项:其中一个或多个必须以任意顺序出现。
  • 双&号(&&)分隔两个或多个组件，所有这些组件必须以任意顺序出现。
  • 括号([ ])用于分组。

并列强于双&号，双&号强于双&号，双&号强于双&号。因此，以下几行是等价的:

    a b   |   c ||   d &&   e f
[ a b ] | [ c || [ d && [ e f ]]]

每个类型、关键字或括起来的组后面都可以跟着以下修饰符之一:

  • 星号(*)表示前面的类型、单词或组出现0次或多次。
  • 加号(+)表示前面的类型、单词或组出现了一次或多次。
  • 问号(?)表示前面的类型、单词或组是可选的。
  • 花括号中的一对数字({A,B})表示前面的类型、单词或组至少出现A次，最多出现B次。

如果需要示例，请参见MDN上的正式的定义部分;这里有一个font: https://developer.mozilla.org/en-US/docs/Web/CSS/font#formal_syntax。

下面是我自己Pandoc小抄中的一个简单例子:

$ pandoc <input_file>.md --from [markdown|commonmark_x][-smart]? --to html --standalone --table-of-contents? --number-sections? [--css <style_sheet>.css]? --output <output_file>.html

提交答案