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

[Martin Geisler]

Adrian Buehlmann <adrian at cadifra.com> writes:

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

I hope --amend will be a commonly used flag in the future. I 'qimport;
qrefresh; qfinish' daily and some of that could be replaced with the
simpler --amend flag.

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

Okay, that's also an issue.

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

Yes and no... I fear some people will just assume we've forgot to
document it :)

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

No doubt about that...

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

Right and I see you've sent a patch for this. It's in crew now.

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

Nah, it was also just a quick idea :)

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

We've been hiding usage examples here and there. That's okay since we're
hiding the easy stuff. You're talking about hiding the more advanced
stuff, which I feel goes in the opposite direction.

-- 
Martin Geisler

aragost Trifork
Commercial Mercurial support
http://aragost.com/mercurial/