Dixie Pine wrote on 10/30/09 13:32:
> On 10/29/09 10:07 PM, Bill Shannon wrote:
>> Following up on this discussion we had last week...
>>
>> Here's what I've done:
>>
>> Usage: asadmin [asadmin-utility-options] create-domain
>> [--adminport <adminport(default:4848)>]
>> [--instanceport <instanceport(default:8080)>] [--portbase <portbase>]
>> [--profile <profile>] [--template <template>] [--domaindir <domaindir>]
>> [--savemasterpassword[=<savemasterpassword(default:false)>]]
>> [--domainproperties <domainproperties>]
>> [--keytooloptions <keytooloptions>]
>> [--savelogin[=<savelogin(default:false)>]]
>> [--checkports[=<checkports(default:true)>]]
>> [--nopassword[=<nopassword(default:false)>]]
>> [-?|--help[=<help(default:false)>]] domain_name
>>
>>
>> Notice that I also fixed it to insert line breaks at reasonable points.
>>
> I think this is very helpful if user has to figure out a subcommand with
> lots of options. They are very hard to read all run together.
>> It's a bit on the verbose side, but is it usable?
>>
>> I considered the alternative of listing the default boolean value first,
>> but since that was inconsistent with the other defaults it seemed
>> like it would be confusing. For example:
>>
>> [--nopassword[=false|true]]
>>
> Now that I'm trying to actually use this style, I'm having trouble with
> the booleans, prefer this to what's in the long example. It's confusing
> to have --nopassword inside the < > because it's what I actually type,
> not a replaceable. Maybe this:
>
> [--nopassword=(default:false)]
>
> Would it be at all likely that a user wouldn't think the other
> possibility is true?
>> I don't expect the man pages to include the defaults in the Synopsis.
>>
> In man page Synopsis, it looks like this with curly braces around
> {false|true}:
>
> [--nopassword={false)|true}]
>
> We list the default first. We also state the default in the descriptions
> of the options.
As I said, I used the same syntax for boolean options as for other options
to be consistent. But I agree it seems unnecessarily verbose.
What do others think? Which do you prefer?
1. [--nopassword[=<nopassword(default:false)>]]
2. [--nopassword[=(default:false)]]
3. [--nopassword[={false|true}]]
In #3, is it clear that the default is false? And is it clear that
"--nopassword" is equivalent to "--nopassword=true"? I wouldn't
people to assume from any of these that, since false is the default
value of the option, if I don't specify any value ("--nopassword")
I get the default value. Ok, now I'm being paranoid...
Don't make me create another doodle poll! :-)