[PATCH] expand and clarify help for update

[TK Soh]

On Fri, Oct 31, 2008 at 6:39 PM, Matt Mackall <mpm at selenic.com> wrote:
> 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.

I like this idea. Considering the number of lines that fit into one
terminal window, I for one hate to have to scroll up (assuming that I
could), or remember to pipe to less all the time, to know what the
command (level a & b) is about.