bug#72570: 31.0.50; Regression in date-to-time

[Paul Eggert <eggert@cs.ucla.edu>]

[-- Attachment #1: Type: text/plain, Size: 984 bytes --]

On 2024-08-12 04:42, Eli Zaretskii wrote:
> Paul, any suggestions?  And can we please document the missing
> time-zone assumptions?

Not sure what documentation is missing, but I went through the doc for 
parse-time-string and iso8601-parse and found some room for improvement 
and so installed the attached.

As for the original issue, I tend to agree with Ulrich that date-to-time 
should default to local time. This would need changes to both 
documentation and to code. Ulrich mentioned the following potential 
issue with this idea:

> The problem is that
> timezone-make-date-arpa-standard would need an explicit timezone as its
> second argument, which we don't know.

The code could use timezone-time-zone-from-absolute to infer a timezone. 
timezone-fix-time already does this sort of thing. Admittedly getting 
the details right could be a bit tricky, and there is no perfect 
solution in this area (certainly timezone-fix-time is flawed). It might 
be good enough, though.

[-- Attachment #2: 0001-Document-time-parsing-functions-a-bit-better.patch --]
[-- Type: text/x-patch, Size: 4160 bytes --]

From 7a828c938ca9daf37baa02a50bb6463e2b7c0b85 Mon Sep 17 00:00:00 2001
From: Paul Eggert <eggert@cs.ucla.edu>
Date: Mon, 12 Aug 2024 14:31:19 -0700
Subject: [PATCH] Document time-parsing functions a bit better

See <https://bugs.gnu.org/72570#14>
---
 doc/lispref/os.texi         | 26 +++++++++++++++++++-------
 lisp/calendar/iso8601.el    | 10 +++++-----
 lisp/calendar/parse-time.el |  5 ++---
 3 files changed, 26 insertions(+), 15 deletions(-)

diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi
index 3ba3da459bf..5839de4a650 100644
--- a/doc/lispref/os.texi
+++ b/doc/lispref/os.texi
@@ -1800,19 +1800,31 @@ Time Parsing
 resemble an RFC 822 (or later) or ISO 8601 string, like ``Fri, 25 Mar
 2016 16:24:56 +0100'' or ``1998-09-12T12:21:54-0200'', but this
 function will attempt to parse less well-formed time strings as well.
+It parses an incomplete string like ``2024-08-13'' to an incomplete
+structure like @samp{(nil nil nil 13 8 2024 nil -1 nil)}, in which
+an unknown DST value is @minus{}1 and other unknown values are @code{nil}.
 @end defun
 
 @vindex ISO 8601 date/time strings
 @defun iso8601-parse string
-For a more strict function (that will error out upon invalid input),
-this function can be used instead.  It can parse all variants of
+This function acts like @code{parse-time-string} except it is stricter
+and errors out upon invalid input.  It can parse all variants of
 the ISO 8601 standard, so in addition to the formats mentioned above,
 it also parses things like ``1998W45-3'' (week number) and
-``1998-245'' (ordinal day number).  To parse durations, there's
-@code{iso8601-parse-duration}, and to parse intervals, there's
-@code{iso8601-parse-interval}.  All these functions return decoded
-time structures, except the final one, which returns three of them
-(the start, the end, and the duration).
+``1998-245'' (ordinal day number).
+@end defun
+
+@defun iso8601-parse-duration string
+This function parses an ISO 8601 time duration @var{string}
+and returns a decoded time structure.
+@c FIXME: example? behavior on incomplete input?
+@end defun
+
+@defun iso8601-parse-interval string
+This function parses an ISO 8601 time interval @var{string}
+and returns three decoded time structures
+representing the start, the end, and the duration.
+@c FIXME: example? behavior on incomplete input?
 @end defun
 
 @defun format-time-string format-string &optional time zone
diff --git a/lisp/calendar/iso8601.el b/lisp/calendar/iso8601.el
index a32b52564c9..a31b60eaec2 100644
--- a/lisp/calendar/iso8601.el
+++ b/lisp/calendar/iso8601.el
@@ -121,11 +121,11 @@ iso8601--zone-dst
 
 (defun iso8601-parse (string &optional form)
   "Parse an ISO 8601 date/time string and return a `decode-time' structure.
-
-The ISO 8601 date/time strings look like \"2008-03-02T13:47:30\",
-but shorter, incomplete strings like \"2008-03-02\" are valid, as
-well as variants like \"2008W32\" (week number) and
-\"2008-234\" (ordinal day number).
+ISO 8601 date/time strings look like \"2008-03-02T13:47:30+05:30\",
+or like shorter, incomplete strings like date \"2008-03-02\",
+week number \"2008W32\", and ordinal day number \"2008-234\".
+Values returned are identical to those of `decode-time', except
+that an unknown DST value is -1 and other unknown values are nil.
 
 See `decode-time' for the meaning of FORM."
   (if (not (iso8601-valid-p string))
diff --git a/lisp/calendar/parse-time.el b/lisp/calendar/parse-time.el
index c34329a4002..9538ea92ee5 100644
--- a/lisp/calendar/parse-time.el
+++ b/lisp/calendar/parse-time.el
@@ -154,9 +154,8 @@ parse-time-string
 \"Wed, 15 Jan 2020 16:12:21 -0800\".  This function is
 somewhat liberal in what format it accepts, and will attempt to
 return a \"likely\" value even for somewhat malformed strings.
-The values returned are identical to those of `decode-time', but
-any unknown values other than DST are returned as nil, and an
-unknown DST value is returned as -1.
+Values returned are identical to those of `decode-time', except
+that an unknown DST value is -1 and other unknown values are nil.
 
 See `decode-time' for the meaning of FORM."
   (condition-case ()
-- 
2.43.0