Dixie Pine wrote on 10/30/09 16:16:
>
>
> 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.
I didn't get a lot of input on this, and there was certainly no
consensus emerging, so I asked Jerome for an executive decision. :-)
Jerome chose #1, so we'll go with that for now.