Maneira correta de documentar opções de comprimento variável em man pages

2

Às vezes, vejo informações de uso como

some_utility [arg [arg [...]]]

ou

some_utility [arg[, arg[...]]]

que indica que você pode passar mais do que um do mesmo argumento.

Eu também vi isso como

some_utility [args]

ou

some_utility [arg][, arg][...]

Existe uma maneira padrão de fazer isso?

    
por David Winiecki 13.05.2014 / 00:57

1 resposta

1

Não, não realmente , mas na maioria das vezes é bastante consistente. A maioria dos manuais lista argumentos opcionais com colchetes ( [foo] ), obrigatórios com colchetes angulares ou sem colchetes ( <bar> , baz , o último sublinhado com freqüência).

Além disso, em quase todos os casos, se o número de argumentos for variável, você terá algum tipo de lista (como você mencionou, [quux ...] ou [quux[, quux[...]]] ...), onde similarmente [quuz] a maioria dos times denota exatamente um um argumento. Em casos raros, [quuz] também pode significar »um ou mais argumentos«, mas a maioria dos manuais está de acordo com as reticências do formulário de listagem.

É quase um padrão, mas você não pode confiar nele. Mas na minha experiência está tudo bem em 95% vezes.

O ponto é, existem centenas de fornecedores de software de qualquer couleur lá fora, não apenas "grandes jogadores", mas também há softwares escritos por indivíduos solteiros que provaram ser úteis. Todos eles (espero) escrevem suas páginas de trabalho de maneira individual ... a maioria deles sabe o suficiente para cuidar de convenções comuns, mas há também aqueles que não se importam ou têm algum tipo de defeito mental relacionado ao gosto do estilo, etc. )

    
por 13.05.2014 / 01:21