From mboxrd@z Thu Jan 1 00:00:00 1970 Path: news.gmane.io!.POSTED.blaine.gmane.org!not-for-mail From: Richard Lawrence Newsgroups: gmane.emacs.bugs Subject: bug#74965: [PATCH] Document representation of dates in calendar.el Date: Thu, 19 Dec 2024 09:46:49 +0100 Message-ID: <87v7vgm552.fsf@recursewithless.net> References: <87y10cm5i0.fsf@recursewithless.net> Mime-Version: 1.0 Content-Type: multipart/mixed; boundary="=-=-=" Injection-Info: ciao.gmane.io; posting-host="blaine.gmane.org:116.202.254.214"; logging-data="25956"; mail-complaints-to="usenet@ciao.gmane.io" To: 74965@debbugs.gnu.org Original-X-From: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Thu Dec 19 09:47:37 2024 Return-path: Envelope-to: geb-bug-gnu-emacs@m.gmane-mx.org Original-Received: from lists.gnu.org ([209.51.188.17]) by ciao.gmane.io with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.92) (envelope-from ) id 1tOCBz-0006a5-Ef for geb-bug-gnu-emacs@m.gmane-mx.org; Thu, 19 Dec 2024 09:47:37 +0100 Original-Received: from localhost ([::1] helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1tOCBX-0007hC-Np; Thu, 19 Dec 2024 03:47:07 -0500 Original-Received: from eggs.gnu.org ([2001:470:142:3::10]) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1tOCBT-0007gU-Hv for bug-gnu-emacs@gnu.org; Thu, 19 Dec 2024 03:47:05 -0500 Original-Received: from debbugs.gnu.org ([2001:470:142:5::43]) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1tOCBS-0008F0-CY for bug-gnu-emacs@gnu.org; Thu, 19 Dec 2024 03:47:03 -0500 DKIM-Signature: v=1; a=rsa-sha256; q=dns/txt; c=relaxed/relaxed; d=debbugs.gnu.org; s=debbugs-gnu-org; h=MIME-Version:Date:From:To:In-Reply-To:References:Subject; bh=Oh10yk4SAHfetsWF/uTdMcfnQKA3KelyFUGn1QmP3ms=; b=lUCvCoJv3WVJ4xLPq3EXCT1T9VYovKOCnIwnm6+FE9foc2GoOTm2GblHPRO6zrCLkpv3vt6BhWdhRncWAR9+QjddADXjAcGqJFf5XIIpUk8CoSAcwo6JsBkwn1p32SiaEgRF8Cq5ABujHdm5DkOKclKhG6BMIK7VnCjFdC98fXNbX++1p9kV8x1pJHEwA7GKavXZfsshQfF8rh5jCCw/z7Jv09YK9TUTwVkQguX9fLMErYmW7C5VhpuoFHtYDht+ZqmZEN2rTO4IMQ/SRYnb3zrj9ZVRR7BVp3arC7SA4KG5GBvIfasQe5p85GznL+y/Xjty71TN2xVgW2091I0xVw==; Original-Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1tOCBS-0002sP-0o for bug-gnu-emacs@gnu.org; Thu, 19 Dec 2024 03:47:02 -0500 X-Loop: help-debbugs@gnu.org In-Reply-To: <87y10cm5i0.fsf@recursewithless.net> Resent-From: Richard Lawrence Original-Sender: "Debbugs-submit" Resent-CC: bug-gnu-emacs@gnu.org Resent-Date: Thu, 19 Dec 2024 08:47:01 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 74965 X-GNU-PR-Package: emacs Original-Received: via spool by 74965-submit@debbugs.gnu.org id=B74965.173459802011049 (code B ref 74965); Thu, 19 Dec 2024 08:47:01 +0000 Original-Received: (at 74965) by debbugs.gnu.org; 19 Dec 2024 08:47:00 +0000 Original-Received: from localhost ([127.0.0.1]:37408 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOCBQ-0002s8-5M for submit@debbugs.gnu.org; Thu, 19 Dec 2024 03:47:00 -0500 Original-Received: from fhigh-a5-smtp.messagingengine.com ([103.168.172.156]:33981) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1tOCBN-0002rq-0K for 74965@debbugs.gnu.org; Thu, 19 Dec 2024 03:46:58 -0500 Original-Received: from phl-compute-02.internal (phl-compute-02.phl.internal [10.202.2.42]) by mailfhigh.phl.internal (Postfix) with ESMTP id EA68C11400A9 for <74965@debbugs.gnu.org>; Thu, 19 Dec 2024 03:46:51 -0500 (EST) Original-Received: from phl-mailfrontend-02 ([10.202.2.163]) by phl-compute-02.internal (MEProxy); Thu, 19 Dec 2024 03:46:51 -0500 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= recursewithless.net; h=cc:content-type:content-type:date:date :from:from:in-reply-to:message-id:mime-version:reply-to:subject :subject:to:to; s=fm3; t=1734598011; x=1734684411; bh=Oh10yk4SAH fetsWF/uTdMcfnQKA3KelyFUGn1QmP3ms=; b=uVTt8RKYU46ycrej+L3QJguLIH pjrryrNsG6s9UMnvu3C6XrzYUNgXfGjEOXN5FWzgvHuv7ArepzZKteWoVjvVTPWR 7vNuB2NtOjjzxzRQl5etfdGxTj82AkyDMzyJv8FzjvUHmkueKXMFqwDLnYEDGs6S RfW4M5hdRXwTm3vinUlBcsdGLNMOx8137g7yZn36ao4YlQs8geNGnVwGe7du+T6g xHHas/R7dJpB9Z8533EKuzjbdNukJPBBRy661vOdNKgWOvtmvxFzN9zp+Cvt/UFf 22pDIL4pY/1r7uCNCQ+ZNVC/KZt+tH3ReQTzUxd3FyvGv3FIXTH/P91/nhCw== DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d= messagingengine.com; h=cc:content-type:content-type:date:date :feedback-id:feedback-id:from:from:in-reply-to:message-id :mime-version:reply-to:subject:subject:to:to:x-me-proxy :x-me-sender:x-me-sender:x-sasl-enc; s=fm1; t=1734598011; x= 1734684411; bh=Oh10yk4SAHfetsWF/uTdMcfnQKA3KelyFUGn1QmP3ms=; b=I PJXdEhqFIOMXnq/9rNP0tlioAo3izK4ATm7kfnYg8jVKrEwkoFSVUSFwRLCYjuXr qTDHR1JxS/l3zXUOxdoo5kzWBoTJlbCPyH39AxbEpLVu2lAb7PqOjj5k7wY6De6r SBg+Mhcdn/kvVKmSIrePmDzbG0lQH/qGiU51MGQju56XFOiUe6yLCIl+QN/TGNTp ozRBPkHwRB1kCkMNEdmZzHypl31pTaZvFwSJTRSPhrh1KbfLifz0ypBzutZXUfsY Zvd9Hd+eh73IHBQtNzmIrjWnV+jbyl9vvos9WT8fasBMxAfkmeYABDNX7RY9WVqp 9KmbPu/1HazkkekkM1dFg== X-ME-Sender: X-ME-Received: X-ME-Proxy-Cause: gggruggvucftvghtrhhoucdtuddrgeefuddrleelgdduvdegucetufdoteggodetrfdotf fvucfrrhhofhhilhgvmecuhfgrshhtofgrihhlpdggtfgfnhhsuhgsshgtrhhisggvpdfu rfetoffkrfgpnffqhgenuceurghilhhouhhtmecufedttdenucenucfjughrpefhvffuff fkgggtsehmtderredttddtnecuhfhrohhmpeftihgthhgrrhguucfnrgifrhgvnhgtvgcu oehrfihlsehrvggtuhhrshgvfihithhhlhgvshhsrdhnvghtqeenucggtffrrghtthgvrh hnpeeiudelffehkefhiefhteegkeevleeiteevhfetgeeggfduveeujeevgefhkeelleen ucevlhhushhtvghrufhiiigvpedtnecurfgrrhgrmhepmhgrihhlfhhrohhmpehrfihlse hrvggtuhhrshgvfihithhhlhgvshhsrdhnvghtpdhnsggprhgtphhtthhopedupdhmohgu vgepshhmthhpohhuthdprhgtphhtthhopeejgeelieehseguvggssghughhsrdhgnhhurd horhhg X-ME-Proxy: Feedback-ID: if7394488:Fastmail Original-Received: by mail.messagingengine.com (Postfix) with ESMTPA for <74965@debbugs.gnu.org>; Thu, 19 Dec 2024 03:46:51 -0500 (EST) X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: bug-gnu-emacs@gnu.org List-Id: "Bug reports for GNU Emacs, the Swiss army knife of text editors" List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Original-Sender: bug-gnu-emacs-bounces+geb-bug-gnu-emacs=m.gmane-mx.org@gnu.org Xref: news.gmane.io gmane.emacs.bugs:297369 Archived-At: --=-=-= Content-Type: text/plain Tags: patch Here is a patch documenting these representations in a comment. --=-=-= Content-Type: text/patch Content-Disposition: attachment; filename=0001-Document-representation-of-dates-in-calendar.el.patch >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 --=-=-=--