[Emacs-diffs] master 5f3f388 1/2: Improve time function doc

[Paul Eggert]

branch: master
commit 5f3f3884a0d2a88101d330b82ef5b584cfc02aa6
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>

    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        |  4 ++--
 doc/misc/emacs-mime.texi   |  6 +-----
 lisp/calendar/iso8601.el   |  2 +-
 lisp/calendar/time-date.el |  4 ++--
 lisp/gnus/nndiary.el       | 12 ++++++------
 lisp/net/soap-client.el    |  1 +
 lisp/org/org-id.el         |  7 +++++--
 7 files changed, 18 insertions(+), 18 deletions(-)

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index b344483..7bb9833 100644
--- 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 6e95013..1f384f4 100644
--- 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 c69156c..30352c7 100644
--- 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 5b82b8a..c0565b3 100644
--- 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 2ad0634..8cda5aa 100644
--- 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 5526d62..95f208b 100644
--- 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 44cc7b2..8f9c132 100644
--- 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))