Here is an attempt at friendlier online help for the interactive hunk editing.

The idea is to just give instructions for the most common use (hunk splitting)
and then hint to the user that the system generalises beyond that by saying
that they can make any edits they want.  The manual would need to follow up
by saying something to the effect that if you make modifications, Darcs will
automatically compute 'filler' patches before and/or after the current patch;
and that you may record or revert these filler patches at will. 

I tried saying that in the online help, but it took up two or three lines.

Tue Dec 29 01:26:13 GMT 2009  Eric Kow <kowey@darcs.net>
  * Name the separators in the hunk splitting interface.

Tue Dec 29 01:45:06 GMT 2009  Eric Kow <kowey@darcs.net>
  * Improve online help for hunk-splitting.

Attachments

• name-the-separators-in-the-hunk-splitting-interface_.dpatch
• unnamed

Here is a third idea:

== BEFORE PATCH 1 (LOCKED)
foo
bar
== BEFORE PATCH 2 (EDIT HERE)
xxx
foo
bar
== AFTER PATCH 2 (EDIT HERE)
bar
yyy
== AFTER PATCH 3 (LOCKED)
== 

Tue Dec 29 01:26:13 GMT 2009  Eric Kow <kowey@darcs.net>
  * Name the separators in the hunk splitting interface.

Tue Dec 29 01:45:06 GMT 2009  Eric Kow <kowey@darcs.net>
  * Improve online help for hunk-splitting.

Tue Dec 29 07:21:39 GMT 2009  Eric Kow <kowey@darcs.net>
  * More self-explanatory interactive hunk editor.
  By repeating the before and after blocks, we convey the idea that the hunk
  will be broken into up to three patches.

Attachments

• name-the-separators-in-the-hunk-splitting-interface_.dpatch
• unnamed

I think I like the general way this is heading, but we need more general user
feedback to get a good idea. I wonder if we can form a panel of people who are
interested in the UI of this feature to help with discussing the ideas.

Also, "You can split the current change into up to three patches" is technically
incorrect, because you can do things such that many more than three
patches/changes are generated, e.g. by inserting lines spaced out through the
patch. Perhaps it's not necessary to be too pedantic about it though.

On Wed, Jan 13, 2010 at 21:42:30 +0000, Ganesh Sittampalam wrote:
> I think I like the general way this is heading

