首页 文章

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

提问于
浏览 次
174

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

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

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

shell command-line command-line-arguments

8 回答

  • 8

    通常，您的帮助输出应包括：

    • 应用程序的功能说明

    • 用法语法，其中：

    • 使用 [options] 指示选项的位置

    • arg_name 为必需的，单数的arg

    • [arg_name] 为可选的单数arg

    • arg_name… 所需的arg可以有很多（这很少见）

    • [arg_name…] 对于可以提供任何数字的arg

    • 请注意 arg_name 应该是一个描述性的短名称，在较低的蛇案例中

    • 一个格式良好的选项列表，每个：

    • 有一个简短的描述

    • 显示默认值（如果有）
      如果适用，

    • 显示可能的值

    • 请注意，如果某个选项可以接受简短表单（例如 -l ）或长表单（例如 --list ），请将它们包含在同一行中，因为它们的描述相同

    • 可能是命令行参数源的配置文件或环境变量位置的简要指示，例如 GREP_OPTS

    • 如果有手册页，请指明，否则，可以找到可以找到更详细帮助的简要指示

    另请注意，接受 -h 和 --help 来触发此消息是一种很好的形式，如果用户弄乱了命令行语法，则应显示此消息，例如：省略必需的参数 .

    回复于
  • 0

    看看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>...
    回复于
  • 12

    微软有Command-Line Syntax

    没有括号或大括号的文字

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

    <尖括号内的文字>

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

    [方括号内的文字]

    可选项目

    {大括号内的文字}

    一套必需的物品;选一个

    竖条（|）

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

    省略号（...）

    可以重复的项目

    回复于
  • 59

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

    回复于
  • 7

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

    回复于
  • 0

    微软有自己的Command Line Standard specification：

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

    回复于
  • 9

    是的，你走在正确的轨道上 .

    是的，方括号是可选项的常用指标 .

    通常情况下，如您所示，顶部有一个命令行摘要，后面是详细信息，最好是每个选项的示例 . （您的示例显示了每个选项描述之间的行，但我认为这是一个编辑问题，并且您的真实程序输出缩进的选项列表，其间没有空行 . 这在任何情况下都是遵循的标准 . ）

    一个更新的趋势，（可能有一个解决这个问题的POSIX规范？），是消除了文档的手册页系统，并包括作为 program --help 输出一部分的手册页中的所有信息 . 这个额外的将包括更长的描述，解释的概念，使用示例，已知的限制和错误，如何报告错误，以及可能相关命令的'see also'部分 .

    我希望这有帮助 .

    回复于
  • 122

    我会像tar这样的官方项目作为例子 . 在我看来帮助消息 . 需要尽可能简单和描述 . 使用的例子也很好 . 没有真正需要“标准帮助” .

    回复于

相关问题