Hello,
I have a question regarding the usage statement of a script.
I have 2 parameters "--pto" and "--pto_list". To start the script I will need one of them. Both together are not possible.
How this would be printed out within a usage statement?
My suggestion would be:
Usage: create_sql -f <filename> -a <add client> --pto | --pto_list <filename> --sim
So, is it possible to seperate them with a pipe?
Its upto you, you can print something like this
Usage: create_sql -f <filename> -a <add client> --[pto/pto_list] <filename> --sim
Ok. But does this statement not mean that it is optional to take one of these parameters?
Usage: create_sql -f <filename> -a <add client> --[pto/pto_list] <filename> --sim
But it is not optional to take one of them - because one of them is mandatory...
The square brackets are what I see used to denote a choice usually.
usage: ./command --arg1 --arg2 [--arg3 | --arg4]
Don't think there's really a standard for that though.
The standard way of doing this (when exactly one of two possible options or operands are required) is to use a two line synopsis:
Usage: create_sql -f <filename> -a <add client> --pto <filename> --sim
create_sql -f <filename> -a <add client> --pto_list <filename> --sim
See the cp man page for an example.
The notation:
Usage: create_sql -f <filename> -a <add client> --pto | --pto_list <filename> --sim
indicates that the only way to use create_sql is to pipe its output to the --pto-list command.
The notation:
Usage: create_sql -f <filename> -a <add client> [--pto | --pto_list] <filename> --sim
indicates that --pto can be specified or --pto-list can be specified, but not both; and neither one is required.
In all of these usage statements you're saying that -f is a mandatory option that requires a filename option-arument, -a is a mandatory option that requires an add client option-argument, --pto and --pto-list are long options that do not take an option-argument, you have a required filename operand and you have another long-option ( --sim ) that violates standard Utiiity Syntax Guideline #9 (all options are supposed to appear on the command line before operands). The order in which the -a , -f , --pto , --pto-list , and --sim options appear on the command line does not matter when you invoke the command, but all options should appear before any operands. The standards don't acknowledge the existence of long options either, but they are a common extension that falls into an area that the standards allow but do not require (a condition in the standards known as unspecified behavior).
By convention, if a long option takes an option-argument, that should be shown in a synopsis as --option=argument ; not as --option argument to preclude an ambiguity issue with long option optional option-arguments. (Having short option optional option-arguments violates Utiiity Syntax Guideline #7.)