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?

l0b0 · Accepted Answer · 2013-06-26 15:38:52Z

9

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."

edited Jun 26, 2013 at 15:38

answered Jun 26, 2013 at 9:24

l0b0

59.7k32 gold badges155 silver badges248 bronze badges

Sign up to request clarification or add additional context in comments.

Collectives™ on Stack Overflow

Shell scripts: conventions to write usage text for parameters?

1 Answer 1

Comments

Your Answer

Hot Network Questions

Collectives™ on Stack Overflow

1 Answer 1

Comments

Your Answer

Sign up or log in

Post as a guest

Related