From b81f80ca621836ff8a7bc6ae446f9abd1455d242 Mon Sep 17 00:00:00 2001 From: Richard Lawrence 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 Gregorian and absolute representations of dates. (Bug#74965) --- lisp/calendar/calendar.el | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/lisp/calendar/calendar.el b/lisp/calendar/calendar.el index 60d8fdd6aee..54b5aebbd8b 100644 --- a/lisp/calendar/calendar.el +++ b/lisp/calendar/calendar.el @@ -90,6 +90,23 @@ ;; ;; +;; As described in more detail in that literature, a Gregorian calendar +;; date in this file is represented as a list of integers (MONTH DAY YEAR). +;; See the functions +;; `calendar-extract-year', +;; `calendar-extract-month', and +;; `calendar-extract-day' +;; which act as accessors for this representation. + +;; The calendar functions in this and related files also use an +;; "absolute" representation, which is an integer number of days since +;; December 31, 1BC on the Gregorian calendar. This representation is +;; useful for certain calculations; e.g. `calendar-day-of-week' is +;; simply the absolute represention modulo 7, because December 31, 1BC +;; is a Sunday. The absolute representation is also to convert between +;; different calendar scales: see e.g. +;; `calendar-absolute-from-gregorian' in this file and +;; `calendar-iso-from-absolute' in cal-iso.el. ;; A note on free variables: -- 2.39.5