[PATCH] expand and clarify help for update

[Adrian Buehlmann]

On 30.10.2008 09:34, Dirkjan Ochtman wrote:
> Adrian Buehlmann <adrian <at> cadifra.com> writes:
>> # HG changeset patch
>> # User Adrian Buehlmann <adrian <at> cadifra.com>
>> # Date 1225322906 -3600
>> # Node ID 94bae0c425ba312c560c7cbe889554ab5bfbbd30
>> # Parent  1493d1e05ca3034a104afca2f49aec2783be3df6
>> expand and clarify help for update
> 
> Like Giorgios, I think it's nice what you're trying to do here, but I don't
> think making it this long is very effective. Trying to describe every little
> corner case of update's behavior just means people won't read it all or get
> scared of using it. Let's instead give people an idea of what the purpose is
> (and what other commands could be used instead) and what the options are.

Funny thing is, Giorgios proposed a limit of 50 lines,
which the text after applying my patch would not
exceed.

And Giorgios didn't even say my patch results
in the help text being too long (so I fail to see
why you cite him this way).

I for one *do* think that describing how update
deals for example with parent revisions would be
valuable.

We have had a quite a couple of people not understanding
the concept of parent revisions in the past.

The help text, as it now is, is talking about
merging into the user's changes. We would be better off
explaining the effect of a real uncommitted 'hg merge'
regarding update -C as well. This is not just a
"little corner" case, as you label it.

As a side note, it's quite amazing that an expert
like you wants to suppress important information
for the sake of "not scaring people".

Of course you already know it. But people trying to
understand what update does should better know how
complex this command really is.

Not that I would want to waste my time trying to
get my patch in any longer, but your arguments are
quite weak.

Not everyone can afford paying support for Mercurial
(as you offer) and ask back on every not documented
situation. Mercurial is definitely not for "Aunt Tilly"
with djc in the back to explain her every single
hg call she enters and doesn't figure out how it
works.

The text of hg help, as it currently is, is lousy at
best. And it has been in that state for quite a long
time now.

The update command is far more complex than newbies
ever expect. And it can be perfectly well described
in under 50 lines of text, as I have demonstrated.

The same amount of text as we already have on hg
clone, which is BTW far less critical than update -C
or update silently merging into local changes.

Instead of trying to letting me look silly ("it's nice
what you are trying to do, but ... "), you could have
made a constructive proposal how to rewrite my text
to make it more dense (which would be easy as others
in this thread already have demonstraded).

Instead you falsely represent Giorgio's post to
quickly rule out this thread.

This is quite disappointing.

Best regards,

Adrian