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.

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index b82d7e72fb0c77cef2e6b4c6fb3dbd015d39d3e1..2ac6a81aa3737230593f9d6c0d676de2e8f4d839 100644 (file)
--- 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
     <xref linkend="functions-datetime">.
+    Dates are counted according to the Gregorian calendar, even in
+    years before that calendar was introduced (see <xref
+    linkend="datetime-units-history"> for more information).
    </para>
 
     <table id="datatype-datetime-table">
@@ -1804,7 +1807,7 @@ MINUTE TO SECOND
         </row>
         <row>
          <entry>J2451187</entry>
-         <entry>Julian day</entry>
+         <entry>Julian date</entry>
         </row>
         <row>
          <entry>January 8, 99 BC</entry>
@@ -2757,23 +2760,6 @@ P <optional> <replaceable>years</>-<replaceable>months</>-<replaceable>days</> <
 
    </sect2>
 
-   <sect2 id="datatype-datetime-internals">
-    <title>Internals</title>
-
-    <para>
-     <productname>PostgreSQL</productname> 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.
-    </para>
-
-    <para>
-     Date conventions before the 19th century make for interesting reading,
-     but are not consistent enough to warrant coding into a date/time handler.
-    </para>
-   </sect2>
-
   </sect1>
 
   <sect1 id="datatype-boolean">

diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml
index 707bd5abb65ffef5285edb9c583cb1ab931aa254..444b0ec2b93a906b996fe5d467cd6ad445cd90bc 100644 (file)
--- a/doc/src/sgml/datetime.sgml
+++ b/doc/src/sgml/datetime.sgml
@@ -318,7 +318,7 @@
        </row>
        <row>
         <entry><literal>JULIAN</>, <literal>JD</>, <literal>J</></entry>
-        <entry>Next field is Julian Day</entry>
+        <entry>Next field is Julian Date</entry>
        </row>
        <row>
         <entry><literal>ON</literal></entry>
@@ -456,6 +456,24 @@
   <sect1 id="datetime-units-history">
   <title>History of Units</title>
 
+  <indexterm zone="datetime-units-history">
+   <primary>Gregorian calendar</primary>
+  </indexterm>
+  <indexterm zone="datetime-units-history">
+   <primary>Julian date</primary>
+  </indexterm>
+
+  <para>
+   The SQL standard states that <quote>Within the definition of a
+   <quote>datetime literal</quote>, the <quote>datetime
+   values</quote> are constrained by the natural rules for dates and
+   times according to the Gregorian calendar</quote>.
+   <productname>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 <firstterm>proleptic Gregorian calendar</>.
+  </para>
+
   <para>
    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 <command>cal</command> program
@@ -522,18 +540,14 @@ $ <userinput>cal 9 1752</userinput>
 17 18 19 20 21 22 23
 24 25 26 27 28 29 30
 </screen>
-  </para>
 
-  <para>
-   The SQL standard states that <quote>Within the definition of a
-   <quote>datetime literal</quote>, the <quote>datetime
-   value</quote>s are constrained by the natural rules for dates and
-   times according to the Gregorian calendar</quote>.  Dates between
-   1582-10-05 and 1582-10-14, although eliminated in some countries
-   by Papal fiat, conform to <quote>natural rules</quote> and are
-   hence valid dates.  <productname>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,
+   <productname>PostgreSQL</> does not try, but rather follows the Gregorian
+   calendar rules for all dates, even though this method is not historically
+   accurate.
   </para>
 
   <para>
@@ -551,8 +565,9 @@ $ <userinput>cal 9 1752</userinput>
   </para>
 
   <para>
-   The <quote>Julian Date</quote> is unrelated to the <quote>Julian
-   calendar</quote>.
+   The <firstterm>Julian Date</firstterm> 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 @@ $ <userinput>cal 9 1752</userinput>
    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.
   </para>
 
   <para>
    Although <productname>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.  <productname>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.  <productname>PostgreSQL</> treats a Julian Date
+   as running from midnight to midnight.
   </para>
 
  </sect1>