On 10/22/09 02:51 PM, Nandini Ektare wrote:
> Dixie Pine wrote:
>>
>>
>> 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
> It does :)
> --transport if not specified is defaulted to tcp and that's what the
> command shows.
Yes, you're right. I missed that. And it is the problem. If we do it for
one option, we need to do it for all options. In all commands. I don't
actually know how many such situations there are (where a non-boolean
has a default). If there aren't very many, perhaps we could devise a
way to indicate that the replaceable has a default value. Something like
this?
[--adminport <adminport> 4848 default]
[--transport <transport> tcp default]
In doc, we just want to avoid more bugs against the man pages when
people don't understand the replaceable.
Dixie
>
> 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
>> 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.
>>>>
>>>>
>>>>>
>>>>>
>>>
>