From: Richard Lawrence <rwl@recursewithless.net>
Date: Mon, 16 Dec 2024 19:46:34 +0000 (+0100)
Subject: Document representation of dates in calendar.el
X-Git-Url: http://git.eshelyaron.com/gitweb/?a=commitdiff_plain;h=656a35f7db55f9249352e58769fbe3003868ad95;p=emacs.git

Document representation of dates in calendar.el

* lisp/calendar/calendar.el: Add a comment in file header
explaining how dates are represented.

(cherry picked from commit d8ffcf2fbaca158f3eed3b35cc181756a4c4878f)
---

diff --git a/lisp/calendar/calendar.el b/lisp/calendar/calendar.el
index 22fab0c242f..63a8504a855 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: