bug#21902: doc incorrectly describes Julian Date

bug#21902: doc incorrectly describes Julian Date

[Zefram]

The manual says, in the section "SRFI-19 Introduction",

#    Also, for those not familiar with the terminology, a "Julian Day" is
# a real number which is a count of days and fraction of a day, in UTC,
# starting from -4713-01-01T12:00:00Z, ie. midday Monday 1 Jan 4713 B.C.

There are two errors in the first statement of the epoch for Julian Date,
in ISO 8601 format.  The JD epoch is noon on 1 January 4713 BC *in the
proleptic Julian calendar*.  The ISO 8601 format is properly never used on
the Julian calendar: ISO 8601 specifies the use of the Gregorian calendar,
including proleptically where necessary (as it most certainly is here).
On the proleptic Gregorian calendar, the JD epoch is noon on 24 November
4714 BC, and so the ISO 8601 expression should have some "-11-24".

The second error is in how the year is expressed in ISO 8601.  The initial
"-" does not mean the BC era, it means that the year number is negative.
ISO 8601 specifies that the AD era is always used, with year numbers
going negative where necessary; this arrangement is commonly known as
"astronomical year numbering".  So "0000" means 1 BC, "-0001" means 2
BC, and "-4713" means 4714 BC.  So the "-4713" is not correct for the
attempted expression of the Julian calendar date, but happens to be
correct for the Gregorian calendar date.

Putting it together, a correct ISO 8601 expression for the Julian Date
epoch is "-4713-11-24T12:00:00Z".

The word-based statement of the JD epoch is correct as far as it goes,
but would benefit considerably by the addition of a clause stating that
it is in the proleptic Julian calendar.  (Generally, a clarification
of which calendar is being used is helpful with the statement of any
date prior to the UK's switch of calendar in 1752.)  The description of
Modified Julian Date is essentially correct.

However, there's a third problem: misuse of the term "UTC" for historical
times.  The description of Julian Date says it's counted "in UTC",
and the statement of the MJD epoch describes its 1858 time as being
specified in UTC.  UTC is defined entirely by its relationship to TAI,
which is defined by the operation of atomic clocks.  TAI is therefore
only defined for the period since the operation of the first caesium
atomic clock in the middle of 1955.  The UTC<->TAI relationship isn't
actually defined even that far back: UTC begins at the beginning of
1961 (and that was not in the modern form with leap seconds).  It is
therefore incorrect to apply the term "UTC" to any time prior to 1961.
These two references to UTC should instead be to "UT", the wider class
of closely-matching time scales of which UTC is one representative.
Also, in the first sentence of this doc section, the phrase "universal
time (UTC)" should be either "universal time (UT)" or (more likely)
"coordinated universal time (UTC)".

-zefram

bug#21902: doc incorrectly describes Julian Date

[Andy Wingo]

Greets,

Time is not my area of expertise :)  Cc'ing guile-devel to see if
someone can review the ideas.

Would you like to propose a specific patch to the documentation?  The
file is in doc/ref/srfi-modules.texi.

Regards,

Andy

On Fri 13 Nov 2015 13:58, Zefram <zefram@fysh.org> writes:

