Clarification of U command

[Ben Fritz]

I learned today that I had misunderstood the U command, and
additionally made changes to a "getting started" page on the wiki that
corrected the same misunderstanding:

http://vim.wikia.com/wiki/Undo_and_Redo

I had thought that U worked on the current line. Rather, it works on
the most recently modified line. I think :help U should be updated to
make it clearer what the command actually does. Change:

U Undo all latest changes on one line. {Vi: while not
moved off of it}

to:

U Undo all changes on the most recently modified line
until just after a different line was changed or editing
started on this line. If no changes since the last U
command, undo the last U. {Vi: only when cursor has not
moved off last modified line}

Any thoughts? Is this actually an accurate description or do I still
misunderstand? Perhaps we should remind users of persistent undo here
as well (since changes which are undone could combine with changes
from months ago, for example).

[Bram Moolenaar]

Ben Fritz -

Thanks for the hint that this was unclear. The text must have been
there forever. How about this:

U Undo all latest changes on one line, the line where
the latest change was made. |U| itself also counts as
a change, and thus |U| undoes a previous |U|.
{Vi: while not moved off of the last modified line}

--
ARTHUR: A scratch? Your arm's off!
BLACK KNIGHT: No, it isn't.
ARTHUR: Well, what's that then?
BLACK KNIGHT: I've had worse.
The Quest for the Holy Grail (Monty Python)

/// Bram Moolenaar -- Br...@Moolenaar.net -- http://www.Moolenaar.net \\\
/// sponsor Vim, vote for features -- http://www.Vim.org/sponsor/ \\\
\\\ an exciting new programming language -- http://www.Zimbu.org ///
\\\ help me help AIDS victims -- http://ICCF-Holland.org ///

[Benjamin Fritz]

On Tue, Aug 2, 2011 at 3:30 PM, Bram Moolenaar <Br...@moolenaar.net> wrote:
>
> Ben Fritz -

>> Change:
>>
>> U Undo all latest changes on one line. {Vi: while not
>> moved off of it}
>>
>> to:
>>
>>
>> U                     Undo all changes on the most recently modified line
>>                       until just after a different line was changed or editing
>>                       started on this line. If no changes since the last U
>>                       command, undo the last U.  {Vi: only when cursor has not
>>                       moved off last modified line}
>>
>

> Thanks for the hint that this was unclear.  The text must have been
> there forever.  How about this:
>
> U                       Undo all latest changes on one line, the line where
>                        the latest change was made. |U| itself also counts as
>                        a change, and thus |U| undoes a previous |U|.
>                        {Vi: while not moved off of the last modified line}
>

Much better, but "latest changes" is still not well-defined. Consider:

line 1: one two three
line 2: a b c

Put cursor on "two" and daw, then move to line 2 and delete the b with
x. Then go back to line 1 and insert some text.

Previously, I believed for some reason that pressing U on line 1 would
revert to "one two three". I now understand that pressing U anywhere
will revert line 1 to "one three".

Maybe add text like, '"Latest changes" refers to changes not
interrupted by changes to other lines.' This could come afterward if
needed, in the longer text which explains details of the interaction
between u, CTRL-R, and U.