GNU bug report logs - #55635
`make-decoded-time' incorrectly sets DST to nil, it should be -1 (guess)

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 55635 in the body.
You can then email your comments to 55635 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Maxim Nikulin <m.a.nikulin <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: `make-decoded-time' incorrectly sets DST to nil, it should be -1
 (guess)
Date: Wed, 25 May 2022 21:46:50 +0700

Consider the following example:

    (format-time-string
     "%F %T %Z %z"
     (encode-time
      (make-decoded-time :year 2022 :month 3 :day 31
    			 :hour 23 :minute 30 :second 0
    			 :zone "Europe/Madrid"))
     "Europe/Madrid")
    "2022-04-01 00:30:00 CEST +0200"

I believe that the result should be
    "2022-03-31 23:30:00 CEST +0200"
It can be obtained if :dst -1 is explicitly added to the 
`make-decoded-time' arguments.

Since `make-decoded-time' is defined using `cl-defun', I think, it is 
better to use -1 ("guess") default value for the :dst argument, not nil 
that explicitly says "no daylight saving time".

There is `decoded-time-set-defaults', but it does not help

    (format-time-string
     "%F %T %Z %z"
     (encode-time
      (decoded-time-set-defaults
       (make-decoded-time :year 2022 :month 3 :day 31
			  :hour 23 :minute 30)
       "Europe/Madrid"))
     "Europe/Madrid")
    "2022-04-01 01:30:00 CEST +0200"

This case I have no idea how to fix the issue.

An example in the `decoded-time-add' docstring
>   (decoded-time-add (decode-time) (make-decoded-time :month 2))
adds even more confusion. If `make-decoded-time' is intended for 
intervals, not timestamps than it should not have DST and TZ values at 
all. Time interval may be added to timestamp, and time zone and daylight 
saving time flag is the property of particular timestamp while the same 
interval may be added to various timestamps and the actual result 
depends on the base timestamp.

Timestamp and interval are different types and should not be used 
interchangeably. nil/t/-1 interpretation difference for DST causes 
issues like (bug#54731), so it should be handled with care.

Message #8 received at 55635 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Maxim Nikulin <m.a.nikulin <at> gmail.com>
Cc: 55635 <at> debbugs.gnu.org, Paul Eggert <eggert <at> cs.ucla.edu>
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Thu, 26 May 2022 14:13:52 +0200

Maxim Nikulin <m.a.nikulin <at> gmail.com> writes:

> Consider the following example:
>
>     (format-time-string
>      "%F %T %Z %z"
>      (encode-time
>       (make-decoded-time :year 2022 :month 3 :day 31
>     			 :hour 23 :minute 30 :second 0
>     			 :zone "Europe/Madrid"))
>      "Europe/Madrid")
>     "2022-04-01 00:30:00 CEST +0200"
>
> I believe that the result should be
>     "2022-03-31 23:30:00 CEST +0200"
> It can be obtained if :dst -1 is explicitly added to the
> `make-decoded-time' arguments.
>
> Since `make-decoded-time' is defined using `cl-defun', I think, it is
> better to use -1 ("guess") default value for the :dst argument, not
> nil that explicitly says "no daylight saving time".

I think that makes some sense, but on the other hand, that's just a
simple helper function that does what it says -- "with only the keywords
given filled out".  But perhaps -1 is less "filled out" than nil in this
case.

