[Emacs-diffs] master aadf721 1/2: Improve documentation for year-zero issues

[Paul Eggert]

branch: master
commit aadf72167673c8702531ba3802e3d5f137f139ba
Author: Paul Eggert <address@hidden>
Commit: Paul Eggert <address@hidden>

    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 e337474..eaae019 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 fae23cb..912d464 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 8a1ba96..53d0a62 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 98dcfab..6c8b988 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 11bd469..dec1531 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 9509b6b..6afeca1 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