[PATCH] Re: Making decoded-times and calendar dates compatible?

[Richard Lawrence <rwl@recursewithless.net>]

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

Richard Stallman <rms@gnu.org> writes:
>   The docstrings of the functions
>
>   > calendar-extract-year
>   > calendar-extract-month
>   > calendar-extract-day
>
>   > are where the (MONTH DAY YEAR) format is mentioned.
>
> Would someoe like to add some comments at the start of the file
> documenging this data structure?

Attached is a patch which adds such a comment, based on my previous
message; let me know if I should open a bug report for this.

For now I take it that it's better not to touch the calendar code? I
don't think there is any constructor function for dates, or at least, I
see that throughout the calendar code, there are many uses of "(list
month day year)" to construct dates, so there might be a lot of code to
fix if we change the representation, and it might be hard to be sure
we've made all the necessary changes. Anyway, this is more work than I
want to do at the moment, though I'm willing to take a stab at it
eventually if others here think it would be worthwhile.

Best,
Richard


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Document-representation-of-dates-in-calendar.el.patch --]
[-- Type: text/patch, Size: 1350 bytes --]

From 4bf17cf59f7f8cc29ca79b03649037416aab1901 Mon Sep 17 00:00:00 2001
From: Richard Lawrence <rwl@recursewithless.net>
Date: Mon, 16 Dec 2024 20:46:34 +0100
Subject: [PATCH] Document representation of dates in calendar.el

* lisp/calendar/calendar.el: Add a comment in file header
explaining how dates are represented.
---
 lisp/calendar/calendar.el | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/lisp/calendar/calendar.el b/lisp/calendar/calendar.el
index 60d8fdd6aee..36d64a2b11c 100644
--- a/lisp/calendar/calendar.el
+++ b/lisp/calendar/calendar.el
@@ -90,6 +90,16 @@
 ;; <https://doi.org/10.1002/spe.4380230404>
 ;; <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.42.6421&rep=rep1&type=pdf>
 
+;; A note on how dates are represented:
+
+;; The standard format for a (Gregorian) calendar date in this file is a
+;; list of integers (MONTH DAY YEAR) -- see the functions
+;; `calendar-extract-year', `calendar-extract-month', and
+;; `calendar-extract-day'.  Internally it also uses an "absolute" format
+;; which is an integer number of days since December 31, 1BC (see
+;; e.g. `calendar-absolute-from-gregorian'), and converts between
+;; different calendar scales by converting to and from the absolute
+;; format (see e.g. `calendar-iso-from-absolute' in cal-iso.el).
 
 ;; A note on free variables:
 
-- 
2.39.5