Question about a more robust date rule syntax for Eid al-Fitr dates for Saudi Arabia

[hnw]

Hi.

Thank you for maintaining this very helpful library.

I'm the author of Pull Request #542, which aims to correct the Eid al-Fitr dates for Saudi Arabia. In that PR, I initially used 30 Ramadan P4D to define a holiday that starts "the day after the 29th of Ramadan." As noted in my PR description, this approach relies on a specific behavior of the underlying caldate library, which could be brittle.

After submitting the PR, I discovered by chance that the syntax 1 day after 29 Ramadan P4D also works as expected. This syntax is far more intuitive and self-documenting. More importantly, it seems to remove the dependency on the internal logic of caldate for handling non-existent dates like the 30th of Ramadan.

However, after reviewing docs/specification.md, I could not find this DD day(s) after <date> grammar pattern documented for Hijri (or other calendar) dates.

Could you please clarify if this is an intentionally supported syntax?

• If it is supported: I believe it's a fantastic feature. Would you be open to a suggestion to add it to the official specification document? It would be incredibly helpful for defining similar holidays.
• If it's not an intentional feature: Is there a risk that this behavior might change or break in a future release?

Depending on your feedback, I would be happy to update my pull request to use this cleaner and more robust syntax.

Thank you for your time and guidance.

[commenthol]

Well currently there was no need for a "x days after y" rule.
If it can be avoided by naming the correct date in the respective calendar system is won't be needed in the future as then the rule is defined by such date.

[hnw]

Hi commenthol,

Thank you for your reply.

While you believe an "x days after y" rule isn't currently needed, I argue that this kind of relative date notation – specifically DD day(s) before <date> – is essential for fixing existing bugs and enabling accurate holiday definitions.

Crucially, this isn't a request for a new feature. I've found that this relative date syntax already works internally within the date-holidays and date-holidays-parser libraries, yet it's undocumented.

Take the South Korean Lunar New Year as an example. The current definition, korean 01-0-01 P3D, incorrectly starts the holiday on Lunar January 1st. In reality, it begins the day before Lunar January 1st for three days. We can't reliably define this using fixed dates like korean 12-0-29 because Lunar months vary in length.

However, the already functional notation, 1 day before korean 01-0-01 P3D, perfectly solves this. It accurately defines the holiday start and fixes the current bug.

Therefore, this notation isn't just a convenience; it's highly necessary for correcting current inaccuracies and making holiday definitions robust, especially for complex calendars like the Lunar calendar.

It would be a missed opportunity not to officially support and document this already working, powerful feature. Doing so would significantly improve the library's accuracy and flexibility.

Thanks for your consideration.