GNU bug report logs - #74965
Document date representations in calendar

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 74965 in the body.
You can then email your comments to 74965 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Richard Lawrence <rwl <at> recursewithless.net>
To: bug-gnu-emacs <at> gnu.org
Subject: Document date representations in calendar
Date: Thu, 19 Dec 2024 09:39:03 +0100

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. 

Message #8 received at 74965 <at> debbugs.gnu.org (full text, mbox):

From: Richard Lawrence <rwl <at> recursewithless.net>
To: 74965 <at> debbugs.gnu.org
Subject: [PATCH] Document representation of dates in calendar.el
Date: Thu, 19 Dec 2024 09:46:49 +0100

[Message part 1 (text/plain, inline)]

Tags: patch

Here is a patch documenting these representations in a comment.

[0001-Document-representation-of-dates-in-calendar.el.patch (text/patch, attachment)]

Message #13 received at 74965-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Richard Lawrence <rwl <at> recursewithless.net>
Cc: 74965-done <at> debbugs.gnu.org
Subject: Re: bug#74965: [PATCH] Document representation of dates in calendar.el
Date: Sat, 21 Dec 2024 13:01:27 +0200

> From: Richard Lawrence <rwl <at> 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.

Message #16 received at 74965 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Richard Lawrence <rwl <at> recursewithless.net>
Cc: 74965 <at> debbugs.gnu.org
Subject: Re: bug#74965: [PATCH] Document representation of dates in calendar.el
Date: Sun, 22 Dec 2024 23:11:19 -0500

[[[ 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)

Message #19 received at 74965 <at> debbugs.gnu.org (full text, mbox):

From: Richard Lawrence <rwl <at> recursewithless.net>
To: rms <at> gnu.org
Cc: 74965 <at> debbugs.gnu.org
Subject: Re: bug#74965: [PATCH] Document representation of dates in calendar.el
Date: Mon, 23 Dec 2024 09:48:49 +0100

Richard Stallman <rms <at> gnu.org> writes:

> 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?

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.

Best,
Richard

Message #22 received at 74965 <at> debbugs.gnu.org (full text, mbox):

From: Björn Bidar <bjorn.bidar <at> thaodan.de>
To: Richard Stallman <rms <at> gnu.org>
Cc: 74965 <at> debbugs.gnu.org, Richard Lawrence <rwl <at> recursewithless.net>
Subject: Re: bug#74965: [PATCH] Document representation of dates in calendar.el
Date: Mon, 23 Dec 2024 15:08:05 +0200

Richard Stallman <rms <at> gnu.org> writes:

> [[[ 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.

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

I would say anything which doesn't receive move love these days could
require these kinds of improvements.

Message #25 received at 74965 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Björn Bidar <bjorn.bidar <at> thaodan.de>
Cc: 74965 <at> debbugs.gnu.org, rwl <at> recursewithless.net
Subject: Re: bug#74965: [PATCH] Document representation of dates in calendar.el
Date: Tue, 24 Dec 2024 23:48:14 -0500

[[[ 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)

Message #28 received at 74965 <at> debbugs.gnu.org (full text, mbox):

From: Richard Stallman <rms <at> gnu.org>
To: Richard Lawrence <rwl <at> recursewithless.net>
Cc: 74965 <at> debbugs.gnu.org
Subject: Re: bug#74965: [PATCH] Document representation of dates in calendar.el
Date: Tue, 24 Dec 2024 23:48:47 -0500

[[[ 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)

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.