> There is `decoded-time-set-defaults', but it does not help
>
>     (format-time-string
>      "%F %T %Z %z"
>      (encode-time
>       (decoded-time-set-defaults
>        (make-decoded-time :year 2022 :month 3 :day 31
> 			  :hour 23 :minute 30)
>        "Europe/Madrid"))
>      "Europe/Madrid")
>     "2022-04-01 01:30:00 CEST +0200"
>
> This case I have no idea how to fix the issue.

It's this code, I guess:

  ;; When we don't have a time zone, default to DEFAULT-ZONE without
  ;; DST if DEFAULT-ZONE if given, and to unknown DST otherwise.
  (unless (decoded-time-zone time)
    (if default-zone
	(progn (setf (decoded-time-zone time) default-zone)
	       (setf (decoded-time-dst time) nil))
      (setf (decoded-time-dst time) -1)))

I've added Paul to the CCs; perhaps he has some comments.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #11 received at 55635 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 55635 <at> debbugs.gnu.org, Maxim Nikulin <m.a.nikulin <at> gmail.com>
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Thu, 26 May 2022 19:11:53 -0700

On 5/26/22 05:13, Lars Ingebrigtsen wrote:
> perhaps -1 is less "filled out" than nil in this
> case.

Indeed it is, and make-decoded-time's DST flag should default to -1.

It's unfortunate that nil means "standard time" in these contexts. In 
hindsight some other symbol should have been used to mean "standard 
time". Could be too late to change this though.


> It's this code, I guess:
> 
>    ;; When we don't have a time zone, default to DEFAULT-ZONE without
>    ;; DST if DEFAULT-ZONE if given, and to unknown DST otherwise.
>    (unless (decoded-time-zone time)
>      (if default-zone
> 	(progn (setf (decoded-time-zone time) default-zone)
> 	       (setf (decoded-time-dst time) nil))
>        (setf (decoded-time-dst time) -1)))

This looks wrong. Shouldn't it leave the DST flag alone? I.e., just this:

  (unless (decoded-time-zone time)
    (setf (decoded-time-zone-time) default-zone))

That is, if we assume that for the DST component -1 means "unknown" and 
nil means "standard time", it should be OK for decoded-time-set-defaults 
to leave the DST component alone, for the same reason that it leaves the 
DOW component alone.

Message #14 received at 55635 <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 55635 <at> debbugs.gnu.org, Maxim Nikulin <m.a.nikulin <at> gmail.com>
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Fri, 27 May 2022 12:40:43 +0200

Paul Eggert <eggert <at> cs.ucla.edu> writes:

>> perhaps -1 is less "filled out" than nil in this
>> case.
>
> Indeed it is, and make-decoded-time's DST flag should default to -1.

So I've now made this change in Emacs 29.

>> It's this code, I guess:
>>    ;; When we don't have a time zone, default to DEFAULT-ZONE
>> without
>>    ;; DST if DEFAULT-ZONE if given, and to unknown DST otherwise.
>>    (unless (decoded-time-zone time)
>>      (if default-zone
>> 	(progn (setf (decoded-time-zone time) default-zone)
>> 	       (setf (decoded-time-dst time) nil))
>>        (setf (decoded-time-dst time) -1)))
>
> This looks wrong. Shouldn't it leave the DST flag alone? I.e., just this:
>
>   (unless (decoded-time-zone time)
>     (setf (decoded-time-zone-time) default-zone))
>
> That is, if we assume that for the DST component -1 means "unknown"
> and nil means "standard time", it should be OK for
> decoded-time-set-defaults to leave the DST component alone, for the
> same reason that it leaves the DOW component alone.

Yes, I think so.  But you changed this in a391ffa2f03, and you usually
have a good reason for changes like this, so I thought there must be
something subtle going on here I didn't quite get.  😀

The old code doesn't look quite right, either, I think...

-  ;; When we don't have a time zone and we don't have a DST, then mark
-  ;; it as unknown.
-  (when (and (not (decoded-time-zone time))
-             (not (decoded-time-dst time)))
-    (setf (decoded-time-dst time) -1))
-
-  (when (and (not (decoded-time-zone time))
-             default-zone)
-    (setf (decoded-time-zone time) 0))


-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #19 received at 55635-done <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: 55635-done <at> debbugs.gnu.org, Maxim Nikulin <m.a.nikulin <at> gmail.com>
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Fri, 27 May 2022 12:26:56 -0700

[Message part 1 (text/plain, inline)]

On 5/27/22 03:40, Lars Ingebrigtsen wrote:
>> This looks wrong. Shouldn't it leave the DST flag alone? I.e., just this:
>>
>>    (unless (decoded-time-zone time)
>>      (setf (decoded-time-zone-time) default-zone))
>>
>> That is, if we assume that for the DST component -1 means "unknown"
>> and nil means "standard time", it should be OK for
>> decoded-time-set-defaults to leave the DST component alone, for the
>> same reason that it leaves the DOW component alone.

> Yes, I think so.  But you changed this in a391ffa2f03, and you usually
> have a good reason for changes like this, so I thought there must be
> something subtle going on here I didn't quite get.  😀

Thanks for the compliment, not sure it's deserved here....


> The old code doesn't look quite right, either, I think...
> 
> -  ;; When we don't have a time zone and we don't have a DST, then mark
> -  ;; it as unknown.
> -  (when (and (not (decoded-time-zone time))
> -             (not (decoded-time-dst time)))
> -    (setf (decoded-time-dst time) -1))
> -
> -  (when (and (not (decoded-time-zone time))
> -             default-zone)
> -    (setf (decoded-time-zone time) 0))

Yes, that old code was wrong because it incorrectly assumeed that (not 
(decoded-time-dst time)) means the DST flag is unspecified, whereas it 
really means that the DST flag is specifying standard time.

It also looked odd because default-zone was used only as a boolean, even 
though its name suggests that it's the default time zone. This usage 
dates back to commit fa648a59c9818ae284209ac7ae4f3700aebd92c9 which you 
installed in July 2019. The only call using default-zone in Emacs is in 
newsticker--decode-iso8601-date, which passes 0 so that the oddity in 
the implementation makes no difference there.

Part of the confusion here is that nil doesn't mean "no time zone is 
known"; it means "use the Emacs default time zone". In other words, nil 
has the same interpretation problem in time zones that it has in DST 
flags - it doesn't mean "unknown".

To try to lessen the confusion I installed the attached, which fixes the 
reported bug so I'll close the bug report. Please feel free to revert if 
you see a problem with it (I'm just trying to save time here by being bold).

[0001-decoded-time-set-defaults-now-leaves-DST-alone.patch (text/x-patch, attachment)]

Message #22 received at 55635-done <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 55635-done <at> debbugs.gnu.org, Maxim Nikulin <m.a.nikulin <at> gmail.com>
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Sat, 28 May 2022 12:41:46 +0200

Paul Eggert <eggert <at> cs.ucla.edu> writes:

> To try to lessen the confusion I installed the attached, which fixes
> the reported bug so I'll close the bug report. Please feel free to
> revert if you see a problem with it (I'm just trying to save time here
> by being bold).

Thanks; I think that looks like the correct thing here.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #25 received at 55635-done <at> debbugs.gnu.org (full text, mbox):

From: Maxim Nikulin <m.a.nikulin <at> gmail.com>
To: Lars Ingebrigtsen <larsi <at> gnus.org>, Paul Eggert <eggert <at> cs.ucla.edu>
Cc: 55635-done <at> debbugs.gnu.org
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Sat, 28 May 2022 23:31:43 +0700

On 28/05/2022 17:41, Lars Ingebrigtsen wrote:
> Paul Eggert writes:
> 
>> To try to lessen the confusion I installed the attached, which fixes
>> the reported bug so I'll close the bug report. Please feel free to
>> revert if you see a problem with it (I'm just trying to save time here
>> by being bold).
> 
> Thanks; I think that looks like the correct thing here.

Thank you, with the committed changes my examples work as I expect.

Paul, do you have any comment concerning the last part of the bug report?

`decoded-time-add' docstring:
>   (decoded-time-add (decode-time) (make-decoded-time :month 2))

