I couldn't resist this. I tried, but I really couldn't restrain myself.
You said:
I'll look in to why --echo is preceded by two spaces.
Could it be that it is preceded by just *one* space? One, *and its
echo*, that is?
Nah.
~Eric
Paul Davies wrote:
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/