On 10/22/09 12:54 PM, Nandini Ektare wrote:
> Dixie Pine wrote:
>> On 10/21/09 09:14 PM, Nandini Ektare wrote:
>>>
>>>>> *BUG?* 4848 and 8080 should not be in the command message, but they
>>>>> are. They should be shown as <adminport> and <instanceport>
>>>>> replaceables. I changed the man page. Can the command message be fixed?
>>>>>
>>>>
>>>> It's a feature. :-)
>>>>
>>>> Seriously, people asked for the usage message to indicate the default
>>>> values of the options, where they're known, so that's what the code does.
>>>> If there's consensus that that should be removed, that's easy to do.
>>>>
>>>> Let's see what people think. I created a poll...
>>>>
>>>> http://sun.doodle.com/6t38vi48u5uyvpg4
>>>>
>>> I like the feature because
>>> 1. It's like example and usage merged together (thought it may not
>>> be a widely used practice, I feel it 's convenient)
>>> 2. More important: In v3 we can't see defaults in the usual place --
>>> domain.xml. So this feature helps to that end.
>> If we are choosing to do this (include defaults for replaceables) you
>> need to do it everywhere, which you don't.
> Hmm..I see defaults in the commands I was working on recently (I have
> not checked other commands):
>
> Usage: asadmin [asadmin-utility-options] create-ssl --certname
> <certname> --type <type> [--ssl2enabled=true] [--ssl2ciphers
> <ssl2ciphers>] [--ssl3enabled=true] [--ssl3tlsciphers
> <ssl3tlsciphers>] [--tlsenabled=true] [--tlsrollbackenabled=true]
> [--clientauthenabled=true] [--target <target>] [-?|--help=false]
> [listener_id]
>
> Usage: asadmin [asadmin-utility-options] create-network-listener
> [--address <address>] --listenerport <listenerport> [--threadpool
> http-thread-pool] --protocol <protocol> [--transport tcp]
> [--enabled=true] [--jkenabled=false] [-?|--help=false] name
It's true that the practice of only including the default boolean is
everywhere. That's not such as big problem. At least, I think users can
figure that out (however, it does look like they should type
--enabled=true). It's the practice of including the value, such as 4848,
rather than the replaceable <adminport> that is the problem. Neither of
the examples above does that, but create-domain does:
Usage: asadmin [asadmin-utility-options] create-domain --user <user>
*[--adminport 4848] [--instanceport 8080] *[--portbase <portbase>]
[--profile <profile>] [--template <template>] [--domaindir <domaindir>]
[--savemasterpassword=false] [--domainproperties <domainproperties>]
[--keytooloptions <keytooloptions>] [--savelogin=false]
[--checkports=true] [--nopassword=false] [-?|--help=false] domain_name
As Paul mentioned, we get bugs against the man pages when people type
such a literal because they don't understand it's a replaceable. That's
why we want the usage message to only indicate replaceables, such as
<adminport>. The man page is pretty accessible if they need info on an
option. Defaults are mentioned there for all options, not just a few of
them.
Dixie
>
> Nandini
>> This is why users get confused and think they should type
>> 4848---because they don't see this often in a command message.
>>
>> Do you all really want to redo all the messages to include default
>> values? And how would you describe this is the message?
>>
>> The defaults are listed in the man pages with the descriptions of the
>> options in the Options section, in a much more complete way than they
>> can be shown in Synopsis or in a command message.
>>
>> While we're discussing this, the true|false presentation would be
>> better if the actual boolean were shown. First listed would be the
>> default. Users could get used to that and not think they should type
>> true.
>>
>>
>>>
>>>
>