(Timers): Discuss timers vs editing the buffer and undo.

diff --git a/lispref/os.texi b/lispref/os.texi
index 90fba8975e220215306cf5a932c9789358e7672a..36d7f9608504d5442df2b47772574c838c03b7cb 100644 (file)
--- a/lispref/os.texi
+++ b/lispref/os.texi
@@ -1368,6 +1368,11 @@ because most timer functions don't do a lot of work.  Indeed, for a
 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
 arguments @var{args} at time @var{time}.  If @var{repeat} is a number
@@ -1481,6 +1486,11 @@ minutes, and even if there have been garbage collections and autosaves.
 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}.