Add a comment to simple.el to explain the workings of `undo'.

Add a comment to simple.el to explain the workings of `undo'.

[Alan Mackenzie]

Hi, Emacs!

I've suffered some pain over the last couple of days trying to make
sense of `undo'.  The things which were bugging me were:

(i) Why does undo copy buffer-undo-list to pending-undo-list before
  calling `primitive-undo' rather than just using buffer-undo-list
  directly?

(ii) What on Earth is `undo' doing, after the call to `undo-more',
  comparing (car buffer-undo-list) to nil, when it always has this nil,
  and clearly "hasn't been changed" (tm) by `undo-more'.

Had the following short comment already been in simple.el, I would have
had little difficulty understanding `undo':


2008-10-21  Alan Mackenzie  <acm@muc.de>

	* simple.el (undo-more): Add comment explaining the operations on
	pending-undo-list and buffer-undo-list.


*** /home/acm/emacs/emacs/lisp/simple.el~	2008-10-21 20:37:17.466580872 +0000
--- /home/acm/emacs/emacs/lisp/simple.el	2008-10-21 20:49:24.843002848 +0000
***************
*** 1725,1730 ****
--- 1725,1733 ----
        (error (concat "No further undo information"
  		     (and undo-in-region " for region"))))
    (let ((undo-in-progress t))
+     ;; Note: The following, while pulling elements off
+     ;; `pending-undo-list' will call primitive change functions which
+     ;; will push more elements onto `buffer-undo-list'.
      (setq pending-undo-list (primitive-undo n pending-undo-list))
      (if (null pending-undo-list)
  	(setq pending-undo-list t))))


Can I install this, please?

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Add a comment to simple.el to explain the workings of `undo'.

[Chong Yidong]

Please go ahead and commit the comment.  It looks safe to install ;-)

Re: Add a comment to simple.el to explain the workings of `undo'.

[Alan Mackenzie]

On Tue, Oct 21, 2008 at 05:07:57PM -0400, Chong Yidong wrote:
> Please go ahead and commit the comment.  It looks safe to install ;-)
 
DONE.  (and Thanks!)

-- 
Alan Mackenzie (Nuremberg, Germany).

Re: Add a comment to simple.el to explain the workings of `undo'.

[Stefan Monnier]

>> Please go ahead and commit the comment.  It looks safe to install ;-)
> DONE.  (and Thanks!)

I see you forgot to install the corresponding regression test.
Please install it immediately, and be more careful in the future,


        Stefan

Re: Add a comment to simple.el to explain the workings of `undo'.

[Alan Mackenzie]

Hi, Stefan!

On Tue, Oct 21, 2008 at 09:35:28PM -0400, Stefan Monnier wrote:
> >> Please go ahead and commit the comment.  It looks safe to install ;-)
> > DONE.  (and Thanks!)

> I see you forgot to install the corresponding regression test.
> Please install it immediately, and be more careful in the future,

Er, do we have systematic regression testing of some sort in our
process?  I must have missed something.

I've grepped recent emails in emacs-devel for "egression" and found
none.  I've grepped through our files (I updated last night), and again
found nothing answering.

Please enlighten me as to how this works, what I should have done.

>         Stefan

-- 
Alan Mackenzie (Nuremberg, Germany).