Shell scripts: conventions to write usage text for parameters?

Question

I am somehow confused on how I should write the usage text for parameters and arguments in a script. Wherever I look it's always different. Especially the way arguments are described and its syntax varies.

e.g. usage for parameters requiring flag with filename

$0 -f <filename>
$0 [-f filename]
$0 [-f] <filename>
$0 [-f] [filename]
$0 [-f <filename>]
$0 [-f] [<filename>]

e.g. usage for parameters which are optional (-f, -g, -h)

$0 [-fgh]
$0 [<optional>]
$0 [-[fgh]]
$0 [-<fgh>]
$0 -fgh
$0 -[fgh]

etc.

This might be a minor issue, but annoying, as the syntax is always different and sometimes it actually means something different, but you can't see it, because it doesn't follow any conventions. What's your opinion about it, and what is the best practise to write a usage text with appropriate syntax?

Answer 1

POSIX defines a convention for utility argument syntax (Oddly enough they seem to have forgotten to put spaces between the ] and following [ groupings, like they do on actual utility description pages (for example command and find)):

• "Arguments or option-arguments enclosed in the '[' and ']' notation are optional and can be omitted." In consequence, "un-enclosed" ("declosed?") arguments are mandatory.

• "Frequently, names of parameters that require substitution by actual values are shown with embedded underscores. Alternatively, parameters are shown as follows:

  <parameter name>
  

  "

• "Arguments separated by the '|' vertical bar notation are mutually-exclusive."
• "Ellipses ( "..." ) are used to denote that one or more occurrences of an option or operand are allowed."