I'll note that having used my version of it a little bit, one annoyance
is that while it's more explicit, and I think helps the user get a
mental model for what's happening, it's also a pain when the patches are
big.. it just dumps a lot of useless text on the screen (useless if
you've already got the mental model).  Can't win!

Maybe we're stuck with

 (i) quick instructions for the most common task -- splitting a patch

 (ii) some sort of concise explanation (ever elusive!)

 (iii) a recommendation to see 'darcs help hunkeditor' for examples on
       how to use this for fancier splits

> but we need more general user feedback to get a good idea. I wonder if
> we can form a panel of people who are interested in the UI of this
> feature to help with discussing the ideas.

That would be good over the long term.

What should we do in the short term?  One answer is to NOT make very
much noise about hunk splitting, and in the release announcement and the
help text, just say that it's experimental with the UI subject to
change.

> Also, "You can split the current change into up to three patches" is technically
> incorrect, because you can do things such that many more than three
> patches/changes are generated, e.g. by inserting lines spaced out through the
> patch. Perhaps it's not necessary to be too pedantic about it though.

Oh, I had not considered that.  My own mental model was wrong a second
time!  I guess this goes to show that this can still be useful even if
you don't have 100% the right idea HOW it works.

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9

3 patches for repository http://darcs.net:

Ganesh: this implements some ideas from last night and this morning.
More details to follow in my reply to Zooko.

Tue Dec 29 01:26:13 GMT 2009  Eric Kow <kowey@darcs.net>
  * Name the separators in the hunk splitting interface.

Tue Dec 29 01:45:06 GMT 2009  Eric Kow <kowey@darcs.net>
  * Improve online help for hunk-splitting.

Mon Jan 18 14:56:59 GMT 2010  Eric Kow <kowey@darcs.net>
  * Simpler and more intuitive help text for hunk editor.
  Note that we lead the user to only edit the second chunk of text;
  but power users can still edit the first chunk if they like.

Attachments

• name-the-separators-in-the-hunk-splitting-interface_.dpatch
• unnamed

3 patches for repository http://darcs.net/releases/branch-2.4:

Tue Dec 29 01:26:13 GMT 2009  Eric Kow <kowey@darcs.net>
  * Name the separators in the hunk splitting interface.

Tue Dec 29 01:45:06 GMT 2009  Eric Kow <kowey@darcs.net>
  * Improve online help for hunk-splitting.

Wed Jan 20 21:51:01 GMT 2010  Eric Kow <kowey@darcs.net>
  * Simpler and more intuitive help text for hunk editor.
  Note that we lead the user to only edit the second chunk of text;
  but power users can still edit the first chunk if they like.
  (Thanks to Petr Ročkai for suggestions on the text!)

Attachments

• name-the-separators-in-the-hunk-splitting-interface_.dpatch
• unnamed

Oh, and here's the latest version...

Interactive hunk edit:
 - This edit will not affect your working copy
 - To split a block of added text, remove the part you want to postpone
 - To split a block of removed text, copy back the part you want to retain
 - Arbitrary editing is supported

======================== BEFORE (for reference) ========================
rambling robot
red rover
======================== AFTER (edit below) ============================
alliterative alligator
amusing amoeba
anecdotal antelope
======================== (edit above) ==================================

I don't think I'm the best person to decide on whether the text is clear. (It is
to me, for what it's worth.)

One comment on the code, if all the separators will have more than 3 '=' signs
at the beginning we should reflect that in the split between sep and the stuff
appended in each case, so that we steal less of the space that could be used by
real patch content. Also sep should probably be renamed to sepPrefix or
something like that.

Thanks for the patch form of this, Eric.

Eric Kow <bugs@darcs.net> writes:
> Interactive hunk edit:
>  - This edit will not affect your working copy
>  - To split a block of added text, remove the part you want to postpone
>  - To split a block of removed text, copy back the part you want to retain
>  - Arbitrary editing is supported

> ======================== BEFORE (for reference) ========================
> rambling robot
> red rover
> ======================== AFTER (edit below) ============================
> alliterative alligator
> amusing amoeba
> anecdotal antelope
> ======================== (edit above) ==================================

I know this is highly subjective, but I find the flushness of the labels
disturbing (to be exact, it nearly makes me twitch...). If they could be
centered, I would be most grateful. : - )

I also prefer the shortened version of the labels, but again that's
quite disputable. This would overall look like this: (it would be also
great if the 3rd bullet could be shortened by ~3 characters, but I don't
see how without compromising its clarity or grammatical
correctness... okay I shut up now)

> Interactive hunk edit:
>  - This edit will not affect your working copy
>  - To split a block of added text, remove the part you want to postpone
>  - To split a block of removed text, copy back the part you want to retain
>  - Arbitrary editing is supported
>
> ======================== BEFORE (reference) =============================
> rambling robot
> red rover
> =========================== AFTER (edit) ================================
> alliterative alligator
> amusing amoeba
> anecdotal antelope
> =========================== (edit above) ================================

Yours,
   Petr.

PS: As things stand, I vote for including hunk splitting in 2.4,
augmented with Eric's proposed patch. I don't think it compromises
stability or correctness, so I would be comfy with a freeze exception
here.

On Wed, Jan 20, 2010 at 22:00:32 +0000, Ganesh Sittampalam wrote:
> I don't think I'm the best person to decide on whether the text is clear. (It is
> to me, for what it's worth.)

Mark, Isaac [and ideally, a user who hasn't already chimed in]?

I repeat the text for convenience.

Interactive hunk edit:
 - This edit will not affect your working copy
 - To split a block of added text, remove the part you want to postpone
 - To split a block of removed text, copy back the part you want to retain
 - Arbitrary editing is supported

======================== BEFORE (for reference) ========================
rambling robot
red rover
======================== AFTER (edit below) ============================
alliterative alligator
amusing amoeba
anecdotal antelope
======================== (edit above) ==================================

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9

On Wed, 20 Jan 2010 22:11:48 +0000
Eric Kow <kowey@darcs.net> wrote:

> On Wed, Jan 20, 2010 at 22:00:32 +0000, Ganesh Sittampalam wrote:
> > I don't think I'm the best person to decide on whether the text is clear. (It is
> > to me, for what it's worth.)
> 
> Mark, Isaac [and ideally, a user who hasn't already chimed in]?

Thanks, Eric. 

This is all very clear and user-friendly to me except for one point:

>  - This edit will not affect your working copy

It's my understanding that the edit will not affect the working copy
*immediately*, but will affect it if I say "yes" to the resulting
patch. If that's correct, clearer text might be this:

 This edit change your working copy only after confirming the
 patch in 'record'.

  Mark

On Wed, Jan 20, 2010 at 17:27:57 -0500, Mark Stosberg wrote:
> >  - This edit will not affect your working copy
> 
> It's my understanding that the edit will not affect the working copy
> *immediately*, but will affect it if I say "yes" to the resulting
> patch. If that's correct, clearer text might be this:

It won't affect it at all!  (which is why editing patches leaves the
confusing detritus that restores your working copy from the edited
state)

I've also made another stab at http://wiki.darcs.net/HunkEditor .
It's not there yet, but I hope we're circling towards clarity! :-)

-- 
Eric Kow <http://www.nltg.brighton.ac.uk/home/Eric.Kow>
PGP Key ID: 08AC04F9

Hi Mark,

Mark Stosberg <mark@summersault.com> writes:
> It's my understanding that the edit will not affect the working copy
> *immediately*, but will affect it if I say "yes" to the resulting
> patch. If that's correct, clearer text might be this:
>
>  This edit change your working copy only after confirming the
>  patch in 'record'.
No, the text is true. It never affects your working copy. And that is as
it should be. You are expected to either revert or record the remaining
(those you have not recorded) patch(es).

Yours,
   Petr.

On Wed, 20 Jan 2010, Mark Stosberg wrote:

> It's my understanding that the edit will not affect the working copy
> *immediately*, but will affect it if I say "yes" to the resulting
> patch. If that's correct, clearer text might be this:

No, it will never affect your working copy. This is consistent with the 
rest of the behaviour of record, which is also to never do that.

Ganesh

OK, here's an amendement taking some comments into account:
- Petr/Max that centering is important
- Isaac and Florent (in a way) that hints should not mislead
  users into thinking the UI is limited to certain way
- Petr that we could regroup the hints.
- Ganesh that we could use a more unlikely split separator
  (I'm doing it in a weak/simple way)

Perhaps if there are no strong objections, we should push this and maybe make
further refinements on that?

Thanks for all the comments!

Eric

----------------------------------------------------------------------

Interactive hunk edit:
 - Edit the section marked 'AFTER'
 - Arbitrary editing is supported
 - This will only affect the patch, not your working copy
 - Hints:
   - To split added text, delete the part you want to postpone
   - To split removed text, copy back the part you want to retain

========================== BEFORE (reference) ==========================
rambling robot
red rover
============================= AFTER (edit) =============================
alliterative alligator
amusing amoeba
anecdotal antelope
============================= (edit above) =============================

4 patches for repository http://darcs.net/releases/branch-2.4:

Tue Dec 29 01:26:13 GMT 2009  Eric Kow <kowey@darcs.net>
  * Name the separators in the hunk splitting interface.

Tue Dec 29 01:45:06 GMT 2009  Eric Kow <kowey@darcs.net>
  * Improve online help for hunk-splitting.

Wed Jan 20 21:51:01 GMT 2010  Eric Kow <kowey@darcs.net>
  * Simpler and more intuitive help text for hunk editor.
  Note that we lead the user to only edit the second chunk of text;
  but power users can still edit the first chunk if they like.
  (Thanks to Petr Ročkai for suggestions on the text!)

Thu Jan 21 23:30:25 GMT 2010  Eric Kow <kowey@darcs.net>
  * Further refine the split UI text.

Attachments

• name-the-separators-in-the-hunk-splitting-interface_.dpatch
• unnamed

Looks fine to me.  I can't run the tests or push it till this evening,
so feel free to do so yourself in the meantime.

This patch bundle (with 2 patches) was just applied to the repository http://darcs.net/.
This message was brought to you by DarcsWatch
http://darcswatch.nomeata.de/repo_http:__darcs.net_.html#bundle-7c76d20bfe932e7e6c47168063f266d0039c8794

A new version of patch that passes tests.

2 patches for repository http://darcs.net:

Thu Aug 19 22:53:31 EEST 2010  Alexey Levan <exlevan@gmail.com>
  * Redefine Darcs.Commands.putInfo in Darcs.Repository

Fri Sep  3 20:54:29 EEST 2010  Alexey Levan <exlevan@gmail.com>
  * Resolve issue1884: correct report about getting lazy repository

Attachments

• redefine-darcs_commands_putinfo-in-darcs_repository.dpatch
• unnamed

Wrong patch number, sorry.

This patch bundle (with 2 patches) was just applied to the repository http://darcs.net/reviewed.
This message was brought to you by DarcsWatch
http://darcswatch.nomeata.de/repo_http:__darcs.net_reviewed.html#bundle-7c76d20bfe932e7e6c47168063f266d0039c8794

This patch bundle (with 4 patches) was just applied to the repository http://darcs.net/reviewed.
This message was brought to you by DarcsWatch
http://darcswatch.nomeata.de/repo_http:__darcs.net_reviewed.html#bundle-b5516fef848752a0d8f3c8d4eb778b61f22d8402

This patch bundle (with 3 patches) was just applied to the repository http://darcs.net/reviewed.
This message was brought to you by DarcsWatch
http://darcswatch.nomeata.de/repo_http:__darcs.net_reviewed.html#bundle-da0253ae8a180346ee57e8adff9fea1b5aea1bf5