[PATCH] expand and clarify help for update

[Dirkjan Ochtman]

On Fri, Oct 31, 2008 at 18:50, Adrian Buehlmann <adrian at cadifra.com> wrote:
> 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).

Upon review, you're right, and I am sorry for misrepresenting his
position. He did say that he was "amazed at how long this has started
becoming" and that he gets "extremely annoyed" when p4 throws "what
seems to be a poorly formatted manpage" at his face.

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

I do agree that there is value in describing this.

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

Right, because people are used to systems where the parent revision is
always a head (and where there's only one parent).

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

The effect of update -C is the same whether a merge is going on or
not. I would venture a guess to say that uncommitted merges are not
the most often state in which up -C is used. The "little" part is of
course debatable, but since the effect of -C isn't different in the
merge case from the other cases, I do think it's in some way a "corner
case".

> 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, I do not want to suppress important information. I also
don't want to add much more help text to the help for any given
command then is necessary to understand the workings of the command,
because I think there is a very real possibility that users will think
the command is more complex than it really is (because of explanations
of the way a few completely orthogonal options interact), and yes,
some people are scared by complexity.

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

Please stop with your frustrated attitude. I'd much rather have you
debating my messages/opinions (like this email) then giving up in
frustration. If you think my arguments are weak, by all means point
out to me why this is the case.

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

I haven't ever provided paid support for Mercurial (though I have
provided quite a lot of unpaid support!), and if I did, it would
probably be development work, no hand-holding. This seems like a
circumstantial ad hominem-attack, trying to imply that
less-than-optimal documentation is somehow to my benefit.

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

I don't think it's that bad. The fourth paragraph contains a stupid
run-on sentence explaining an exceptional case, which could probably
be better, but most of the other help text seems quite alright.

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

I was certainly not trying to make you look silly. I honestly
appreciate your effort in improving the documentation (as I appreciate
your other improvements, first in improving the wiki quite a lot,
later in very important patches like the fncache one). I'd like to
propose an alternative help text for update, but so far haven't had
the time to come up with one (for me, writing concise and useful
documentation requires quite a bit of effort).

Please remember that I will never try to insult you. When I do, it is
by accident.

Cheers,

Dirkjan