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
>
>