[
https://issues.apache.org/jira/browse/HADOOP-9158?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=13586411#comment-13586411
]
Jonathan Allen commented on HADOOP-9158:
----------------------------------------
The ant example just has a generic "ant [options] [target [target2 [target3]
...]]" usage whereas the Hadoop usage command lists the available options, eg
"Usage: hadoop fs [generic options] -ls [-d] [-h] [-R] [<path> ...]". If using
HelpFormatter.printUsage then you either give it a fixed syntax message (which
loses some of the point of using the Options) or you give it the Options but
that then loses the arguments, ie prints "... -ls [-d] [-h] [-R]".
It feels a bit clunky to capture the formatted text and then reformat it,
especially as the HelpFormatter only allows printing to a PrintWriter (rather
than returning a formatted string). It can be done but seems to be asking for
trouble.
Newlines within the text are handled OK but it then forces a trim on the new
line. The current ls help produces the following text
List the contents that match the specified file pattern. If
path is not specified, the contents of /user/<currentUser>
will be listed. Directory entries are of the form
dirName (full path) <dir>
and file entries are of the form
fileName(full path) <r n> size
where n is the number of replicas specified for the file
and size is the size of the file, in bytes.
Using HelpFormatter would produce the following (forcing the example entries to
the left).
List the contents that match the specified file pattern. If
path is not specified, the contents of /user/<currentUser>
will be listed. Directory entries are of the form
dirName (full path) <dir>
and file entries are of the form
fileName(full path) <r n> size
where n is the number of replicas specified for the file
and size is the size of the file, in bytes.
I just think the existing formatting looks better and is more readable.
I'm happy with stopAtNonOption, the problem is that if this is true then a
single dash gets treated as an option terminator rather than the first argument
(see
http://svn.apache.org/viewvc/commons/proper/cli/trunk/src/main/java/org/apache/commons/cli/Parser.java?revision=1445352&view=markup
line 186). You then need an explicit double dash to force and end to the
options but this changes the existing functionality. I think it's a good change
because it makes it more consistent with standard linux commands but it's still
a change.
> Tidy up fs -help
> ----------------
>
> Key: HADOOP-9158
> URL: https://issues.apache.org/jira/browse/HADOOP-9158
> Project: Hadoop Common
> Issue Type: Improvement
> Reporter: Jonathan Allen
> Assignee: Jonathan Allen
> Priority: Minor
> Attachments: HADOOP-9158.patch
>
>
> There are a number of issues with the current fs -help implementation that
> could do with tidying up.
> 1) Running 'hadoop fs -help' displays the full detailed help for all
> commands. This produces a large amount of text and makes it hard to find
> what you're looking for. Better functionality would be:
> - hadoop fs -usage : shows the basic usage information for all commands
> - hadoop fs -help : shows usage and brief summary (couple of lines) for all
> commands
> - hadoop fs -help <command> : shows full description of the specified command
> 2) Help text is hardcoded into each command class. This should be replaced by
> resource files to allow internationalisation.
> 3) Line breaks are hardcoded into the help text. The help text should be
> auto-formatted at display time.
--
This message is automatically generated by JIRA.
If you think it was sent incorrectly, please contact your JIRA administrators
For more information on JIRA, see: http://www.atlassian.com/software/jira
