[darcs-users] Feedback on hunk splitting with Darcs 2.4 beta 1

[Eric Kow]

Hi Mark,

On Fri, Jan 15, 2010 at 21:10:59 -0500, Mark Stosberg wrote:
> I was interested to try the hunk splitting sometimes because I've wanted that
> feature myself at times. My first impression found it to be a frustrating and
> unintuitive experience. I'll try to explain why.

Thanks very much for the feedback!  This is what I've been hoping to get
when the hunk splitting first came online.

> Here's a "screenshot" of what it looked like for me:
> 
> ####################
> Interactive hunk edit:
>  - Edit the first set of lines to insert a new change before the current one.
>  - Edit the second set of lines to insert a new change after the current one.
> ===
> ===
>         use Data::Dumper;
>         warn Dumper ('foo!');
> ===
> 
> #####################
> 
> First, it's not clear what "set of lines" refer to. Is it referring to the
> "===" lines? I wouldn't call those sets. Maybe it is referring to the content between
> the === lines. But there nothing between the first two === lines, so referring to nothing
> as a "set of lines" is also confusing.

There's two issues here.  First, the separators are not well named.
This can be addressed by some variant of http://bugs.darcs.net/patch123

Second, and this is not readily apparent.  The hunk editor is very
simple and powerful in the usual Darcs style.  The only problem is that
this is a lot less intuitive than the rest of Darcs.

Once you have a sort of working mental model of it, though (eg. through
trial and error), it's really powerful and easy to use.

The problem is that getting people over that initial hurdle!  (We're
even contemplating hiding it for this release, which would be a little
sad, but better than giving people a bad first impression).

I'm going to try and do this now if you and Isaac will bear with me
(with Ganesh correcting me if I say something stupid).  Perhaps in light
of my explanation you'd be willing to offer up a solution?

Here are the ideas:

1. The hunk editor turns your hunk patch into a sequence of hunk patches

2. Any empty patch in that sequence is filtered out.

3. You can make arbitrary edits in the hunk editor.  One example use of
   this would be to clean up trailing whitespace on the spot.

4. Here's the wild and crazy part: the sequence of patches created by
   the hunk editor is COMPLETELY EQUIVALENT to the original patch.
   This means you can pop out the original patch, slip the sequence in
   and Darcs would be none the wiser. Huh?  How's that possible?...

5. The trick behind is that Darcs actually splits the patch into a
   sequence of three (or more) patches.  For now, I'll ignore the
   (or more) case and focus on the basic idea.
   
   The point is that you can think of the hunk editor as manipulating
   a sequence

     pb p1 pa

   When you fire up the hunk editor, pb and pa are empty and p1 is your
   original hunk.  In the editor, what you are doing is making arbitrary
   edits to p1 (both to the before and after sections).
   
   When you are satisfied with your edits, darcs automatically infers
   what pb and pa have to be in order to make the sequence equivalent to
   the original hunk. (NB: You may not always see pa and/or pb because
   in #2, empty hunks get filtered out.)

   Got that?  The more general explanation is that you are actually
   editing the sequence

     pb p1..pN pa

    Which you will only see if you use blank lines to break up blocks
    of text (like in regular Darcs usage).

I realise this sounds like wild and crazy over-excited talk for people
who just want to split some hunks, that I'm throwing a bunch of mumbo
jumbo out in response to what looks like a simple thing... but please
bear with me!

http://wiki.darcs.net/HunkEditor tries to document some of the
implications of #1-#5, but it's poorly written, for which I apologise.

I should say that I really hated the hunk editor UI when I first
encountered it, but then I started using it (a lot) and now I think it's
great!  It turns out to be very easy/convenient once you've internalised
that chunk of mental model.  I would definitely be very open to change
(and I'm sure Ganesh would as well), but it would be awesome if we could
somehow preserve this simplicity/power.

We keep thinking the right explanation is just around the corner...

One idea I had was to change the UI to look like this...

####################
Interactive hunk edit:
 - Changes outside of the EDIT regions will be ignored
=== BEFORE PATCH 0
some lines removed
some other lines removed
=== BEFORE PATCH 1 (EDIT BELOW) =======================================
some lines removed
some other lines removed
=== AFTER PATCH 1 
some lines added
some lines added
=== AFTER PATCH 2 (EDIT ABOVE) =======================================
some lines added
some lines added
===
#####################

The hope is that (with a tiny bit of text), this would make it more
explicit what's going on, that you can think of it as editing a sequence
of patches by manipulating the before and after states (but that you
can't touch the first and last bit of that sequence).  On the other
hand, this gets very awkward when the patch is large :-(

Argh! We need somebody who can think about user interfaces!

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 195 bytes
Desc: not available
URL: <http://lists.osuosl.org/pipermail/darcs-users/attachments/20100116/d662aae1/attachment.pgp>