Agreed.
Paul Davies wrote on 11/03/09 12:33:
> This discussion applies only to the short usage strings that appear when
> someone leaves out a required parameter or enters an unsupported option.
>
> The man pages do not have the space constraints of the usage messages
> and, therefore, can follow a different set of conventions, for example,
> not stating default values of options in the Synopsis but only in the
> Options section.
>
> On 11/03/09 10:15, June.Parks_at_Sun.COM wrote:
>> Just to clarify: Are we discussing only the short usage strings that
>> appear when someone leaves out a required parameter or enters an
>> unsupported option, such as this?
>>
>> asadmin create-domain --foo
>>
>> Or are we also discussing the man pages that appear when someone
>> explicitly calls for them, such as this?
>>
>> asadmin create-domain --help
>>
>> The (default:false) construction wouldn't work very easily with the
>> font conventions we use in the PDF versions of the man pages. We
>> don't use angle brackets. We use italicized text. The question
>> arises whether we should do this:
>>
>> --savelogin=/savelogin/(default:false)
>>
>> Or this:
>>
>> --savelogin=/savelogin(default:false)/
>>
>> Listing all the values as we've done previously in the man pages
>> avoids some confusion by not italicizing anything:
>>
>> --savelogin={false|true}
>>
>> We don't necessarily have to use the exact same conventions in the
>> usage strings and the man pages. The PDF man pages use fonts that the
>> usage strings can't use. Because the man pages list defaults in the
>> detailed descriptions of the options, listing the defaults in the
>> syntax summaries isn't so important. But I can see the value of
>> listing defaults in the usage strings.
>>
>> June
>>
>> On 11/02/09 17:03, Bill Shannon wrote:
>>> 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.
>>>
>>> ---------------------------------------------------------------------
>>> To unsubscribe, e-mail: admin-unsubscribe_at_glassfish.dev.java.net
>>> For additional commands, e-mail: admin-help_at_glassfish.dev.java.net
>>>
>>>
>>
>
> --
> Paul Davies, Senior Technical Writer, Sun Microsystems, Inc.
> http://blogs.sun.com/techscribe/
>