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  <address@hidden>

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