[PATCH V2] help: indicate help omitting if help document is not fully displayed

[Adrian Buehlmann]

On 2012-07-12 07:57, FUJIWARA Katsunori wrote:
> # HG changeset patch
> # User FUJIWARA Katsunori <foozy at lares.dti.ne.jp>
> # Date 1342072559 -32400
> # Node ID 18f587f1b4db2052d481bd83af8950a9ed865e85
> # Parent  2e13c1bd34dc6afda8fc7cfa22a8cd658276724f
> help: indicate help omitting if help document is not fully displayed
> 
> Before this patch, there is no information about whether help document
> is fully displayed or not.

..

> So, some users seem to misunderstand "-v" for "hg help" just as "the
> option to show list of global options" by their experience on "hg help
> -v" for some commands not containing verbose containers in their help
> document.

If you assumed that, then it's simply not true anymore. I don't see why
that should be a problem.

I think we never made a guarantee that --verbose is just meant for seeing
the global options.

Otherwise, we would probably have worded the

  use "hg -v help status" to show more info

as

  use "hg -v help status" to show the global options

But we didn't.

> Omitted help document is never seen by such users, and this may cause
> wrong or insufficient understanding about Mercurial.

Wrong? Certainly not. Why should the non-verbose help be wrong ever?

> This patch indicates help omitting, if help document is not fully
> displayed. This allows users to know whether there is any omitted
> information or not exactly, and can trigger "hg help -v" invocation by
> users.

I don't really like that. There's now a duplication:

Both

  (detailed description is omitted. use "hg help -v status" to show details.)

and

  use "hg -v help status" to show more info

are displayed, which clutters the non-verbose help yet again. We are now
informed *twice* to use -v to "show details" and "more info".

IMHO, that's overkill and redundant. The single

  use "hg -v help status" to show more info

is enough.