From 92df2203437603d40417fe711c3cb7066ac4fdf5 Mon Sep 17 00:00:00 2001 From: Tom Lane Date: Thu, 26 Apr 2012 18:28:52 -0400 Subject: [PATCH] Improve documentation around historical calendar rules. Get rid of section 8.5.6 (Date/Time Internals), which appears to confuse people more than it helps, and anyway discussion of Postgres' internal datetime calculation methods seems pretty out of place here. Instead, make datatype.sgml just say that we follow the Gregorian calendar (a bit of specification not previously present anywhere in that chapter :-() and link to the History of Units appendix for more info. Do some mild editorialization on that appendix, too, to make it clearer that we are following proleptic Gregorian calendar rules rather than anything more historically accurate. Per a question from Florence Cousin and subsequent discussion in pgsql-docs. --- doc/src/sgml/datatype.sgml | 22 +++------------ doc/src/sgml/datetime.sgml | 57 ++++++++++++++++++++++++-------------- 2 files changed, 40 insertions(+), 39 deletions(-) diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml index b82d7e72fb..2ac6a81aa3 100644 --- a/doc/src/sgml/datatype.sgml +++ b/doc/src/sgml/datatype.sgml @@ -1511,6 +1511,9 @@ SELECT E'\\xDEADBEEF'; linkend="datatype-datetime-table">. The operations available on these data types are described in . + Dates are counted according to the Gregorian calendar, even in + years before that calendar was introduced (see for more information). @@ -1804,7 +1807,7 @@ MINUTE TO SECOND J2451187 - Julian day + Julian date January 8, 99 BC @@ -2757,23 +2760,6 @@ P years-months-days < - - Internals - - - PostgreSQL uses Julian dates - for all date/time calculations. This has the useful property of correctly - calculating dates from 4713 BC - to far into the future, using the assumption that the length of the - year is 365.2425 days. - - - - Date conventions before the 19th century make for interesting reading, - but are not consistent enough to warrant coding into a date/time handler. - - - diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml index 707bd5abb6..444b0ec2b9 100644 --- a/doc/src/sgml/datetime.sgml +++ b/doc/src/sgml/datetime.sgml @@ -318,7 +318,7 @@ JULIAN, JD, J - Next field is Julian Day + Next field is Julian Date ON @@ -456,6 +456,24 @@ History of Units + + Gregorian calendar + + + Julian date + + + + The SQL standard states that Within the definition of a + datetime literal, the datetime + values are constrained by the natural rules for dates and + times according to the Gregorian calendar. + PostgreSQL follows the SQL + standard's lead by counting dates exclusively in the Gregorian + calendar, even for years before that calendar was in use. + This rule is known as the proleptic Gregorian calendar. + + The Julian calendar was introduced by Julius Caesar in 45 BC. It was in common use in the Western world @@ -507,8 +525,8 @@ reluctant to change, and the Greek Orthodox countries didn't change until the start of the 20th century. - The reform was observed by Great Britain and Dominions (including what is - now the USA) in 1752. + The reform was observed by Great Britain and its dominions (including what + is now the USA) in 1752. Thus 2 September 1752 was followed by 14 September 1752. This is why Unix systems have the cal program @@ -522,18 +540,14 @@ $ cal 9 1752 17 18 19 20 21 22 23 24 25 26 27 28 29 30 - - - The SQL standard states that Within the definition of a - datetime literal, the datetime - values are constrained by the natural rules for dates and - times according to the Gregorian calendar. Dates between - 1582-10-05 and 1582-10-14, although eliminated in some countries - by Papal fiat, conform to natural rules and are - hence valid dates. PostgreSQL follows the SQL - standard's lead by counting dates exclusively in the Gregorian - calendar, even for years before that calendar was in use. + But, of course, this calendar is only valid for Great Britain and + dominions, not other places. + Since it would be difficult and confusing to try to track the actual + calendars that were in use in various places at various times, + PostgreSQL does not try, but rather follows the Gregorian + calendar rules for all dates, even though this method is not historically + accurate. @@ -551,8 +565,9 @@ $ cal 9 1752 - The Julian Date is unrelated to the Julian - calendar. + The Julian Date system is another type of + calendar, unrelated to the Julian calendar though it is confusingly + named similarly to that calendar. The Julian Date system was invented by the French scholar Joseph Justus Scaliger (1540-1609) and probably takes its name from Scaliger's father, @@ -564,15 +579,15 @@ $ cal 9 1752 is most often used by astronomers for labeling their nightly observations, and therefore a date runs from noon UTC to the next noon UTC, rather than from midnight to midnight: JD 0 designates the 24 hours from noon UTC on - 1 January 4713 BC to noon UTC on 2 January 4713 BC. + 24 November 4714 BC to noon UTC on 25 November 4714 BC. Although PostgreSQL supports Julian Date notation for - input and output of dates (and also uses them for some internal datetime - calculations), it does not observe the nicety of having dates run from - noon to noon. PostgreSQL treats a Julian Date as running - from midnight to midnight. + input and output of dates (and also uses Julian dates for some internal + datetime calculations), it does not observe the nicety of having dates + run from noon to noon. PostgreSQL treats a Julian Date + as running from midnight to midnight. -- 2.40.0