Bill Shannon wrote:
> 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)>]]
With those line breaks in place, I vote for #1.
To me :- No confusion...no guesswork needed... legible...and consistent.
> 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! :-)
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: admin-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: admin-help_at_glassfish.dev.java.net
>