[PATCH] expand and clarify help for update

[Matt Mackall]

On Fri, 2008-10-31 at 18:50 +0100, Adrian Buehlmann wrote:
> 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.

Food for thought: the following sentence can be parsed two ways
depending on how you group the clauses:

"Like Sam, I like jelly, but I hate blueberry jelly."


There are perhaps 3 levels of detail that we might want in help:

a) is this the command I want? (one line description)
b) ok, how the hell do I use it? (a few concise paragraphs and examples
to get started)
c) what about if I want to do x with it? (more writing and lots of
examples)

Level (b) is important because people are impatient and easily confused.
When trying to use update for the first time, we may not want to throw
concepts like 'named branches' at them. They may cry.

Originally, Mercurial had levels (a) and (b), and people have slowly
expanded help for some commands into (c). As we don't have any better
place to put level (c), there's been only half-hearted back pressure
against this. We do in fact want and need (c), but we also want (b).

So here's a simple proposal: add a -v switch to help topics to allow
showing otherwise omitted sections of the help. Perhaps lines in help
prefixed with '%' or some other character get removed without -v and
displayed (without %) with -v.

ps: I like blueberry jelly.
-- 
Mathematics is the supreme nostalgia of our time.