[MERGE] concise help for commands by default

[Ian Clatworthy]

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.

>  * 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.

My 2c,
Ian C.