From af03663878b257f7fb93a80eec03a8dd070b22b7 Mon Sep 17 00:00:00 2001
From: Tom Lane <tgl@sss.pgh.pa.us>
Date: Mon, 1 Dec 2003 20:34:53 +0000
Subject: [PATCH] Minor wordsmithing in datetime docs to try to address gripes
 raised by cnliou.

---
 doc/src/sgml/datatype.sgml | 33 +++++++++++++++++----------------
 doc/src/sgml/datetime.sgml | 18 ++++++++++++++----
 2 files changed, 31 insertions(+), 20 deletions(-)

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 7707aed2a47..a214f5398c8 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.133 2003/11/30 20:55:09 joe Exp $
+$PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.134 2003/12/01 20:34:53 tgl Exp $
 -->
 
  <chapter id="datatype">
@@ -1301,7 +1301,7 @@ SELECT b, char_length(b) FROM test2;
         <entry>8 bytes</entry>
         <entry>both date and time</entry>
         <entry>4713 BC</entry>
-        <entry>AD 5874897</entry>
+        <entry>5874897 AD</entry>
         <entry>1 microsecond / 14 digits</entry>
        </row>
        <row>
@@ -1309,7 +1309,7 @@ SELECT b, char_length(b) FROM test2;
         <entry>8 bytes</entry>
         <entry>both date and time, with time zone</entry>
         <entry>4713 BC</entry>
-        <entry>AD 5874897</entry>
+        <entry>5874897 AD</entry>
         <entry>1 microsecond / 14 digits</entry>
        </row>
        <row>
@@ -1348,6 +1348,14 @@ SELECT b, char_length(b) FROM test2;
      </tgroup>
     </table>
 
+   <note>
+    <para>
+     Prior to <productname>PostgreSQL</productname> 7.3, writing just
+     <type>timestamp</type> was equivalent to <type>timestamp with
+     time zone</type>.  This was changed for SQL compliance.
+    </para>
+   </note>
+
    <para>
     <type>time</type>, <type>timestamp</type>, and
     <type>interval</type> accept an optional precision value
@@ -1363,23 +1371,16 @@ SELECT b, char_length(b) FROM test2;
     When <type>timestamp</> values are stored as double precision floating-point
     numbers (currently the default), the effective limit of precision
     may be less than 6. <type>timestamp</type> values are stored as seconds
-    since 2000-01-01, and microsecond precision is achieved for dates within
-    a few years of 2000-01-01, but the precision degrades for dates further
-    away.  When <type>timestamp</type> values are stored as eight-byte integers (a compile-time
+    before or after midnight 2000-01-01.  Microsecond precision is achieved for
+    dates within a few years of 2000-01-01, but the precision degrades for
+    dates further away.  When <type>timestamp</type> values are stored as
+    eight-byte integers (a compile-time
     option), microsecond precision is available over the full range of
-    values. However eight-byte integer timestamps have a reduced range of
-    dates from 4713 BC up to 294276 AD.
+    values. However eight-byte integer timestamps have a more limited range of
+    dates than shown above: from 4713 BC up to 294276 AD.
    </para>
    </note>
 
-   <note>
-    <para>
-     Prior to <productname>PostgreSQL</productname> 7.3, writing just
-     <type>timestamp</type> was equivalent to <type>timestamp with
-     time zone</type>.  This was changed for SQL compliance.
-    </para>
-   </note>
-
    <para>
     For the <type>time</type> types, the allowed range of
     <replaceable>p</replaceable> is from 0 to 6 when eight-byte integer
diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml
index 93315564c86..d1f82c9d6e5 100644
--- a/doc/src/sgml/datetime.sgml
+++ b/doc/src/sgml/datetime.sgml
@@ -1,5 +1,5 @@
 <!--
-$PostgreSQL: pgsql/doc/src/sgml/datetime.sgml,v 2.38 2003/11/29 19:51:36 pgsql Exp $
+$PostgreSQL: pgsql/doc/src/sgml/datetime.sgml,v 2.39 2003/12/01 20:34:53 tgl Exp $
 -->
 
  <appendix id="datetime-appendix">
@@ -370,15 +370,25 @@ $PostgreSQL: pgsql/doc/src/sgml/datetime.sgml,v 2.38 2003/11/29 19:51:36 pgsql E
 
    <para>
     <xref linkend="datetime-timezone-table"> shows the time zone
-    abbreviations recognized by <productname>PostgreSQL</productname>.
-    <productname>PostgreSQL</productname> contains internal tabular
-    information for time zone decoding, since there is no standard
+    abbreviations recognized by <productname>PostgreSQL</productname>
+    in date/time input values.
+    <productname>PostgreSQL</productname> uses internal tables
+    for time zone input decoding, since there is no standard
     operating system interface to provide access to general,
     cross-time zone information. The underlying operating system
     <emphasis>is</emphasis> used to provide time zone information for
     <emphasis>output</emphasis>, however.
    </para>
 
+   <para>
+    Keep in mind also that the time zone names
+    recognized by <command>SET TIMEZONE</> are operating-system
+    dependent and may have little to do with <xref
+    linkend="datetime-timezone-table">.  For example, some systems
+    recognize values like <literal>'Europe/Rome'</> in <command>SET
+    TIMEZONE</>.
+   </para>
+
    <para>
     The table is organized by time zone offset from <acronym>UTC</>,
     rather than alphabetically.  This is intended to facilitate