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

14

Parece-me que todos têm sua própria idéia de como escrever uma sinopse descrevendo o uso do comando para o usuário final.

Por exemplo, este é 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 de manual. []é reconhecido como opcional e ...faz sentido como múltiplo da mesma entrada.

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

Gostaria de seguir um padrão para o que escrevo, mas cada site que eu olho me diz algo diferente.

Existe uma maneira padrão de escrever sinopses ou a convenção é exatamente o que as pessoas têm feito ao longo do tempo?

command-line man Tormyst
fonte
Escolha um e fique com ele.
Kevin
Por alguma razão, acho que isso não ajudaria. Toda pessoa teria seu próprio padrão e nada seria feito a respeito.
Tormyst
4
Esse é o tipo de padrão que você quer dizer? pubs.opengroup.org/onlinepubs/009695399/basedefs/…
Mark Plotnick
Sim, é exatamente isso que eu estava procurando. Obrigado.
Tormyst
1
@ MarkPlotnick - eu faria um A para que o OP possa aceitá-lo. Esse é o padrão, se é que houve algum. Faça referência ao link que o illuminÉ referenciou.
Slm

Respostas:

8

O padrão clássico para isso é do POSIX, Utility Argument Syntax (obrigado a @ illuminÉ pelo link atualizado). Descreve a sintaxe a ser usada nas páginas do manual, por exemplo

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

Por ser clássico, recomenda o uso de opções de um caractere, -Wrecomendadas para uso pelos fornecedores, e é assim que as opções de vários caracteres são acomodadas (consulte, 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 formatar páginas de manual com essas opções podem ser encontradas na referência help2man .

Mark Plotnick
fonte