bug#66502: 30.0.50; [PATCH; DOC] time-to-days and days-to-time use different epochs

bug#66502: 30.0.50; [PATCH; DOC] time-to-days and days-to-time use different epochs

[Bob Rogers]

[-- Attachment #1: message body text --]
[-- Type: text/plain, Size: 476 bytes --]

   Imagine my surprise when converting back using days-to-time gave me
something almost two millenia in the future.  Of course, the problem was
that days-to-time uses a different epoch from time-to-days.  The fix was
pretty easy . . . and then I discovered all the code that depends on the
existing behavior.  So I offer the following modest documentation patch,
in the hope that others will be spared any similar confusion.

					-- Bob Rogers
					   http://www.rgrjr.com/


[-- Attachment #2: Type: text/x-patch, Size: 1813 bytes --]

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 5400d492f0a..2f6bb4e190c 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -2127,6 +2127,14 @@ Time Calculations
 The operating system limits the range of time and zone values.
 @end defun
 
+@defun days-to-time days
+This is not quite the inverse of the @code{time-to-days} function, as
+it uses the Emacs epoch (instead of the year 1) for historical
+reasons.  To get the inverse, subtract @code{(time-to-days 0)} from
+@var{days}, in which case @code{days-to-time} may return @code{nil} if
+@var{days} is negative.
+@end defun
+
 @defun time-to-day-in-year time-value
 This returns the day number within the year corresponding to @var{time-value},
 assuming the default time zone.
diff --git a/lisp/calendar/time-date.el b/lisp/calendar/time-date.el
index 9cbe8e0f53c..786134d8ac5 100644
--- a/lisp/calendar/time-date.el
+++ b/lisp/calendar/time-date.el
@@ -181,7 +181,10 @@ seconds-to-time
 
 ;;;###autoload
 (defun days-to-time (days)
-  "Convert DAYS into a time value."
+  "Convert Emacs-epoch DAYS into a time value.
+Note that this does not use the same epoch as time-to-days; you
+must subtract (time-to-days 0) first to convert, and may get nil
+if the result is before the start."
   ;; 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.
@@ -243,7 +246,7 @@ time-to-day-in-year
 
 ;;;###autoload
 (defun time-to-days (time)
-  "The absolute date corresponding to TIME, a time value.
+  "The absolute pseudo-Gregorian date for TIME, a time value.
 The absolute date is the number of days elapsed since the imaginary
 Gregorian date Sunday, December 31, 1 BC."
   (let* ((tim (decode-time time))

bug#66502: 30.0.50; [PATCH; DOC] time-to-days and days-to-time use different epochs

[Eli Zaretskii]

> From: Bob Rogers <rogers@rgrjr.com>
> Date: Thu, 12 Oct 2023 10:23:35 -0700
> 
>    Imagine my surprise when converting back using days-to-time gave me
> something almost two millenia in the future.  Of course, the problem was
> that days-to-time uses a different epoch from time-to-days.  The fix was
> pretty easy . . . and then I discovered all the code that depends on the
> existing behavior.  So I offer the following modest documentation patch,
> in the hope that others will be spared any similar confusion.

Thanks, installed on the emacs-29 branch, and closing the bug.

Please in the future accompany the patches by a ChangeLog-style commit
log message, it makes the patches easier to install.

bug#66502: 30.0.50; [PATCH; DOC] time-to-days and days-to-time use different epochs

[Bob Rogers]

   From: Eli Zaretskii <eliz@gnu.org>
   Date: Sat, 14 Oct 2023 12:02:10 +0300

   Thanks, installed on the emacs-29 branch, and closing the bug.

   Please in the future accompany the patches by a ChangeLog-style commit
   log message, it makes the patches easier to install.

Oops; I didn't do that, because I thought doc patches didn't need a
ChangeLog message.  In hindsight, they need at least a commit message,
so that was pretty silly.

					-- Bob

bug#66502: 30.0.50; [PATCH; DOC] time-to-days and days-to-time use different epochs

[Eli Zaretskii]

> From: Bob Rogers <rogers@rgrjr.com>
> Date: Sat, 14 Oct 2023 07:19:46 -0700
> CC: 66502-done@debbugs.gnu.org
> 
>    From: Eli Zaretskii <eliz@gnu.org>
>    Date: Sat, 14 Oct 2023 12:02:10 +0300
> 
>    Thanks, installed on the emacs-29 branch, and closing the bug.
> 
>    Please in the future accompany the patches by a ChangeLog-style commit
>    log message, it makes the patches easier to install.
> 
> Oops; I didn't do that, because I thought doc patches didn't need a
> ChangeLog message.  In hindsight, they need at least a commit message,
> so that was pretty silly.

Yes.  What happened isn't a catastrophe: I typed the message for you.
It just takes more time and more manual work, so is best avoided.

TIA

bug#66502: 30.0.50; [PATCH; DOC] time-to-days and days-to-time use different epochs

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Oops; I didn't do that, because I thought doc patches didn't need a
  > ChangeLog message.  In hindsight, they need at least a commit message,
  > so that was pretty silly.

the commit message should list what entities you changed, added or
deleted: that is, the doc strings of which functions or variables etc.
And, in a general sense, what the change was about.

Please look at doc string change logs in some of the principal files.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#66502: 30.0.50; [PATCH; DOC] time-to-days and days-to-time use different epochs

[Bob Rogers]

   From: Richard Stallman <rms@gnu.org>
   Date: Sun, 15 Oct 2023 22:02:57 -0400

   [[[ To any NSA and FBI agents reading my email: please consider    ]]]
   [[[ whether defending the US Constitution against all enemies,     ]]]
   [[[ foreign or domestic, requires you to follow Snowden's example. ]]]

     > Oops; I didn't do that, because I thought doc patches didn't need a
     > ChangeLog message.  In hindsight, they need at least a commit message,
     > so that was pretty silly.

   the commit message should list what entities you changed, added or
   deleted: that is, the doc strings of which functions or variables etc.
   And, in a general sense, what the change was about.

   Please look at doc string change logs in some of the principal files.

Thank you, Richard; I realize what I should have done, and how I should
have done it, I just spaced out in this instance.

					-- Bob