From aadf72167673c8702531ba3802e3d5f137f139ba Mon Sep 17 00:00:00 2001 From: Paul Eggert Date: Sat, 5 Oct 2019 21:17:48 -0700 Subject: [PATCH] Improve documentation for year-zero issues * doc/emacs/calendar.texi (Calendar Systems) * doc/lispref/os.texi (Time Conversion): Prefer "BC" to "B.C." since the documentation generally uses "BC". * doc/misc/emacs-mime.texi (time-date): * lisp/calendar/time-date.el (date-to-day, time-to-days): In the doc string, state the day origin more clearly, and more consistently with the rest of the documentation. * src/timefns.c (Fdecode_time): State the year origin in the doc string. --- doc/emacs/calendar.texi | 2 +- doc/lispref/os.texi | 4 ++-- doc/misc/emacs-mime.texi | 4 ++-- lisp/calc/calc-forms.el | 2 +- lisp/calendar/time-date.el | 11 ++++++----- src/timefns.c | 4 ++-- 6 files changed, 14 insertions(+), 13 deletions(-) diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi index e337474d922..eaae0193783 100644 --- a/doc/emacs/calendar.texi +++ b/doc/emacs/calendar.texi @@ -706,7 +706,7 @@ century. @cindex Julian day numbers @cindex astronomical day numbers Astronomers use a simple counting of days elapsed since noon, Monday, -January 1, 4713 B.C. on the Julian calendar. The number of days elapsed +January 1, 4713 BC on the Julian calendar. The number of days elapsed is called the @dfn{Julian day number} or the @dfn{Astronomical day number}. @cindex Hebrew calendar diff --git a/doc/lispref/os.texi b/doc/lispref/os.texi index fae23cb0758..912d464b49b 100644 --- a/doc/lispref/os.texi +++ b/doc/lispref/os.texi @@ -1435,9 +1435,9 @@ the past or future. Calendrical conversion functions always use the Gregorian calendar, even for dates before the Gregorian calendar was introduced. Year numbers -count the number of years since the year 1 B.C., and do not skip zero +count the number of years since the year 1 BC, and do not skip zero as traditional Gregorian years do; for example, the year number -@minus{}37 represents the Gregorian year 38 B.C@. +@minus{}37 represents the Gregorian year 38 BC@. @defun time-convert time &optional form This function converts a time value into a Lisp timestamp. diff --git a/doc/misc/emacs-mime.texi b/doc/misc/emacs-mime.texi index 8a1ba969ed9..53d0a62ac4e 100644 --- a/doc/misc/emacs-mime.texi +++ b/doc/misc/emacs-mime.texi @@ -1603,8 +1603,8 @@ An integer or floating point count of seconds. For instance: @code{905595714.0}, @code{905595714}. @item days -An integer number representing the number of days since 00000101. For -instance: @code{729644}. +An integer number representing the number of days since Sunday, +December 31, 1 BC (Gregorian). For instance: @code{729644}. @item decoded time A list of decoded time. For instance: @code{(54 21 12 12 9 1998 6 nil diff --git a/lisp/calc/calc-forms.el b/lisp/calc/calc-forms.el index 98dcfab015a..6c8b98851eb 100644 --- a/lisp/calc/calc-forms.el +++ b/lisp/calc/calc-forms.el @@ -381,7 +381,7 @@ ;;; These versions are rewritten to use arbitrary-size integers. ;;; A numerical date is the number of days since midnight on -;;; the morning of December 31, 1 B.C. (Gregorian) or January 2, 1 A.D. (Julian). +;;; the morning of December 31, 1 BC (Gregorian) or January 2, 1 AD (Julian). ;;; Emacs's calendar refers to such a date as an absolute date, some Calc function ;;; names also use that terminology. If the date is a non-integer, it represents ;;; a specific date and time. diff --git a/lisp/calendar/time-date.el b/lisp/calendar/time-date.el index 11bd469ae3b..dec153113f0 100644 --- a/lisp/calendar/time-date.el +++ b/lisp/calendar/time-date.el @@ -197,8 +197,9 @@ TIME should be either a time value or a date-time string." ;;;###autoload (defun date-to-day (date) - "Return the number of days between year 1 and DATE. -DATE should be a date-time string." + "Return the absolute date of DATE, a date-time string. +The absolute date is the number of days elapsed since the imaginary +Gregorian date Sunday, December 31, 1 BC." (time-to-days (date-to-time date))) ;;;###autoload @@ -233,9 +234,9 @@ DATE1 and DATE2 should be date-time strings." ;;;###autoload (defun time-to-days (time) - "The number of days between the Gregorian date 0001-12-31bce and TIME. -TIME should be a time value. -The Gregorian date Sunday, December 31, 1bce is imaginary." + "The absolute date corresponding to TIME, a time value. +The absolute date is the number of days elapsed since the imaginary +Gregorian date Sunday, December 31, 1 BC." (let* ((tim (decode-time time)) (year (decoded-time-year tim))) (+ (time-date--day-in-year tim) ; Days this year diff --git a/src/timefns.c b/src/timefns.c index 9509b6b63eb..6afeca1cb38 100644 --- a/src/timefns.c +++ b/src/timefns.c @@ -1491,8 +1491,8 @@ Lisp timestamp representing a nonnegative value less than 60 \(or less than 61 if the operating system supports leap seconds). MINUTE is an integer between 0 and 59. HOUR is an integer between 0 and 23. DAY is an integer between 1 and 31. MONTH is an -integer between 1 and 12. YEAR is an integer indicating the -four-digit year. DOW is the day of week, an integer between 0 and 6, +integer between 1 and 12. YEAR is the year number, an integer; 0 +represents 1 BC. DOW is the day of week, an integer between 0 and 6, where 0 is Sunday. DST is t if daylight saving time is in effect, nil if it is not in effect, and -1 if daylight saving information is not available. UTCOFF is an integer indicating the UTC offset in -- 2.39.5