[RFC] Concise vs comprehensive help - do we need both?

[Ian Clatworthy]

Marius Gedminas wrote:
> On Sat, Jan 31, 2009 at 07:04:51PM +1100, Ben Finney wrote:

>> Multi-page verbosity should not be something associated with a
>> commonly-used option like ‘--help’, but rather something that
>> indicates it's verbose, such as ‘--help --verbose’ or ‘--help --long’.
> 
> This makes most sense to me, especially if the short help page mentions
> the existence of the long one.
> 
>   $ bzr help merge
>   Purpose: ...
>   Usage: ...
>   Options:
>     ...
> 
>   See bzr help -v merge for more details and examples.

That sounds fine to me. I guess I have a slight preference for:

* bzr xxx -h showing Purpose, Usage and Options only
* bzr help xxx showing all sections

but I'm happy either way. "help -v" is certainly preferably IMO to
introducing "bzr man ..." say.

Just to be clear, we're saying that help/-h ought be to changed to no
longer show the Description and Example sections. Instead, the final
line of the output will point users to "help -v" for these.

Ian C.