Improve cmd-line help output. #docfixit

Review Request #2599 - Created Aug. 11, 2015 and submitted

Benjy Weinberger
jsirois, zundel

- Only print help for the scopes the user asked for (and anything
under them). Previously we printed help for all tasks under any
goals the user specified. E.g., `./pants help` would
print all compile help, including those for other tasks.
- Print help for subsystems, if asked. E.g., ./pants help cache
now shows help for global cache options. This falls nicely out of the
implementation of the point above.
- Be smarter about detecting whether a cmd-line token is a target spec
or an unrecognized scope, so we can issue an appropriate error in
the second case.
- Print the first line of an optionable's docstring in the help.

TODO: The subsytem help printing still needs some work. For example
you can do 'pants help jvm' and get help for the global jvm
subsystem, even though nothing uses it. John's pending change
to have subsystems know what scope they're embedded in should
help here.

TODO: This no longer prints the goal description before the help for all
options for tasks under the goal. But that can easily be restored
by making Goal an Optionable with a description (but, presumably,
no registered options). Will follow up with this soon.

CI passes:

Benjy Weinberger
Benjy Weinberger
Eric Ayers
John Sirois
Stu Hood
John Sirois
Eric Ayers
Benjy Weinberger
Review request changed

Status: Closed (submitted)

Change Summary:

Submitted as ef7c8b9ccfe4eeefd97d639fcf7593fc88edb9e2.