> The manual says, in the section "SRFI-19 Introduction",
>
> #    Also, for those not familiar with the terminology, a "Julian Day" is
> # a real number which is a count of days and fraction of a day, in UTC,
> # starting from -4713-01-01T12:00:00Z, ie. midday Monday 1 Jan 4713 B.C.
>
> There are two errors in the first statement of the epoch for Julian Date,
> in ISO 8601 format.  The JD epoch is noon on 1 January 4713 BC *in the
> proleptic Julian calendar*.  The ISO 8601 format is properly never used on
> the Julian calendar: ISO 8601 specifies the use of the Gregorian calendar,
> including proleptically where necessary (as it most certainly is here).
> On the proleptic Gregorian calendar, the JD epoch is noon on 24 November
> 4714 BC, and so the ISO 8601 expression should have some "-11-24".
>
> The second error is in how the year is expressed in ISO 8601.  The initial
> "-" does not mean the BC era, it means that the year number is negative.
> ISO 8601 specifies that the AD era is always used, with year numbers
> going negative where necessary; this arrangement is commonly known as
> "astronomical year numbering".  So "0000" means 1 BC, "-0001" means 2
> BC, and "-4713" means 4714 BC.  So the "-4713" is not correct for the
> attempted expression of the Julian calendar date, but happens to be
> correct for the Gregorian calendar date.
>
> Putting it together, a correct ISO 8601 expression for the Julian Date
> epoch is "-4713-11-24T12:00:00Z".
>
> The word-based statement of the JD epoch is correct as far as it goes,
> but would benefit considerably by the addition of a clause stating that
> it is in the proleptic Julian calendar.  (Generally, a clarification
> of which calendar is being used is helpful with the statement of any
> date prior to the UK's switch of calendar in 1752.)  The description of
> Modified Julian Date is essentially correct.
>
> However, there's a third problem: misuse of the term "UTC" for historical
> times.  The description of Julian Date says it's counted "in UTC",
> and the statement of the MJD epoch describes its 1858 time as being
> specified in UTC.  UTC is defined entirely by its relationship to TAI,
> which is defined by the operation of atomic clocks.  TAI is therefore
> only defined for the period since the operation of the first caesium
> atomic clock in the middle of 1955.  The UTC<->TAI relationship isn't
> actually defined even that far back: UTC begins at the beginning of
> 1961 (and that was not in the modern form with leap seconds).  It is
> therefore incorrect to apply the term "UTC" to any time prior to 1961.
> These two references to UTC should instead be to "UT", the wider class
> of closely-matching time scales of which UTC is one representative.
> Also, in the first sentence of this doc section, the phrase "universal
> time (UTC)" should be either "universal time (UT)" or (more likely)
> "coordinated universal time (UTC)".
>
> -zefram

bug#21902: doc incorrectly describes Julian Date

[Zefram]

[-- Attachment #1: Type: text/plain, Size: 117 bytes --]

Andy Wingo wrote:
>Would you like to propose a specific patch to the documentation?

Sure.  Patch attached.

-zefram

[-- Attachment #2: d0 --]
[-- Type: text/plain, Size: 1850 bytes --]

--- a/doc/ref/srfi-modules.texi	2014-03-20 20:21:21.000000000 +0000
+++ b/doc/ref/srfi-modules.texi	2016-06-24 18:57:59.088243245 +0100
@@ -2461,8 +2461,8 @@
 @cindex UTC
 @cindex TAI
 This module implements time and date representations and calculations,
-in various time systems, including universal time (UTC) and atomic
-time (TAI).
+in various time systems, including Coordinated Universal Time (UTC)
+and International Atomic Time (TAI).
 
 For those not familiar with these time systems, TAI is based on a
 fixed length second derived from oscillations of certain atoms.  UTC
@@ -2494,18 +2494,12 @@
 @cindex julian day
 @cindex modified julian day
 Also, for those not familiar with the terminology, a @dfn{Julian Day}
-is a real number which is a count of days and fraction of a day, in
-UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan
-4713 B.C.  A @dfn{Modified Julian Day} is the same, but starting from
-1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC.  That time
-is julian day 2400000.5.
-
-@c  The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at
-@c  noon, UTC), but this is incorrect.  It looks like it might have
-@c  arisen from the code incorrectly treating years a multiple of 100
-@c  but not 400 prior to 1582 as non-leap years, where instead the Julian
-@c  calendar should be used so all multiples of 4 before 1582 are leap
-@c  years.
+is a real number which is a count of days and fraction of a day, in UT,
+starting from -4713-11-24T12:00:00Z, ie.@: midday UT on Monday 24 November
+4714 BC in the proleptic Gregorian calendar (1 January 4713 BC in the
+proleptic Julian calendar).  A @dfn{Modified Julian Day} is the same,
+but starting from 1858-11-17T00:00:00Z, ie.@: midnight UT on Wednesday
+17 November AD 1858.  That time is julian day 2400000.5.
 
 
 @node SRFI-19 Time

bug#21902: reviewer for time-related bugs (srfi-19)

[Andy Wingo]

Thanks, that's great :)

For this and the other time-related bugs it sounds like you know what
you're doing but I would like someone to check the work just to make
sure we're not introducing new errors.

To that end, I ask guile-devel, in this top-post so that people will see
it :), for a volunteer!

Are you a person who is interested in the specifics of time
representation?  TAI, UTC, and all that?

If so your input is very much appreciated on the patch quoted below from
bug 21902, and also on these other bugs:

 https://debbugs.gnu.org/21902  doc incorrectly describes Julian Date
 https://debbugs.gnu.org/21903  date->string duff ISO 8601 negative years
 https://debbugs.gnu.org/21904  date->string duff ISO 8601 format for non-4-digit years
 https://debbugs.gnu.org/21906  julian-day->date negative input breakage
 https://debbugs.gnu.org/21907  date->string duff ISO 8601 zone format
 https://debbugs.gnu.org/21911  TAI-to-UTC conversion leaps at wrong time
 https://debbugs.gnu.org/21912  TAI<->UTC conversion botches the unknown
 https://debbugs.gnu.org/22033  time-utc format is lossy
 https://debbugs.gnu.org/22034  time-utc->date shows bogus zone-dependent leap second

To give feedback is very easy.  The first thing is to confirm the bug
report: does it make sense to you?  If you or Zefram comes up with a
patch to fix the issue, as below, that's even better of course, but
already just a confirmation of the bug would be great.

To comment on the bug, just send a mail to NNNN@debbugs.gnu.org, where
NNNN is the bug number.  Super easy.

Cheers, and thanks in advance!

Andy

On Fri 24 Jun 2016 20:01, Zefram <zefram@fysh.org> writes:

> Andy Wingo wrote:
>>Would you like to propose a specific patch to the documentation?
>
> Sure.  Patch attached.
>
> -zefram
>
> --- a/doc/ref/srfi-modules.texi	2014-03-20 20:21:21.000000000 +0000
> +++ b/doc/ref/srfi-modules.texi	2016-06-24 18:57:59.088243245 +0100
> @@ -2461,8 +2461,8 @@
>  @cindex UTC
>  @cindex TAI
>  This module implements time and date representations and calculations,
> -in various time systems, including universal time (UTC) and atomic
> -time (TAI).
> +in various time systems, including Coordinated Universal Time (UTC)
> +and International Atomic Time (TAI).
>  
>  For those not familiar with these time systems, TAI is based on a
>  fixed length second derived from oscillations of certain atoms.  UTC
> @@ -2494,18 +2494,12 @@
>  @cindex julian day
>  @cindex modified julian day
>  Also, for those not familiar with the terminology, a @dfn{Julian Day}
> -is a real number which is a count of days and fraction of a day, in
> -UTC, starting from -4713-01-01T12:00:00Z, ie.@: midday Monday 1 Jan
> -4713 B.C.  A @dfn{Modified Julian Day} is the same, but starting from
> -1858-11-17T00:00:00Z, ie.@: midnight 17 November 1858 UTC.  That time
> -is julian day 2400000.5.
> -
> -@c  The SRFI-1 spec says -4714-11-24T12:00:00Z (November 24, -4714 at
> -@c  noon, UTC), but this is incorrect.  It looks like it might have
> -@c  arisen from the code incorrectly treating years a multiple of 100
> -@c  but not 400 prior to 1582 as non-leap years, where instead the Julian
> -@c  calendar should be used so all multiples of 4 before 1582 are leap
> -@c  years.
> +is a real number which is a count of days and fraction of a day, in UT,
> +starting from -4713-11-24T12:00:00Z, ie.@: midday UT on Monday 24 November
> +4714 BC in the proleptic Gregorian calendar (1 January 4713 BC in the
> +proleptic Julian calendar).  A @dfn{Modified Julian Day} is the same,
> +but starting from 1858-11-17T00:00:00Z, ie.@: midnight UT on Wednesday
> +17 November AD 1858.  That time is julian day 2400000.5.
>  
>  
>  @node SRFI-19 Time

bug#21902: doc incorrectly describes Julian Date

[Mark H Weaver]

Zefram <zefram@fysh.org> writes:

> The manual says, in the section "SRFI-19 Introduction",
>
> #    Also, for those not familiar with the terminology, a "Julian Day" is
> # a real number which is a count of days and fraction of a day, in UTC,
> # starting from -4713-01-01T12:00:00Z, ie. midday Monday 1 Jan 4713 B.C.
>
> There are two errors in the first statement of the epoch for Julian Date,
> in ISO 8601 format.  The JD epoch is noon on 1 January 4713 BC *in the
> proleptic Julian calendar*.  The ISO 8601 format is properly never used on
> the Julian calendar: ISO 8601 specifies the use of the Gregorian calendar,
> including proleptically where necessary (as it most certainly is here).
> On the proleptic Gregorian calendar, the JD epoch is noon on 24 November
> 4714 BC, and so the ISO 8601 expression should have some "-11-24".
>
> The second error is in how the year is expressed in ISO 8601.  The initial
> "-" does not mean the BC era, it means that the year number is negative.
> ISO 8601 specifies that the AD era is always used, with year numbers
> going negative where necessary; this arrangement is commonly known as
> "astronomical year numbering".  So "0000" means 1 BC, "-0001" means 2
> BC, and "-4713" means 4714 BC.  So the "-4713" is not correct for the
> attempted expression of the Julian calendar date, but happens to be
> correct for the Gregorian calendar date.
>
> Putting it together, a correct ISO 8601 expression for the Julian Date
> epoch is "-4713-11-24T12:00:00Z".
>
> The word-based statement of the JD epoch is correct as far as it goes,
> but would benefit considerably by the addition of a clause stating that
> it is in the proleptic Julian calendar.  (Generally, a clarification
> of which calendar is being used is helpful with the statement of any
> date prior to the UK's switch of calendar in 1752.)  The description of
> Modified Julian Date is essentially correct.
>
> However, there's a third problem: misuse of the term "UTC" for historical
> times.  The description of Julian Date says it's counted "in UTC",
> and the statement of the MJD epoch describes its 1858 time as being
> specified in UTC.  UTC is defined entirely by its relationship to TAI,
> which is defined by the operation of atomic clocks.  TAI is therefore
> only defined for the period since the operation of the first caesium
> atomic clock in the middle of 1955.  The UTC<->TAI relationship isn't
> actually defined even that far back: UTC begins at the beginning of
> 1961 (and that was not in the modern form with leap seconds).  It is
> therefore incorrect to apply the term "UTC" to any time prior to 1961.
> These two references to UTC should instead be to "UT", the wider class
> of closely-matching time scales of which UTC is one representative.
> Also, in the first sentence of this doc section, the phrase "universal
> time (UTC)" should be either "universal time (UT)" or (more likely)
> "coordinated universal time (UTC)".

I changed the text, based partly on your proposed patch and partly based
on similar recent fixes in the upstream SRFI-19 document, in commit
5106377a3460e1e35daf14ea6edbe80426347155 on the stable-2.2 branch.

I'm closing this bug now, but feel free to reopen if there are still
problems.

     Thanks!
       Mark