master 696411ab8af: (sleep-for): Make the `millisec` argument obsolete

[Stefan Monnier]

branch: master
commit 696411ab8af4ca3e47b8e29482646f69034151eb
Author: Stefan Monnier <monnier@iro.umontreal.ca>
Commit: Stefan Monnier <monnier@iro.umontreal.ca>

    (sleep-for): Make the `millisec` argument obsolete
    
    * lisp/subr.el (sleep-for): Set new advertized calling convention.
    * src/dispnew.c (Fsleep_for): Adjust docstring.
    * doc/lispref/commands.texi (Waiting): Adjust doc.
---
 doc/lispref/commands.texi | 11 ++++-------
 etc/NEWS                  |  3 +++
 lisp/subr.el              |  1 +
 src/dispnew.c             |  6 +++---
 4 files changed, 11 insertions(+), 10 deletions(-)

diff --git a/doc/lispref/commands.texi b/doc/lispref/commands.texi
index fdf5ec1d7fe..41c30437dce 100644
--- a/doc/lispref/commands.texi
+++ b/doc/lispref/commands.texi
@@ -3969,20 +3969,17 @@ interrupted, even by input from the standard input 
descriptor.  It is
 thus equivalent to @code{sleep-for}, which is described below.
 @end defun
 
-@defun sleep-for seconds &optional millisec
+@defun sleep-for seconds
 This function simply pauses for @var{seconds} seconds without updating
 the display.  It pays no attention to available input.  It returns
 @code{nil}.
 
 The argument @var{seconds} need not be an integer.  If it is floating
 point, @code{sleep-for} waits for a fractional number of seconds.
-Some systems support only a whole number of seconds; on these systems,
-@var{seconds} is rounded down.
 
-The optional argument @var{millisec} specifies an additional waiting
-period measured in milliseconds.  This adds to the period specified by
-@var{seconds}.  If the system doesn't support waiting fractions of a
-second, you get an error if you specify nonzero @var{millisec}.
+It is also possible to call @code{sleep-for} with two arguments,
+as @code{(sleep-for @var{seconds} @var{millisec})},
+but that is considered obsolete and will be removed in the future.
 
 Use @code{sleep-for} when you wish to guarantee a delay.
 @end defun
diff --git a/etc/NEWS b/etc/NEWS
index 129017f7dbe..6898aa99bbc 100644
--- a/etc/NEWS
+++ b/etc/NEWS
@@ -1041,6 +1041,9 @@ Use 'define-minor-mode' and 
'define-globalized-minor-mode' instead.
 ** The obsolete calling convention of 'sit-for' has been removed.
 That convention was: (sit-for SECONDS MILLISEC &optional NODISP)
 
+** The 'millisec' argument of 'sleep-for' has been declared obsolete.
+Use a float value for the first argument instead.
+
 ** 'eshell-process-wait-{seconds,milliseconds}' options are now obsolete.
 Instead, use 'eshell-process-wait-time', which supports floating-point
 values.
diff --git a/lisp/subr.el b/lisp/subr.el
index 58274987d71..d9baecd600a 100644
--- a/lisp/subr.el
+++ b/lisp/subr.el
@@ -1959,6 +1959,7 @@ be a list of the form returned by `event-start' and 
`event-end'."
 (set-advertised-calling-convention 'redirect-frame-focus '(frame focus-frame) 
"24.3")
 (set-advertised-calling-convention 'libxml-parse-xml-region '(&optional start 
end base-url) "27.1")
 (set-advertised-calling-convention 'libxml-parse-html-region '(&optional start 
end base-url) "27.1")
+(set-advertised-calling-convention 'sleep-for '(seconds) "30.1")
 (set-advertised-calling-convention 'time-convert '(time form) "29.1")
 
 ;;;; Obsolescence declarations for variables, and aliases.
diff --git a/src/dispnew.c b/src/dispnew.c
index d6a27ac29ec..e4037494775 100644
--- a/src/dispnew.c
+++ b/src/dispnew.c
@@ -6206,9 +6206,9 @@ bitch_at_user (void)
 DEFUN ("sleep-for", Fsleep_for, Ssleep_for, 1, 2, 0,
        doc: /* Pause, without updating display, for SECONDS seconds.
 SECONDS may be a floating-point value, meaning that you can wait for a
-fraction of a second.  Optional second arg MILLISECONDS specifies an
-additional wait period, in milliseconds; this is for backwards compatibility.
-\(Not all operating systems support waiting for a fraction of a second.)  */)
+fraction of a second.
+An optional second arg MILLISECONDS can be provided but is deprecated:
+it specifies an additional wait period, in milliseconds.  */)
   (Lisp_Object seconds, Lisp_Object milliseconds)
 {
   double duration = extract_float (seconds);