Bill Shannon wrote:
> Dixie Pine wrote:
>>
>>
>> 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]
> I'd be happy to do something like that, but I think that syntax is
> problematic.
> How would people feel about something like this:
>
> [--adminport <adminport(default:4848)>]
> [--transport <transport(default:tcp)>]
> [--enabled=<enabled(default:true)>]
[Thinking aloud] It sure does give more info. But if there were bugs, as
docs team stated, because someone used 4848 as is, this kind of
nomenclature as well as the one above seems to have a high bugs
potential. Plus some of the commands with many options are already
pretty lengthy. Such verbose usage will reduce the usage reference
appeal further. To me, usage has to be short as it is a means of quick
reference. If the user needs more info on any particular option, man
page should provide all the details needed.
But then again any existing standards and practices on this may have
better reasons to support such detailed usage text.
Nandini
> It's kind of verbose, but does it solve both problems?
>
> For boolean options perhaps we just list the choices with the default
> first:
>
> [--enabled={true|false}]
>
> or, to be more correct
>
> [--enabled[={true|false}]]
>
> Comments?
>
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: admin-unsubscribe_at_glassfish.dev.java.net
> For additional commands, e-mail: admin-help_at_glassfish.dev.java.net
>