GNU bug report logs - #80159
[PATCH v1] ; holiday-float: Improve documentation of edge case

Previous Next

To reply to this bug, email your comments to 80159 AT debbugs.gnu.org.
There is no need to reopen the bug first.

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

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

From: "Jacob S. Gordon" <jacob.as.gordon <at> gmail.com>
To: bug-gnu-emacs <at> gnu.org
Subject: [PATCH v1] ; holiday-float: Improve documentation of edge case
Date: Thu, 08 Jan 2026 18:50:37 -0500

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

Tags: patch

Hey everyone,

I noticed a gap in the documentation of ‘holiday-float’ when
considering an edge case.

  (holiday-float MONTH DAYNAME N STRING &optional DAY)

  Holiday called STRING on the Nth DAYNAME after/before MONTH DAY.
  DAYNAME=0 means Sunday, DAYNAME=1 means Monday, and so on.
  If N>0, use the Nth DAYNAME after MONTH DAY.
  If N<0, use the Nth DAYNAME before MONTH DAY.
  DAY defaults to 1 if N>0, and MONTH’s last day otherwise.

From this description, when ‘MONTH DAY’ falls on ‘DAYNAME’ I would
expect the holiday to be |N| weeks before/after ‘MONTH DAY’ (IOW, I
understand ‘before’/‘after’ in a strict sense).  Instead it’s |N|-1
weeks before/after: for |N| = 1 the holiday falls on ‘MONTH DAY’, and
for |N| = 2 the holiday is 1 week before/after ‘MONTH DAY’.

For concreteness, consider |N| = 1:

  (holiday-float 5 1 -1 "Victoria Day" 25)
  (holiday-fixed 5 25   "MONTH DAY")
  (holiday-float 5 1 1  "Anti-Victoria Day" 25)

According to the current docs, Victoria Day should fall on the first
Monday /before/ May 25th, and Anti-Victoria Day should fall on the
first Monday /after/ May 25th.  In 2026 May 25th is a Monday, and all
3 are scheduled then:

  Monday, May 19, 2025: Victoria Day
  Sunday, May 25, 2025: MONTH DAY
  Monday, May 26, 2025: Anti-Victoria Day

  Monday, May 25, 2026: Victoria Day
  Monday, May 25, 2026: MONTH DAY
  Monday, May 25, 2026: Anti-Victoria Day

  Monday, May 24, 2027: Victoria Day
  Tuesday, May 25, 2027: MONTH DAY
  Monday, May 31, 2027: Anti-Victoria Day

Similarly, for |N| = 2 the following holidays are only 1 week before
‘MONTH DAY’ in 2026:

  (holiday-float 5 1 -2 "Holiday" 25)
  (holiday-fixed 5 25   "MONTH DAY")
  (holiday-float 5 1 2  "Anti-Holiday" 25)

  Monday, May 18, 2026: Holiday
  Monday, May 25, 2026: MONTH DAY
  Monday, June 1, 2026: Anti-Holiday

The undocumented N = 0 behaviour actually seems closer to what I’d
expect for N = 1, choosing the first Monday /after/ May 25th in 2026:

  (holiday-fixed 5 25   "MONTH DAY")
  (holiday-float 5 1 0  "Zero Day" 25)
  (holiday-float 5 1 1  "Holiday" 25)

  Sunday, May 25, 2025: MONTH DAY
  Monday, May 26, 2025: Zero Day
  Monday, May 26, 2025: Holiday

  Monday, May 25, 2026: MONTH DAY
  Monday, May 25, 2026: Holiday
  Monday, June 1, 2026: Zero Day

  Tuesday, May 25, 2027: MONTH DAY
  Monday, May 31, 2027: Zero Day
  Monday, May 31, 2027: Holiday

At the very least, I suggest that the doc string describes this edge
case for N != 0.  The case of N = 0 is less clear to me, maybe it
should select the closest ‘DAYNAME’?

[v1-0001-holiday-float-Improve-documentation-of-edge-case.patch (text/patch, attachment)]

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

Best,

-- 
Jacob S. Gordon
jacob.as.gordon <at> gmail.com
Please avoid sending me HTML emails and MS Office documents.
https://useplaintext.email/#etiquette
https://www.fsf.org/campaigns/opendocument/

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