I think, it is confusing that `make-decoded-time' is used to create 
timestamps *and* time intervals. They are different types, for example 
sum of intervals is meaningful (despite may be ambiguous) while there is 
no point to add timestamps. Daylight saving time and timezone are 
something alien for intervals. Though I am unsure if it is reasonable to 
mark intervals by e.g. 'time-interval symbol or to make these types 
distinct by some other way.

Message #28 received at 55635-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Maxim Nikulin <m.a.nikulin <at> gmail.com>
Cc: larsi <at> gnus.org, eggert <at> cs.ucla.edu, 55635-done <at> debbugs.gnu.org
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil,
 it should be -1 (guess)
Date: Sat, 28 May 2022 19:53:47 +0300

> Cc: 55635-done <at> debbugs.gnu.org
> From: Maxim Nikulin <m.a.nikulin <at> gmail.com>
> Date: Sat, 28 May 2022 23:31:43 +0700
> 
> I think, it is confusing that `make-decoded-time' is used to create 
> timestamps *and* time intervals. They are different types, for example 
> sum of intervals is meaningful (despite may be ambiguous) while there is 
> no point to add timestamps.

But this situation already exists with time units anyway.  You can add
an hour to some other time, but there's also a valid time stamp that
expresses 1 hour past the epoch UTC, and their values are exactly
identical.

