Existe um padrão para escrever uma sinopse de comando?

Question

Parece-me que todos têm a sua própria ideia sobre como escrever uma sinopse descrevendo utilização do comando para o utilizador final.

Por exemplo, esse é o formato de man grep :

grep [OPTIONS] PATTERN [FILE...]
grep [OPTIONS] [-e PATTERN | -f FILE] [FILE...]

Agora, isso tem alguma sintaxe que aparece em outras páginas do manual. [] é reconhecido como opcional e ... faz sentido como múltiplos da mesma entrada.

Mas as pessoas usam | ou / para OR e há outras que revertem o que significa [] . Ou eles não dão nenhuma indicação de onde [OPTIONS] vai.

Eu gostaria de seguir um padrão para o que eu escrevo, mas cada site que eu vejo me diz algo diferente.

Existe uma forma real padrão de escrever sinopses, ou a convenção é exatamente o que as pessoas vêm fazendo ao longo do tempo?

    

Answer 1

O padrão clássico para isso é de POSIX, Sintaxe do Argumento de Utilidade (graças a @ illuminÉ para o link atualizado). Descreve a sintaxe a ser usada nas páginas man, por exemplo

utility_name[-a][-b][-c option_argument]
    [-d|-e][-f[option_argument]][operand...]

Sendo clássico, recomenda usar opções de caractere único, com -W recomendado para uso por fornecedores, e é assim que opções de vários caracteres são acomodadas (veja, por exemplo, Resumo das opções do gcc ).

O software GNU introduziu opções de vários caracteres que começam com -- . Algumas diretrizes do GNU para formatação de páginas man com essas opções podem ser encontradas na referência help2man .