Existe um formato "padrão" para o texto de ajuda da linha de comando / shell?

Caso contrário, existe um padrão de fato? Basicamente, estou escrevendo um texto de ajuda da linha de comando, assim:

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

Eu fiz isso basicamente lendo apenas o texto de ajuda de várias ferramentas, mas há uma lista de diretrizes ou algo assim? Por exemplo, eu uso colchetes ou parênteses? Como usar espaçamento? E se o argumento for uma lista? Obrigado!

Normalmente, sua saída de ajuda deve incluir:

• Descrição do que o aplicativo faz
• Sintaxe de uso, que:
  • Usa [options]para indicar para onde as opções vão
  • arg_name para um argumento obrigatório e singular
  • [arg_name] para um argumento opcional e singular
  • arg_name... para um argumento exigido, do qual pode haver muitos (isso é raro)
  • [arg_name...] para um argumento para o qual qualquer número pode ser fornecido
  • note que arg_namedeve ser um nome curto e descritivo, em letras minúsculas
• Uma lista de opções bem formatada, cada uma:
  • tendo uma breve descrição
  • mostrando o valor padrão, se houver um
  • mostrando os valores possíveis, se aplicável
  • Observe que, se uma opção puder aceitar um formulário curto (por exemplo -l) ou longo (por exemplo --list), inclua-os juntos na mesma linha, pois suas descrições serão as mesmas
• Breve indicador da localização dos arquivos de configuração ou variáveis ​​de ambiente que podem ser a fonte dos argumentos da linha de comando, por exemplo GREP_OPTS
• Se houver uma página de manual, indique como tal, caso contrário, um breve indicador de onde pode ser encontrada ajuda mais detalhada

Observe ainda que é uma boa forma aceitar ambos -he --helpacionar esta mensagem e que você deve mostrá-la se o usuário alterar a sintaxe da linha de comando, por exemplo, omite um argumento necessário.

Dê uma olhada no docopt . É um padrão formal para documentar (e analisar automaticamente) argumentos da linha de comando.

Por exemplo...

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>...

Eu acho que não há sintaxe padrão para o uso da linha de comando, mas a maioria usa esta convenção:

Sintaxe da linha de comando da Microsoft , a IBM possui sintaxe de linha de comando semelhante

• Text without brackets or braces

  Itens que você deve digitar como mostrado
  
  

• <Text inside angle brackets>

  Espaço reservado para o qual você deve fornecer um valor
  
  

• [Text inside square brackets]

  Itens opcionais
  
  

• {Text inside braces}

  Conjunto de itens necessários; escolha um
  
  

• Barra vertical {a|b}

  Separador para itens mutuamente exclusivos; escolha um
  
  

• Elipse <file> …

  Itens que podem ser repetidos
  
  

Estamos executando o Linux, um sistema operacional principalmente compatível com POSIX. Os padrões POSIX devem ser: Sintaxe do argumento do utilitário .

• Uma opção é um hífen seguido por um único caractere alfanumérico, como este: -o.
• Uma opção pode exigir um argumento (que deve aparecer imediatamente após a opção); por exemplo, -o argumentou -oargument.
• As opções que não exigem argumentos podem ser agrupadas após um hífen; portanto, por exemplo, -lsté equivalente a -t -l -s.
• As opções podem aparecer em qualquer ordem; assim -lsté equivalente a -tls.
• As opções podem aparecer várias vezes.
• As opções precedem outros argumentos de não- -lstopção : não- opção.
• O --argumento encerra as opções.
• A -opção é normalmente usada para representar um dos fluxos de entrada padrão.

A Microsoft tem sua própria especificação Command Line Standard :

Este documento está focado nos desenvolvedores de utilitários de linha de comando. Coletivamente, nosso objetivo é apresentar uma experiência consistente e composível ao usuário da linha de comando. Conseguir isso permite que o usuário aprenda um conjunto principal de conceitos (sintaxe, nomeação, comportamentos etc.) e depois possa traduzir esse conhecimento para trabalhar com um grande conjunto de comandos. Esses comandos devem poder gerar fluxos de dados padronizados em um formato padronizado para permitir uma composição fácil, sem a necessidade de analisar fluxos de texto de saída. Este documento foi escrito para ser independente de qualquer implementação específica de um shell, conjunto de utilitários ou tecnologias de criação de comandos; no entanto, o Apêndice J - Usando o Windows Powershell para implementar o Microsoft Command Line Standard mostra como o uso do Windows PowerShell fornecerá a implementação de muitas dessas diretrizes gratuitamente.

O GNU Coding Standard é uma boa referência para coisas assim. Esta seção trata da saída de --help. Nesse caso, não é muito específico. Você provavelmente não pode dar errado ao imprimir uma tabela mostrando as opções curtas e longas e uma descrição sucinta. Tente acertar o espaçamento entre todos os argumentos para facilitar a leitura. Você provavelmente deseja fornecer uma manpágina (e possivelmente um infomanual) para sua ferramenta, para fornecer uma explicação mais elaborada.

sim, você está no caminho certo.

Sim, colchetes são o indicador usual para itens opcionais.

Normalmente, como você esboçou, há um resumo da linha de comando na parte superior, seguido por detalhes, idealmente com amostras para cada opção. (Seu exemplo mostra linhas entre cada descrição de opção, mas presumo que seja um problema de edição e que seu programa real produz listagens de opções recuadas sem linhas em branco no meio. Esse seria o padrão a ser seguido em qualquer caso.)

Uma tendência mais recente, (talvez exista uma especificação POSIX que resolva isso?), É a eliminação do sistema da página de manual para documentação e incluindo todas as informações que estariam em uma página de manual como parte da program --helpsaída. Este extra incluirá descrições mais longas, conceitos explicados, exemplos de uso, limitações e bugs conhecidos, como relatar um bug e, possivelmente, uma seção 'consulte também' para comandos relacionados.

Eu espero que isso ajude.

Eu seguiria projetos oficiais como o tar como exemplo. Na minha opinião ajuda msg. precisa ser o mais simples e descritivo possível. Exemplos de uso também são bons. Não há necessidade real de "ajuda padrão".