On 10/30/09 02:54 PM, Nandini Ektare wrote:
> 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.
I still think it's confusing to have the option stated again inside the
<replaceable> brackets.
User could get used to the idea of the default coming first, so I vote
for #3.
dixie
>> 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
>>
>
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: admin-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: admin-help_at_glassfish.dev.java.net
>