bug#74965: Document date representations in calendar

bug#74965: Document date representations in calendar

[Richard Lawrence]

Severity: minor

As discussed in this thread:

https://lists.gnu.org/archive/html/emacs-devel/2024-12/msg00291.html

it would be nice to have better documentation of the date
representations used by calendar.el. Opening a bug so I can send a patch
with a bug number. 

bug#74965: [PATCH] Document representation of dates in calendar.el

[Richard Lawrence]

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

Tags: patch

Here is a patch documenting these representations in a comment.


[-- 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: 1694 bytes --]

From b81f80ca621836ff8a7bc6ae446f9abd1455d242 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 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 @@
 ;; <https://doi.org/10.1002/spe.4380230404>
 ;; <http://citeseerx.ist.psu.edu/viewdoc/download?doi=10.1.1.42.6421&rep=rep1&type=pdf>
 
+;; 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

bug#74965: [PATCH] Document representation of dates in calendar.el

[Eli Zaretskii]

> From: Richard Lawrence <rwl@recursewithless.net>
> Date: Thu, 19 Dec 2024 09:46:49 +0100
> 
> Here is a patch documenting these representations in a comment.

Thanks.  Most of this I already installed using your previous patch.
So now I just added the missing info to what was already there.  And
with that, I'm closing this bug.

bug#74965: [PATCH] Document representation of dates in calendar.el

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

Thanks for improving our code's readabilty.

There are other files in Emacs which could benefit from such improvement.
Would you ever be in hje mood to do more?

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#74965: [PATCH] Document representation of dates in calendar.el

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > There are some modes which could have more documentation on internal
  > functions to explain better what they are doing such as in Gnus.

Yes, that is crucial for clear code.

But what we really want, to make a program easy to read and
understand, goes beyond that.  It should have an introduction which
explains the parts of the program, and how they relate in terms of
jobs they do, and what the entry points are for each part.

Patr of this is explicitly dividng the program into parts
and starting each part with a comment saying what that part does
and how to use it.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

bug#74965: [PATCH] Document representation of dates in calendar.el

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > Yes, of course. If there is already a list somewhere, I'd be happy to
  > look over it and see if there's anything I can contribute. Otherwise,
  > I'll keep this in mind and will send more patches like this when I
  > encounter such files.

I ave observed that parts of epa.el and epg.el are hard to follow.  If
you can figure it out, writing down the understanding you've acquired
would make future maitenance easier.  Especially for how it reads
passwords.

-- 
Dr Richard Stallman (https://stallman.org)
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)