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.

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

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

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)

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

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)))
 

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

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))