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

[Ian Clatworthy]

Stephen J. Turnbull wrote:

> In the Unix tradition, there is no "the help".  At a bare minimum,
> there is the *usage*, and there is the *man page*.

Well put - that's what I was trying to say. Right now, -h shows the
"man page" with the usage at the top. If we want -h to be the usage
only, we should make it so (rather than put arbitrary limits on the
size of the man page).

>  > * "bzr help xxx" and "bzr xxx -h" give comprehensive help
> 
> The default should be short help.  Even fairly new users will often be
> looking for something very simple ("I know there's a 'verbose' log
> format, but it's not 'verbose' and it's not 'full'...").  Having to
> wade through several pages to find the single word you need is enough
> to break your train of thought.

Well, the usage and option information is at the top. IMO, the bigger UI
issue is not knowing whether the pipe the output into less/more or not.
If -h is just the usage, then you can be reasonably certain that using
a pager isn't needed. That's certainly good I think: I hate it when the
more useful information scrolls off the screen.

Ian C.