Re: undo in loaddefs.el buffer

[Luc Teirlinck]

Richard Stallman wrote:

   The manual is not supposed to describe every possible exception to the
   rules that could be made to work.  That would make the manual too
   big, too complicated, and too hard to read for ordinary purposes.

But 100% of the known examples (Auto Revert and Auto Revert Tail)
contradict the rules.  So it would seem better not to mention these
rules to begin with.  There is no need to distinguish between timers
and idle timers in as far as the undo problem is concerned.  All cases
where we had to worry about were timers, not idle timers.

There are several problems with:

      It is legitimate for an idle timer to edit the current buffer.  If
    it does, it should explicitly call @code{undo-boundary} once at the
    beginning and once just before exiting, since Emacs won't do that
    automatically for an idle timer.

It should be discussed in the common introduction to timers and idle
timers and not distinguish between them.  Remember that we arrived at
the above conclusion by looking exclusively at timers.  We never
looked at one single instance of the problem that involved idle timers.

Secondly, the correct solution is not always to make two undo
boundaries.  Sometimes it is to disable undo, sometimes it is to clear
out all undo info, as we saw with autorevert.  It sometimes might be
unnecessary for a timer that runs only once.  I believe that we should
explicitly mention the problem we want to avoid.  The person writing
the timer function is best placed to decide what the best solution is.
Also, it would make clear that the problem is serious.  I believe that
there is no need to explicitly mention disabling undo and clearing out
undo info, since these are obvious solutions to the problem.  The
double undo boundary solution is less obvious and should be mentioned,
especially since the programmer might have the false impression that
Emacs does this automatically anyway.

I propose the following alternative patch, which is rather different
from the one proposed yesterday.  I believe that it says all that
needs to be said.  It replaces the current two four line paragraphs
with one six line paragraph and describes the actual problem.

===File ~/os.texi-diff======================================
*** os.texi     29 Dec 2004 15:49:18 -0600      1.67
--- os.texi     30 Dec 2004 14:20:31 -0600      
***************
*** 1368,1377 ****
  timer to call a function that takes substantial time to run is likely
  to be annoying.
  
!   Timer functions should normally not alter the current buffer
! contents, but it may be ok to alter some other buffer that exists for
! special purposes.  A general guideline is that if a buffer has undo
! enabled, timers should not write in it.
  
  @deffn Command run-at-time time repeat function &rest args
  This sets up a timer that calls the function @var{function} with
--- 1368,1379 ----
  timer to call a function that takes substantial time to run is likely
  to be annoying.
  
!   A timer that edits a buffer in which undo is enabled, should be
! careful not to accumulate one huge undo entry over time, since that
! could yield memory problems.  To avoid this, it is usually necessary
! for the timer to explicitly call @code{undo-boundary} once at the
! beginning and once just before exiting.  Emacs won't do that
! automatically (@pxref{Undo}).
  
  @deffn Command run-at-time time repeat function &rest args
  This sets up a timer that calls the function @var{function} with
***************
*** 1486,1496 ****
  input.  Then it becomes idle again, and all the idle timers that are
  set up to repeat will subsequently run another time, one by one.
  
-   It is legitimate for an idle timer to edit the current buffer.  If
- it does, it should explicitly call @code{undo-boundary} once at the
- beginning and once just before exiting, since Emacs won't do that
- automatically for an idle timer.
- 
  @defun cancel-timer timer
  Cancel the requested action for @var{timer}, which should be a value
  previously returned by @code{run-at-time} or @code{run-with-idle-timer}.
--- 1488,1493 ----
============================================================