Hi Dies,
A random sampling of Solaris man pages suggests that the convention is
to have do it the way you suggest, with the spaces between the square
brackets:
zfs create [[-o property=value]]... filesystem
zfs create [-s] [-b blocksize] [[-o property=value]]... -V size volume
man [-] [-adFlrt] [-M path] [-T macro-package] [-s section] name.
So I think that your suggestion is probably better, especially as man
pages are read by people and not parsers.
For the alternatives separated by pipe, I agree that when the option is
followed by an option argument, spaces around the pipe symbol enhances
readability, as your example demonstrates:
<classfile> | -client <appjar>
Without the extra spaces, at first glance, -client seems more closely
related to <classfile> than <appjar>:
<classfile>|-client <appjar>
For the options without option arguments, the presence or absence of
spaces has little effect on readability:
--echo={true|false}
--echo={true | false}
So, provided there's no danger of users typing --echo= false (which
would be a syntax error), I would suggest always including spaces either
side of the pipe symbol for consistency.
I'll look in to why --echo is preceded by two spaces.
Thanks for all this feedback. Your comments will help improve the
quality of the GlassFish documentation.
Regards,
-Paul
On 05/05/09 18:51, Dies Koper wrote:
> Hi Paul,
>
> I was thinking of doing it the following way. (I haven't check how
> other (non-GF) commands do it, though.)
>
> deploy
> [--terse={true|false}] [--echo={true|false}]
> ...
>
> I feel this way the grouping (the optional parts) are clearly visible.
> Your way might be grammatically better and clear to a parser but at
> first glance I see three groups "[", "--terse={true|false}][" and
> "--echo={true|false}]", which gave me a first impression of it looking
> messy.
>
> Also, I don't understand why you put two spaces before '--echo' (typo
> I assume?).
>
> So to give a full example of my suggested way:
>
> deploy
> [--terse={true|false}] [--echo={true|false}]
> [--interactive={true|false}] [--host host]
> [--port port] [--secure | -s] [--user admin_user]
> [--passwordfile filename] [--help]
> [--virtualservers virtual_servers]
> [--contextroot context_root] [--force={false|true}]
>
> I'm not sure whether to include spaces around '|' symbols consistently
> or not. Here I feel with single words it's nice and compact without,
> but with multiple words (like appclient's "[<classfile> | -client
> <appjar>]") it's better with. I feel no particular preference with
> [--secure|-s] or [--secure | -s].
> I'd like to hear your thoughts.
>
> Thanks,
> Dies
>
>
> Paul Davies wrote:
>> Hi,
>>
>> Please work with the GlassFish documentation community to ensure that
>> these changes are propagated to all versions of these man pages (such
>> as the online version that is published on docs.sun.com). Rather than
>> edit the man pages directly, please use the document comment page or
>> file an issue.
>>
>> I think that the correct syntax should have a space after the opening
>> square bracket to indicate that the space is required only if the
>> option that follows is specified:
>>
>> deploy
>> [ --terse={true|false}][ --echo={true|false}]
>> ...
>>
>> Please let me know if you agree.
>>
>> Regards,
>> -Paul
>>
>>
>> On 05/05/09 17:52, Dies Koper wrote:
>>> Hi Hong,
>>>
>>>>> deploy
>>>>> [--terse={true|false}][ --echo={true|false} ]
>>>>> [ --interactive={true|false} ] [ --host host]
>>>>> [--port port] [--secure| -s ] [ --user admin_user]
>>>>> [--passwordfile filename] [--help]
>>>>> [ --virtualservers virtual_servers]
>>>>> [--contextroot context_root] [--force={false|true}]
>>>>>
>>>>> Why do you only sometimes put a space between the bracket and
>>>>> option, or between a closing bracket and the next opening bracket?
>>>>
>>>> Most likely these were just inherited from v2. Guess people just
>>>> did not pay enough attention to these details. Feel free to fix
>>>> them! :-)
>>>
>>> I think I will!
>>>
>>> Speaking of paying attention to details, I tried starting a
>>> discussion in the dev ML a while ago about fixing typo's and
>>> inconsistent message IDs. I have noticed that only the DPL messages
>>> are surrounded by double quotes. I've previously tried experimenting
>>> with a custom logger handler to pick up messages with a certain ID
>>> and needed to add special processing to compensate for these double
>>> quotes.
>>> May I remove them from your messages?
>>>
>>> Thanks,
>>> Dies
>>>
>>
>> --
>> Paul Davies, Senior Technical Writer, Sun Microsystems, Inc.
>> http://blogs.sun.com/techscribe/
>
--
Paul Davies, Senior Technical Writer, Sun Microsystems, Inc.
http://blogs.sun.com/techscribe/