admin@glassfish.java.net

Re: Final Review of create-domain man page

From: Paul Davies <Paul-Martin.Davies_at_Sun.COM>
Date: Wed, 21 Oct 2009 18:58:46 -0700

Hi,

> If --portbase is omitted --adminport defaults to 4848 --instanceport
> defaults to 8080 , so it will show up in the command usage as default
> values.
I am working actively to discourage the practice of including the
default value for options instead of a placeholder in the Synopsis
section of man pages. This practice confuses users, who think that the
default value is part of the syntax and must be typed literally as is.
The convention of stating the default in this way is not widespread and
is lost on most users. It has led to bugs being filed against man pages
in the past.

Ideally, to prevent user confusion, and for consistency with the man
pages, the usage messages from the asadmin subcommands should also avoid
this practice.

Regards,

-- 
Paul Davies, Senior Technical Writer, Sun Microsystems, Inc.
http://blogs.sun.com/techscribe/