Improve time function doc

* doc/misc/emacs-mime.texi (time-date): Don’t give
parse-iso8601-time-string in the example, as the function is
not autoloaded.
* lisp/gnus/nndiary.el (nndiary-compute-reminders):
No need to call encode-time or use floating point here.

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index b3444838d3ba5b9ad2b082d43505a28be5b90009..7bb9833467de90da25ab01a9edfed41d92d67a2a 100644 (file)
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1559,7 +1559,7 @@ or more arguments.  The first six arguments @var{second},
 specify most of the components of a decoded time.  If there are more
 than six arguments the @emph{last} argument is used as @var{zone} and
 any other extra arguments are ignored, so that @code{(apply
-#\\='encode-time (decode-time ...))} works; otherwise @var{zone} defaults
+#'encode-time (decode-time ...))} works; otherwise @var{zone} defaults
 to the current time zone rule (@pxref{Time Zone Rules}).  The decoded
 time's @var{dst} component is treated as if it was @minus{}1, and
 @var{form} takes its default value.
@@ -1581,7 +1581,7 @@ You can perform simple date arithmetic by using out-of-range values for
 for example, day 0 means the day preceding the given month.
 
 The operating system puts limits on the range of possible time values;
-if you try to encode a time that is out of range, an error results.
+if the limits are exceeded while encoding the time, an error results.
 For instance, years before 1970 do not work on some systems;
 on others, years as early as 1901 do work.
 @end defun

diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi
index 6e95013c1868ba1b517fff3cf0dd71d8b7b4db9c..1f384f4f2700a16d5f95ba2dd4493215bcab34d4 100644 (file)
--- a/doc/misc/emacs-mime.texi
+++ b/doc/misc/emacs-mime.texi
@@ -1541,10 +1541,6 @@ Here's a bunch of time/date/second/day examples:
              1000000)
 @result{} (905595714000000 . 1000000)
 
-(encode-time (parse-iso8601-time-string "1998-09-12T12:21:54+0200")
-             1000000)
-@result{} (905595714000000 . 1000000)
-
 (float-time '(905595714000000 . 1000000))
 @result{} 905595714.0
 
@@ -1627,7 +1623,7 @@ These are the functions available:
 Take a date and return a time.
 
 @item float-time
-Take a time and return seconds.  (This is a built-in function.)
+Take a time and return seconds.
 
 @item encode-time
 Take seconds (and other ways to represent time, notably decoded time

diff --git a/lisp/calendar/iso8601.el b/lisp/calendar/iso8601.el
index c69156cbeb68e5febb085fa91adec84af0e06552..30352c7e75ff163c79f7ff1595925194c2d51065 100644 (file)
--- a/lisp/calendar/iso8601.el
+++ b/lisp/calendar/iso8601.el
@@ -138,7 +138,7 @@ well as variants like \"2008W32\" (week number) and
       date)))
 
 (defun iso8601-parse-date (string)
-  "Parse STRING (which should be on ISO 8601 format) and return a time value."
+  "Parse STRING (in ISO 8601 format) and return a decoded time value."
   (cond
    ;; Just a year: [-+]YYYY.
    ((iso8601--match iso8601--year-match string)

diff --git a/lisp/calendar/time-date.el b/lisp/calendar/time-date.el
index 5b82b8ab0fabcb4ca34ea8593dd6cc1fae3661df..c0565b3cfb72c85703f74d38744b8b42810575bd 100644 (file)
--- a/lisp/calendar/time-date.el
+++ b/lisp/calendar/time-date.el
@@ -374,8 +374,8 @@ January 1st being 1."
 
 (defun decoded-time-add (time delta)
   "Add DELTA to TIME, both of which are `decoded-time' structures.
-TIME should represent a time, while DELTA should only have
-non-nil integers for the values that should be altered.
+TIME should represent a time, while DELTA should have non-nil
+entries only for the values that should be altered.
 
 For instance, if you want to \"add two months\" to TIME, then
 leave all other fields but the month field in DELTA nil, and make

diff --git a/lisp/gnus/nndiary.el b/lisp/gnus/nndiary.el
index 2ad0634e6adf9620f81867260652da80dcda71fe..8cda5aa7031022e583f0ef2737893d6164325419 100644 (file)
--- a/lisp/gnus/nndiary.el
+++ b/lisp/gnus/nndiary.el
@@ -1278,27 +1278,27 @@ all.  This may very well take some time.")
        (cond ((eq (cdr reminder) 'minute)
              (time-subtract
               (apply #'encode-time 0 (nthcdr 1 date-elts))
-              (encode-time (* (car reminder) 60.0))))
+              (* (car reminder) 60)))
             ((eq (cdr reminder) 'hour)
              (time-subtract
               (apply #'encode-time 0 0 (nthcdr 2 date-elts))
-              (encode-time (* (car reminder) 3600.0))))
+              (* (car reminder) 3600)))
             ((eq (cdr reminder) 'day)
              (time-subtract
               (apply #'encode-time 0 0 0 (nthcdr 3 date-elts))
-              (encode-time (* (car reminder) 86400.0))))
+              (* (car reminder) 86400)))
             ((eq (cdr reminder) 'week)
              (time-subtract
               (apply #'encode-time 0 0 0 monday (nthcdr 4 date-elts))
-              (encode-time (* (car reminder) 604800.0))))
+              (* (car reminder) 604800)))
             ((eq (cdr reminder) 'month)
              (time-subtract
               (apply #'encode-time 0 0 0 1 (nthcdr 4 date-elts))
-              (encode-time (* (car reminder) 18748800.0))))
+              (* (car reminder) 18748800)))
             ((eq (cdr reminder) 'year)
              (time-subtract
               (apply #'encode-time 0 0 0 1 1 (nthcdr 5 date-elts))
-              (encode-time (* (car reminder) 400861056.0)))))
+              (* (car reminder) 400861056))))
        res))
     (sort res 'time-less-p)))
 

diff --git a/lisp/net/soap-client.el b/lisp/net/soap-client.el
index 5526d624f968a9d3aa5e8cc59c9ac4163101712b..95f208baf988c67300783c6d86627d782d505106 100644 (file)
--- a/lisp/net/soap-client.el
+++ b/lisp/net/soap-client.el
@@ -636,6 +636,7 @@ disallows them."
       (error "Invalid or unsupported time: %s" date-time-string))
     ;; Return a value in a format similar to that returned by decode-time, and
     ;; suitable for (apply #'encode-time ...).
+    ;; FIXME: Nobody uses this idiosyncratic value.  Perhaps stop returning it?
     (list second minute hour day month year second-fraction datatype
           (if has-time-zone
               (* (rng-xsd-time-to-seconds

diff --git a/lisp/org/org-id.el b/lisp/org/org-id.el
index 44cc7b2f14d1b28de3fe825cfa4be807672daa80..8f9c132ad3758577e7024b5741a157a584a3b81b 100644 (file)
--- a/lisp/org/org-id.el
+++ b/lisp/org/org-id.el
@@ -412,9 +412,12 @@ The input I may be a character, or a single-letter string."
     r))
 
 (defun org-id-time-to-b36 (&optional time)
-  "Encode TIME as a 10-digit string.
+  "Encode TIME as a 12-digit string.
 This string holds the time to micro-second accuracy, and can be decoded
 using `org-id-decode'."
+  ;; FIXME: If TIME represents N seconds after the epoch, then
+  ;; this encoding assumes 0 <= N < 110075314176 = (* (expt 36 4) 65536),
+  ;; i.e., that TIME is from 1970-01-01 00:00:00 to 5458-02-23 20:09:36 UTC.
   (setq time (encode-time time 'list))
   (concat (org-id-int-to-b36 (nth 0 time) 4)
          (org-id-int-to-b36 (nth 1 time) 4)
@@ -423,7 +426,7 @@ using `org-id-decode'."
 (defun org-id-decode (id)
   "Split ID into the prefix and the time value that was used to create it.
 The return value is (prefix . time) where PREFIX is nil or a string,
-and time is the usual three-integer representation of time."
+and TIME is a Lisp time value (HI LO USEC)."
   (let (prefix time parts)
     (setq parts (org-split-string id ":"))
     (if (= 2 (length parts))