Shell scripts: conventions to write usage text for parameters?
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."