time-convert): Deprecate calls without an explicit FORM arg

* lisp/subr.el (time-convert): Deprecate calls without an explicit FORM arg.

* doc/lispref/os.texi (Time Conversion): Adjust doc accordingly.

* lisp/calendar/time-date.el (days-to-time):
* lisp/emacs-lisp/timer.el (timer-next-integral-multiple-of-time):
* lisp/gnus/nnrss.el (nnrss-normalize-date):
* lisp/epa-ks.el (epa-ks--parse-buffer): Silence corresponding warnings.

doc/lispref/os.texi

@@ -1541,7 +1541,7 @@ Year numbers count since the year 1 BCE, and do not skip zero
 as traditional Gregorian years do; for example, the year number
 @minus{}37 represents the Gregorian year 38 BCE@.
 
-@defun time-convert time &optional form
+@defun time-convert time form
 This function converts a time value into a Lisp timestamp.
 
 The optional @var{form} argument specifies the timestamp form to be
@@ -1554,7 +1554,7 @@ representing the timestamp; for example, it is treated as 1000000000
 if @var{time} is @code{nil} and the platform timestamp has nanosecond
 resolution.  If @var{form} is @code{list}, this function returns an
 integer list @code{(@var{high} @var{low} @var{micro} @var{pico})}.
-Although an omitted or @code{nil} @var{form} currently acts like
+Although a @code{nil} @var{form} currently acts like
 @code{list}, this is planned to change in a future Emacs version, so
 callers requiring list timestamps should pass @code{list} explicitly.
 

etc/NEWS

@@ -2525,6 +2525,10 @@ patcomp.el, pc-mode.el, pc-select.el, s-region.el, and sregex.el.
 
 * Lisp Changes in Emacs 29.1
 
+** The FORM arg of 'time-convert' is mandatory.
+'time-convert' can still be called without it, as before, but the
+compiler now emits a warning about this deprecated usage.
+
 +++
 ** Emacs now supports user-customizable and themable icons.
 These can be used for buttons in buffers and the like.  See

lisp/calendar/time-date.el

@@ -179,7 +179,10 @@ If DATE lacks timezone information, GMT is assumed."
 ;;;###autoload
 (defun days-to-time (days)
   "Convert DAYS into a time value."
-  (let ((time (time-convert (* 86400 days))))
+  ;; FIXME: We should likely just pass `t' to `time-convert'.
+  ;; All uses I could find in Emacs, GNU ELPA, and NonGNU ELPA can handle
+  ;; any valid time representation as return value.
+  (let ((time (time-convert (* 86400 days) 'list)))
     ;; Traditionally, this returned a two-element list if DAYS was an integer.
     ;; Keep that tradition if time-convert outputs timestamps in list form.
     (if (and (integerp days) (consp (cdr time)))

lisp/emacs-lisp/timer.el

@@ -122,7 +122,7 @@ of SECS seconds since the epoch.  SECS may be a fraction."
       (setq ticks (ash ticks 1))
       (setq hz (ash hz 1)))
     (let ((more-ticks (+ ticks trunc-s-ticks)))
-      (time-convert (cons (- more-ticks (% more-ticks trunc-s-ticks)) hz)))))
+      (time-convert (cons (- more-ticks (% more-ticks trunc-s-ticks)) hz) t))))
 
 (defun timer-relative-time (time secs &optional usecs psecs)
   "Advance TIME by SECS seconds.

lisp/epa-ks.el

@@ -295,13 +295,11 @@ enough, since keyservers have strict timeout settings."
                :created
                (and  (match-string 4)
                      (not (string-empty-p (match-string 4)))
-		     (time-convert
-                      (string-to-number (match-string 4))))
+		     (time-convert (string-to-number (match-string 4)) t))
                :expires
                (and (match-string 5)
                     (not (string-empty-p (match-string 5)))
-		    (time-convert
-                     (string-to-number (match-string 5))))
+		    (time-convert (string-to-number (match-string 5)) t))
                :flags
                (mapcar (lambda (flag)
                          (cdr (assq flag '((?r revoked)

lisp/gnus/nnrss.el

@@ -453,8 +453,8 @@ which RSS 2.0 allows."
   (let (case-fold-search vector year month day time zone given)
     (cond ((null date))			; do nothing for this case
 	  ;; if the date is just digits (unix time stamp):
-	  ((string-match "^[0-9]+$" date)
-	   (setq given (time-convert (string-to-number date))))
+	  ((string-match "\\`[0-9]+\\'" date)
+	   (setq given (time-convert (string-to-number date) t)))
 	  ;; RFC 822
 	  ((string-match " [0-9]+ " date)
 	   (setq vector (timezone-parse-date date)

lisp/subr.el

@@ -1857,6 +1857,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 '(start end &optional base-url) "27.1")
 (set-advertised-calling-convention 'libxml-parse-html-region '(start end &optional base-url) "27.1")
+(set-advertised-calling-convention 'time-convert '(time form) "29.1")
 
 ;;;; Obsolescence declarations for variables, and aliases.