Message #31 received at 55635-done <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: larsi <at> gnus.org, 55635-done <at> debbugs.gnu.org,
 Maxim Nikulin <m.a.nikulin <at> gmail.com>
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Sat, 28 May 2022 10:25:51 -0700

On 5/28/22 09:53, Eli Zaretskii wrote:
> this situation already exists with time units anyway.  You can add
> an hour to some other time, but there's also a valid time stamp that
> expresses 1 hour past the epoch UTC, and their values are exactly
> identical.

Quite true for encoded times that count seconds. However, Max also has a 
point that decoded timestamps like (19 17 10 28 5 2022 6 t -25200) are 
problematic as relative times. Although their first six elements can be 
treated as either relative or absolute, their last three elements don't 
make much sense in relative times.

The recent change in the master branch that lets encode-time take 
six-element lists suggests that perhaps a better way to represent a 
relative decoded time would be as a 6-element list.

With that in mind, here are three suggestions.

1. decoded-time-dst should return -1, instead of nil, when given a 
6-element list, since nil means standard time and -1 means DST is unknown.

2. make-decoded-time should generate a six-element list unless given a 
DST or ZONE arg.

3. Document the above nicely. (This is the hardest part....)

Message #34 received at 55635-done <at> debbugs.gnu.org (full text, mbox):

From: Lars Ingebrigtsen <larsi <at> gnus.org>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 55635-done <at> debbugs.gnu.org,
 Maxim Nikulin <m.a.nikulin <at> gmail.com>
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Sun, 29 May 2022 15:10:19 +0200

Paul Eggert <eggert <at> cs.ucla.edu> writes:

> With that in mind, here are three suggestions.
>
> 1. decoded-time-dst should return -1, instead of nil, when given a
> 6-element list, since nil means standard time and -1 means DST is
> unknown.

I think that sounds correct.

> 2. make-decoded-time should generate a six-element list unless given a
> DST or ZONE arg.

I don't think we should do this.  Yes, the remaining elements are
nonsensical when talking about intervals, but people rely on that
function to return its documented value.  If somebody wants to do
interval calculations and passes in a DST to make-decoded-time, that's a
classic "well, don't do that" situation.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

Message #37 received at 55635-done <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 55635-done <at> debbugs.gnu.org,
 Maxim Nikulin <m.a.nikulin <at> gmail.com>
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Sun, 29 May 2022 15:04:38 -0700

[Message part 1 (text/plain, inline)]

On 5/29/22 06:10, Lars Ingebrigtsen wrote:
> Paul Eggert <eggert <at> cs.ucla.edu> writes:
> 
>> With that in mind, here are three suggestions.
>>
>> 1. decoded-time-dst should return -1, instead of nil, when given a
>> 6-element list, since nil means standard time and -1 means DST is
>> unknown.
> 
> I think that sounds correct.

I looked into that, and since decoded-time-dst is defined by 
cl-defstruct it's not easy to change how it works. For now, I just 
documented the glitch; see the 3rd attached patch.

I also installed the 1st attached patch which mentions that Emacs's 
decoded dst flag differs from that of Common Lisp, and the 2nd attached 
patch which makes iso8601 parsing compatible with what we've discussed 
here by having it return -1 for unknown DST flags.


>> > 2. make-decoded-time should generate a six-element list unless given a
>> > DST or ZONE arg.
> 
> I don't think we should do this.

OK, I left that alone.

[0001-Doc-fix-for-dst-flag.patch (text/x-patch, attachment)]

[0002-ISO-8601-strings-sans-Z-don-t-specify-DST-flag.patch (text/x-patch, attachment)]

[0003-Document-decoded-time-string-issue-on-6-elt-args.patch (text/x-patch, attachment)]

Message #40 received at 55635-done <at> debbugs.gnu.org (full text, mbox):

From: Maxim Nikulin <m.a.nikulin <at> gmail.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>, Lars Ingebrigtsen <larsi <at> gnus.org>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 55635-done <at> debbugs.gnu.org
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Tue, 31 May 2022 19:25:25 +0700