From: Eli Zaretskii <eliz <at> gnu.org>
To: "Jacob S. Gordon" <jacob.as.gordon <at> gmail.com>
Cc: 80159-done <at> debbugs.gnu.org
Subject: Re: bug#80159: [PATCH v1] ;
 holiday-float: Improve documentation of edge case
Date: Sat, 10 Jan 2026 15:39:22 +0200

> From: "Jacob S. Gordon" <jacob.as.gordon <at> gmail.com>
> Date: Thu, 08 Jan 2026 18:50:37 -0500
> 
> I noticed a gap in the documentation of ‘holiday-float’ when
> considering an edge case.
> 
>   (holiday-float MONTH DAYNAME N STRING &optional DAY)
> 
>   Holiday called STRING on the Nth DAYNAME after/before MONTH DAY.
>   DAYNAME=0 means Sunday, DAYNAME=1 means Monday, and so on.
>   If N>0, use the Nth DAYNAME after MONTH DAY.
>   If N<0, use the Nth DAYNAME before MONTH DAY.
>   DAY defaults to 1 if N>0, and MONTH’s last day otherwise.
> 
> >From this description, when ‘MONTH DAY’ falls on ‘DAYNAME’ I would
> expect the holiday to be |N| weeks before/after ‘MONTH DAY’ (IOW, I
> understand ‘before’/‘after’ in a strict sense).  Instead it’s |N|-1
> weeks before/after: for |N| = 1 the holiday falls on ‘MONTH DAY’, and
> for |N| = 2 the holiday is 1 week before/after ‘MONTH DAY’.
> 
> For concreteness, consider |N| = 1:
> 
>   (holiday-float 5 1 -1 "Victoria Day" 25)
>   (holiday-fixed 5 25   "MONTH DAY")
>   (holiday-float 5 1 1  "Anti-Victoria Day" 25)
> 
> According to the current docs, Victoria Day should fall on the first
> Monday /before/ May 25th, and Anti-Victoria Day should fall on the
> first Monday /after/ May 25th.  In 2026 May 25th is a Monday, and all
> 3 are scheduled then:
> 
>   Monday, May 19, 2025: Victoria Day
>   Sunday, May 25, 2025: MONTH DAY
>   Monday, May 26, 2025: Anti-Victoria Day
> 
>   Monday, May 25, 2026: Victoria Day
>   Monday, May 25, 2026: MONTH DAY
>   Monday, May 25, 2026: Anti-Victoria Day
> 
>   Monday, May 24, 2027: Victoria Day
>   Tuesday, May 25, 2027: MONTH DAY
>   Monday, May 31, 2027: Anti-Victoria Day
> 
> Similarly, for |N| = 2 the following holidays are only 1 week before
> ‘MONTH DAY’ in 2026:
> 
>   (holiday-float 5 1 -2 "Holiday" 25)
>   (holiday-fixed 5 25   "MONTH DAY")
>   (holiday-float 5 1 2  "Anti-Holiday" 25)
> 
>   Monday, May 18, 2026: Holiday
>   Monday, May 25, 2026: MONTH DAY
>   Monday, June 1, 2026: Anti-Holiday
> 
> The undocumented N = 0 behaviour actually seems closer to what I’d
> expect for N = 1, choosing the first Monday /after/ May 25th in 2026:
> 
>   (holiday-fixed 5 25   "MONTH DAY")
>   (holiday-float 5 1 0  "Zero Day" 25)
>   (holiday-float 5 1 1  "Holiday" 25)
> 
>   Sunday, May 25, 2025: MONTH DAY
>   Monday, May 26, 2025: Zero Day
>   Monday, May 26, 2025: Holiday
> 
>   Monday, May 25, 2026: MONTH DAY
>   Monday, May 25, 2026: Holiday
>   Monday, June 1, 2026: Zero Day
> 
>   Tuesday, May 25, 2027: MONTH DAY
>   Monday, May 31, 2027: Zero Day
>   Monday, May 31, 2027: Holiday
> 
> At the very least, I suggest that the doc string describes this edge
> case for N != 0.  The case of N = 0 is less clear to me, maybe it
> should select the closest ‘DAYNAME’?

Thanks, I installed the changes on the master branch.

I have no opinion about the N = 0 case; anybody?

Previous Next

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