[MERGE] concise help for commands by default

[Martin Pool]

2009/2/13 Ian Clatworthy <ian.clatworthy at internode.on.net>:
> Martin Pool wrote:
>> Martin Pool has voted abstain.
>
>> I do think 'bzr help foo' should display all the help on foo, not just
>> the summary.  I'd rather instead see some or all of these:
>
> I'm fine with 'bzr help foo' showing the full text and 'bzr foo -h' showing
> the usage. That implies that help and -h aren't identical but I can't
> see why they have to be. If someone went to the trouble of typing
> 'bzr help foo' (vs 'bzr foo -h'), then the full help ought to be no
> surprise IMHO.

How about

  bzr help foo == bzr foo --help == long help
  bzr --usage foo (or bzr --short-help foo) == bzr -h foo == brief help?

>>  * merge or reimplement bzr-pager so that help is shown in a pager instead
>
> That would be good. I'm not sure it solves the 'don't show me everything,
> just the usage' issue that several users felt strongly about.
>
>>  * add a short form that gives you just the brief summary, like bzr foo
>> --usage
>
> I originally suggested 'bzr foo -?' but that got shot down in flames. :-)
>
>>  * split topics into smaller components, as you did with log-formats,
>> and we could add log-examples
>
> I think that's a slippery slope. Multiple topics is the right answer when
> the things are genuinely independent and meaningful in their own right.
> Having a whole bunch of xxx-examples topics separate to xxx help sounds
> wrong. 'bzr help foo' ought to tell me about foo, not redirect me to
> several subtopics simply because foo's help takes more than a page.

Right, I think you'd want to be looking for places where the split-off
part is either often uninteresting to readers of the main page, or
often interesting in isolation.  I think all commands should give some
examples.

-- 
Martin <http://launchpad.net/~mbp/>