On 30/05/2022 05:04, Paul Eggert wrote:
> diff --git a/lisp/simple.el b/lisp/simple.el
> index a254ee2251..d6b7045432 100644
> --- a/lisp/simple.el
> +++ b/lisp/simple.el
> @@ -10519,6 +10519,14 @@ capitalize-dwim
>  the number of seconds east of Greenwich.")
>    )
>  
> +;; Document that decoded-time-dst is problematic on 6-element lists.
> +;; It should return -1 indicating unknown DST, but currently returns
> +;; nil indicating standard time.
> +(put 'decoded-time-dst 'function-documentation
> +     (append (get 'decoded-time-dst 'function-documentation)
> +             "As a special case, `decoded-time-dst' returns an unspecified
> +value when given a list too short to have a dst element."))
> +

Paul, thank you for your efforts to fix the issues.

I have never used `cl-defstruct' before (and frankly speaking I am 
rather confused that the `decoded-time' struct and its constructor 
`make-decoded-time' are defined in different files and even directories 
are not the same), so my question may be naïve. Why did not you just add 
this new sentence to the :documentation property of the DST slot a bit 
above?

By the way, after updating of `make-decoded-time', default value for DST 
should be updated in `cl-defstruct' as well, otherwise
    (describe-symbol 'decoded-time)
reports that the default is nil.

It may be reasonable to cross-link `decoded-time' and 
`make-decoded-time' in docstrings.

Concerning timestamp vs. interval, first of all, I do not request 
immediate changes. I raised the question to make developers aware that 
the problem exist and it should be taken into account during further 
modifications or implementation of new features.

Lars Ingebrigtsen, Sun, 29 May 2022 15:10:19 +0200.
> If somebody wants to do
> interval calculations and passes in a DST to make-decoded-time, that's a
> classic "well, don't do that" situation.

DST slot with -1 (default) value is rather confusing for intervals but 
it safer for timestamps. Certainly it possible to do anything with bytes 
in memory, but direction of programming languages and libraries 
development is to allow users to clearly express intentions code and to 
add some measures that prevents bugs. That is why I mentioned tagged 
structure for interval type to distinguish it from timestamps.

Eli Zaretskii, Sat, 28 May 2022 19:53:47 +0300. >> From: Maxim Nikulin 
Date: Sat, 28 May 2022 23:31:43 +0700
>>
>> I think, it is confusing that `make-decoded-time' is used to create 
>> timestamps *and* time intervals. They are different types, for example 
>> sum of intervals is meaningful (despite may be ambiguous) while there is 
>> no point to add timestamps.
> 
> But this situation already exists with time units anyway.  You can add
> an hour to some other time, but there's also a valid time stamp that
> expresses 1 hour past the epoch UTC, and their values are exactly
> identical.

Certainly timestamps are actually intervals with various reference 
points. Encoded time is counted from 1970, decoded time from 0 a.d., so 
trying to add the same timestamps you will get result depending on their 
representation. Decoded time in some cases is more convenient since 1 
day may be not the same as 24 hours, not to mention varying duration of 
1 month.

The problem is that `decoded-time' time have field that are alien for 
intervals (timezone). Using the same constructor for both types makes 
code more obscure, it is impossible to enforce particular type of 
function argument to catch a programming error.

It is possible to use the same type for timestamps and intervals 
further, I am trying to dispute that it is the best design choice.

Message #43 received at 55635 <at> debbugs.gnu.org (full text, mbox):

From: Paul Eggert <eggert <at> cs.ucla.edu>
To: Maxim Nikulin <m.a.nikulin <at> gmail.com>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 55635 <at> debbugs.gnu.org,
 Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Mon, 13 Jun 2022 14:30:40 -0700

[Message part 1 (text/plain, inline)]

On 5/31/22 05:25, Maxim Nikulin wrote:

> I have never used `cl-defstruct' before (and frankly speaking I am 
> rather confused that the `decoded-time' struct and its constructor 
> `make-decoded-time' are defined in different files and even directories 
> are not the same), so my question may be naïve. Why did not you just add 
> this new sentence to the :documentation property of the DST slot a bit 
> above?

I am not sure I understand the question. The slot itself has a specified 
value (t, nil, or -1) whereas the decoded-time-dst function returns an 
unspecified value when there is no slot.

> By the way, after updating of `make-decoded-time', default value for DST 
> should be updated in `cl-defstruct' as well, otherwise
>      (describe-symbol 'decoded-time)
> reports that the default is nil.
> 
> It may be reasonable to cross-link `decoded-time' and 
> `make-decoded-time' in docstrings.

Thanks for the suggestions; I installed the attached.

[0001-Default-decoded-time-dst-slot-to-1.patch (text/x-patch, attachment)]

Message #46 received at 55635 <at> debbugs.gnu.org (full text, mbox):

From: Maxim Nikulin <m.a.nikulin <at> gmail.com>
To: Paul Eggert <eggert <at> cs.ucla.edu>
Cc: Eli Zaretskii <eliz <at> gnu.org>, 55635 <at> debbugs.gnu.org,
 Lars Ingebrigtsen <larsi <at> gnus.org>
Subject: Re: bug#55635: `make-decoded-time' incorrectly sets DST to nil, it
 should be -1 (guess)
Date: Tue, 14 Jun 2022 22:57:51 +0700

On 14/06/2022 04:30, Paul Eggert wrote:
> On 5/31/22 05:25, Maxim Nikulin wrote:
> 
>> I have never used `cl-defstruct' before (and frankly speaking I am 
>> rather confused that the `decoded-time' struct and its constructor 
>> `make-decoded-time' are defined in different files and even 
>> directories are not the same), so my question may be naïve. Why did 
>> not you just add this new sentence to the :documentation property of 
>> the DST slot a bit above?
> 
> I am not sure I understand the question. The slot itself has a specified 
> value (t, nil, or -1) whereas the decoded-time-dst function returns an 
> unspecified value when there is no slot.

See the diff at the end of this message. Maybe I do not see any 
difference because I tried such definitions and (describe-function 
`decoded-time-dst), (describe-symbol 'decoded-time) in Emacs-27, not for 
the development version.

>> It may be reasonable to cross-link `decoded-time' and 
>> `make-decoded-time' in docstrings.
> 
> Thanks for the suggestions; I installed the attached.

First of all, I am sorry, for some reason I missed that 
`make-decoded-time' already has "`decoded-time'" in its docstring. Maybe 
I am not familiar with help system enough, but my idea was to add a 
docstring to `cl-defstruct' as a whole (currently only slots are 
documented) that has "`make-decoded-time'" reference in the opposite 
direction to existing one. I admit that I missed something else and it 
is not necessary.

diff --git a/lisp/simple.el b/lisp/simple.el
index 99c951b24b..3054d79d44 100644
--- a/lisp/simple.el
+++ b/lisp/simple.el
@@ -10511,27 +10511,19 @@ This is an integer between 1 and 12 
(inclusive).  January is 1.")
   (year nil :documentation "This is a four digit integer.")
   (weekday nil :documentation "\
 This is a number between 0 and 6, and 0 is Sunday.")
+  ;; decoded-time-dst is problematic on 6-element lists.
+  ;; It should return -1 indicating unknown DST, but currently returns
+  ;; nil indicating standard time.
   (dst -1 :documentation "\
 This is t if daylight saving time is in effect, nil if it is not
 in effect, and -1 if daylight saving information is not available.
-Also see `decoded-time-dst'.")
+As a special case, return an unspecified value when given a list
+too short to have a dst element.")
   (zone nil :documentation "\
 This is an integer indicating the UTC offset in seconds, i.e.,
 the number of seconds east of Greenwich.")
   )

-;; Document that decoded-time-dst is problematic on 6-element lists.
-;; It should return -1 indicating unknown DST, but currently returns
-;; nil indicating standard time.
-(put 'decoded-time-dst 'function-documentation
-     "Access slot \"dst\" of `decoded-time' struct CL-X.
-This is t if daylight saving time is in effect, nil if it is not
-in effect, and -1 if daylight saving information is not available.
-As a special case, return an unspecified value when given a list
-too short to have a dst element.
-
-(fn CL-X)")
-
 (defun get-scratch-buffer-create ()
   "Return the *scratch* buffer, creating a new one if needed."
   (or (get-buffer "*scratch*")

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.