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

[Alan Mackenzie <acm@muc.de>]

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).