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/