8189102: All tools should support -?, -h and --help

[Lindenmaier, Goetz]

Hi,

I think this basic recommendation how to format help messages is
good.
Unfortunately the tools follow very different strategies of formatting.
Many list the shortcut first.
In the link below you can find the test output of the test in this change. It includes
all help messages of all tools affected.  (I modified the test to print
each message only once.)  Search for --help in the file:
http://cr.openjdk.java.net/~goetz/wr17/8189102-helpMessage/webrev.03/HelpFlagsTest2.jtr

I already fixed jshell to the recommended format.

I think in most cases the documentation of --help fits to the format.
For jmod, which has lots of -- options, I could easily establish the 
ordering proposed by you, but I would have to change "--module-path, -p", 
too.

Best regards,
  Goetz.





> -----Original Message-----
> From: Jonathan Gibbons [mailto:jonathan.gibbons at oracle.com]
> Sent: Donnerstag, 23. November 2017 00:24
> To: Robert Field <robert.field at oracle.com>; compiler-
> dev at openjdk.java.net; Lindenmaier, Goetz <goetz.lindenmaier at sap.com>
> Subject: Re: 8189102: All tools should support -?, -h and --help
> 
> I agree with putting the long form first, followed by single-letter forms.
> 
> Using a comma to separate alternative forms is good, leaving white space
> to separate option and arg. For example, see these lines from javac --help
> 
>    --module <module-name>, -m <module-name>
>          Compile only the specified module, check timestamps
>    --module-path <path>, -p <path>
>          Specify where to find application modules
> 
> 
> -- Jon
> 
> On 11/22/2017 11:20 AM, Robert Field wrote:
> > Per jshell tool --
> >
> > Thanks for adding to the test.
> >
> > As to the option formatting:
> >
> >  219 \    -? -h --help          Print this synopsis of standard
> > options and exit\n\
> >  220 \    --help-extra, -X      Print help on non-standard options and
> > exit\n\
> >
> > The number one priority is that it is consistent: comma vs space,
> > --option first vs last.
> >
> > The number two priority is best readability.  These options are
> > surrounded by --options, so that first seems best to me.
> > The comma seems clearer to me, and is used in a good percentage of the
> > tools you listed.
> >
> > So, my preference is:
> >
> >  219 \    --help,-?, -h        Print this synopsis of standard options
> > and exit\n\
> >  220 \    --help-extra, -X      Print help on non-standard options and
> > exit\n\
> >
> > Thanks,
> > Robert
> >
> >
> > On 11/22/17 09:28, Lindenmaier, Goetz wrote:
> >> Hi,
> >>
> >> I prepared a new webrev trying to incorporate all change requests:
> >>   * I removed changes to non-english property files.
> >>   * I removed help texts from ktab, kinit, klist
> >>   * I removed changes to corba tools
> >>   * I added test cases for new flags to tool specific tests (to the
> >> ones I spotted)
> >>   * I added -help back to javac
> >> I left the removal of -help from Javadoc, as Javadoc just prints the
> >> help message
> >> anyways.
> >>
> >> New webrev:
> >> http://cr.openjdk.java.net/~goetz/wr17/8189102-
> helpMessage/webrev.03/index.html
> >>
> >>
> >> I uploaded the parts of the patch I removed within the webrev:
> >> http://cr.openjdk.java.net/~goetz/wr17/8189102-
> helpMessage/webrev.03/help_in_property_files.patch
> >>
> >> http://cr.openjdk.java.net/~goetz/wr17/8189102-
> helpMessage/webrev.03/KinitKtabKlist_help_message.patch
> >>
> >> http://cr.openjdk.java.net/~goetz/wr17/8189102-
> helpMessage/webrev.03/corba_help_message.patch
> >>
> >>
> >> Best regards,
> >>    Goetz.
> >>
> >>
> >>> -----Original Message-----
> >>> From: serviceability-dev [mailto:serviceability-dev-
> >>> bounces at openjdk.java.net] On Behalf Of Lindenmaier, Goetz
> >>> Sent: Friday, November 17, 2017 12:23 PM
> >>> To: core-libs-dev at openjdk.java.net; 'compiler-dev at openjdk.java.net'
> >>> <compiler-dev at openjdk.java.net>; serviceability-dev (serviceability-
> >>> dev at openjdk.java.net) <serviceability-dev at openjdk.java.net>
> >>> Subject: RFR: 8189102: All tools should support -?, -h and --help
> >>>
> >>> Hi,
> >>>
> >>> please review this change. I also filed a CSR for this:
> >>> http://cr.openjdk.java.net/~goetz/wr17/8189102-
> helpMessage/webrev.02/
> >>> Bug: https://bugs.openjdk.java.net/browse/JDK-8189102
> >>> CSR: https://bugs.openjdk.java.net/browse/JDK-8191477
> >>>
> >>> See the webrev for a detailed description of the changes.
> >>>
> >>> If required, I'll make break-out changes to be reviewed separately.
> >>>
> >>> I had posted a RFR before, but improved the change to
> >>> give a more complete overview of currently supported flags
> >>> for the CSR:
> >>> http://mail.openjdk.java.net/pipermail/hotspot-dev/2017-
> >>> October/028615.html
> >>>
> >>> Best regards,
> >>>    Goetz.
> >