[PATCH] commit: move help about --amend into verbose section

[Adrian Buehlmann]

On 2012-07-11 12:52, Martin Geisler wrote:
> Adrian Buehlmann <adrian at cadifra.com> writes:
> 
>> # HG changeset patch
>> # User Adrian Buehlmann <adrian at cadifra.com>
>> # Date 1341994525 -7200
>> # Node ID f7d6aed0b593c7574effce913229bee4f623cf3a
>> # Parent  6defd83a3657c5acf46284c25b3d4e6c045f5a96
>> commit: move help about --amend into verbose section
>>
>> This is a pretty advanced feature. It should be ok to require
>> --verbose to get that text.
> 
> I would like to keep the description of --amend in the main text. I fear
> that few users will notice the 'use "hg -v help commit" to show more
> info' line at the bottom. Even if they do notice, then they might assume
> that it'll just show the boring global options and so disregard it.

I think that's a general question, and the answer has already be given
by Matt having accepted and used verbose sections.

If there is a section applicable to the verbose pattern, then I think
it's surely advanced, rarely used, longwinded things like the details
about --amend, which is pretty scaring for new users anyway, talking
about bundles and whatnot.

And even regulars who just want to look up a few options are annoyed if
they get that much text thrown at them in the terminal.

It's also quite easy to discover that the default help text doesn't
mention the --amend option at all, the conclusion that there might be
more things said with --verbose isn't that hard to draw (given the
ending "use "hg -v help commit" to show more info).

But it's surely a topic that can be easily discussed to death, with an
abundance of opinions :-)

> In a HTML version of the help we could hide the verbose section behind a
> "show more" link directly in the text and then expand the help when it
> is clicked. That would tidy up the help while not hiding the verbose
> sections too far away.

That's just needless fancyness, I think. For the html help, I think
there's no problem always showing the full help. It's much easier to
scroll there than in a command shell terminal. The html help is also
more used as a detailed reference than when quickly looking up something.

> Maybe we could consider writing "(3 paragraphs hidden, use -v to see
> them)" into the text when we suppress a verbose section on the console?

I don't like that.

> I don't think it would look very pretty and knowing myself, I would be a
> little annoyed that the software "hides" information for me :)

We already do have that hiding (see above). So that decision has already
been made.