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.

diff --git a/doc/emacs/calendar.texi b/doc/emacs/calendar.texi
index e337474d9224978ecfa850151b3a1ff4a51d0b4a..eaae01937837e4eb643e20798b72ad5d6aa1f5c1 100644 (file)
--- 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 fae23cb0758423c5dd54d113307593de5135057d..912d464b49be27bd76eee4a3129fd075862821c3 100644 (file)
--- 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 8a1ba969ed9248f58bf814f9a72edb71a1152fcc..53d0a62ac4e939ea2e088252802d115bbb1e2dda 100644 (file)
--- 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 98dcfab015a980ccf2c774c4e8f79fd3268d1251..6c8b98851eb33bd58509f9b6e141e365f93d7f16 100644 (file)
--- 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 11bd469ae3b4f2f7f15de724b2980042cee61989..dec153113f0e538faaf0833ebff90f215d4b632b 100644 (file)
--- 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 9509b6b63eb5103a050b2e7575051b24cba1e98e..6afeca1cb38c6775f9ce873a1163adf7666f82d8 100644 (file)
--- 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