From: Lars Ingebrigtsen <larsi@gnus.org>
Date: Fri, 3 Dec 2021 16:22:54 +0000 (+0100)
Subject: Clarify the run-at-time documentation about "integral multiple"
X-Git-Tag: emacs-29.0.90~3619^2~27
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=85e56d97b717915509cb81c53238fbd06f390b92;p=emacs.git

Clarify the run-at-time documentation about "integral multiple"

* lisp/emacs-lisp/timer.el (run-at-time):
* doc/lispref/os.texi (Timers): Explain what "integral multiple"
really means.
---

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index fb0f25fa3d7..e420644cd81 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2183,7 +2183,13 @@ In most cases, @var{repeat} has no effect on when @emph{first} call
 takes place---@var{time} alone specifies that.  There is one exception:
 if @var{time} is @code{t}, then the timer runs whenever the time is a
 multiple of @var{repeat} seconds after the epoch.  This is useful for
-functions like @code{display-time}.
+functions like @code{display-time}.  For instance, the following will
+make @var{function} run at every ``whole'' minute (e.g.,
+@samp{11:03:00}, @samp{11:04:00}, etc):
+
+@example
+(run-at-time t 60 @var{function})
+@end example
 
 If Emacs didn't get any CPU time when the timer would have run (for
 example if the system was busy running another process or if the
diff --git a/lisp/emacs-lisp/timer.el b/lisp/emacs-lisp/timer.el
index 1ef4931b7be..2ac2c992456 100644
--- a/lisp/emacs-lisp/timer.el
+++ b/lisp/emacs-lisp/timer.el
@@ -351,19 +351,27 @@ This function is called, by name, directly by the C code."
 Repeat the action every REPEAT seconds, if REPEAT is non-nil.
 REPEAT may be an integer or floating point number.
 TIME should be one of:
+
 - a string giving today's time like \"11:23pm\"
   (the acceptable formats are HHMM, H:MM, HH:MM, HHam, HHAM,
   HHpm, HHPM, HH:MMam, HH:MMAM, HH:MMpm, or HH:MMPM;
   a period `.' can be used instead of a colon `:' to separate
   the hour and minute parts);
+
 - a string giving a relative time like \"90\" or \"2 hours 35 minutes\"
   (the acceptable forms are a number of seconds without units
   or some combination of values using units in `timer-duration-words');
+
 - nil, meaning now;
+
 - a number of seconds from now;
+
 - a value from `encode-time';
-- or t (with non-nil REPEAT) meaning the next integral
-  multiple of REPEAT.
+
+- or t (with non-nil REPEAT) meaning the next integral multiple
+  of REPEAT.  This is handy when you want the function to run at
+  a certain \"round\" number.  For instance, (run-at-time t 60 ...)
+  will run at 11:04:00, 11:05:00, etc.
 
 The action is to call FUNCTION with arguments ARGS.