From a77275fe3b79d06c9db7c699394416230f6a3fe9 Mon Sep 17 00:00:00 2001
From: Bruce Momjian
Date: Thu, 6 Jul 2006 01:46:38 +0000
Subject: Please find attached two patches for documentation and regression
 tests for the usage of full time zone names.

Joachim Wieland
---
 doc/src/sgml/datatype.sgml | 23 ++++++++++++++++++++---
 doc/src/sgml/datetime.sgml | 19 ++++++++++++-------
 doc/src/sgml/func.sgml     |  4 ++--
 3 files changed, 34 insertions(+), 12 deletions(-)

(limited to 'doc/src')

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index 7722f958c14..35e71004c18 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.168 2006/06/18 15:38:35 petere Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/datatype.sgml,v 1.169 2006/07/06 01:46:37 momjian Exp $ -->
 
  <chapter id="datatype">
   <title id="datatype-title">Data Types</title>
@@ -1602,7 +1602,12 @@ SELECT b, char_length(b) FROM test2;
       linkend="datatype-datetime-time-table"> 
       and <xref linkend="datatype-timezone-table">.)  If a time zone is
       specified in the input for <type>time without time zone</type>,
-      it is silently ignored.
+      it is silently ignored. You can also always specify a date but it will
+      be ignored except for when you use a full time zone name like
+      <literal>America/New_York</literal>. In this case specifying the date
+      is compulsory in order to tell which time zone offset should be
+      applied. It will be applied whatever time zone offset was valid at that
+      date and time at the specified place.
      </para>
 
       <table id="datatype-datetime-time-table">
@@ -1659,6 +1664,10 @@ SELECT b, char_length(b) FROM test2;
           <entry><literal>04:05:06 PST</literal></entry>
           <entry>time zone specified by name</entry>
          </row>
+         <row>
+          <entry><literal>2003-04-12 04:05:06 America/New_York</literal></entry>
+          <entry>time zone specified by full name</entry>
+         </row>
         </tbody>
        </tgroup>
       </table>
@@ -1677,6 +1686,10 @@ SELECT b, char_length(b) FROM test2;
           <entry><literal>PST</literal></entry>
           <entry>Pacific Standard Time</entry>
          </row>
+         <row>
+          <entry><literal>America/New_York</literal></entry>
+          <entry>Full time zone name</entry>
+         </row>
          <row>
           <entry><literal>-8:00</literal></entry>
           <entry>ISO-8601 offset for PST</entry>
@@ -1739,8 +1752,12 @@ SELECT b, char_length(b) FROM test2;
 </programlisting>
 
       are valid values, which follow the <acronym>ISO</acronym> 8601
-      standard.  In addition, the wide-spread format
+      standard. You can also specify the full time zone name as in
+<programlisting>
+1999-01-08 04:05:06 America/New_York
+</programlisting>
 
+      In addition, the wide-spread format
 <programlisting>
 January 8 04:05:06 1999 PST
 </programlisting>
diff --git a/doc/src/sgml/datetime.sgml b/doc/src/sgml/datetime.sgml
index 3603a6156e1..2bd42e5e52b 100644
--- a/doc/src/sgml/datetime.sgml
+++ b/doc/src/sgml/datetime.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/datetime.sgml,v 2.49 2006/04/23 03:39:50 momjian Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/datetime.sgml,v 2.50 2006/07/06 01:46:37 momjian Exp $ -->
 
  <appendix id="datetime-appendix">
   <title>Date/Time Support</title>
@@ -46,7 +46,9 @@
        <para>
         If the numeric token contains a dash (<literal>-</>), slash
         (<literal>/</>), or two or more dots (<literal>.</>), this is
-        a date string which may have a text month.
+        a date string which may have a text month. In case of a slash
+        (<literal>/</>) it can also be a full time zone name like
+        <literal>America/New_York</>.
        </para>
       </step>
 
@@ -359,7 +361,8 @@
    </indexterm>
 
    <para>
-    <xref linkend="datetime-timezone-input-table"> shows the time zone
+    <xref linkend="datetime-timezone-input-table"> and
+    <xref linkend="datetime-timezone-full-names-table"> show the time zone
     abbreviations recognized by <productname>PostgreSQL</productname>
     in date/time input values.  Note that these names are <emphasis>not</>
     necessarily used for date/time output &mdash; output is driven by the
@@ -983,13 +986,15 @@
    </indexterm>
 
    <para>
-    <xref linkend="datetime-timezone-set-table"> shows the time zone
+    <xref linkend="datetime-timezone-full-names-table"> shows the time zone
     names recognized by <productname>PostgreSQL</productname> as valid
     settings for the <xref linkend="guc-timezone"> parameter.  Note that
     these names are conceptually as well as practically different from
     the names shown in <xref linkend="datetime-timezone-input-table">:
     most of these names imply a local daylight-savings time rule, whereas
-    the former names each represent just a fixed offset from UTC.
+    the former names each represent just a fixed offset from UTC. That's why
+    you always have to specify a date if you want to use these time zone
+    names in <type>timetz</> values.
    </para>
 
    <para>
@@ -998,8 +1003,8 @@
     by the name of the principal city of the zone.
    </para>
 
-    <table id="datetime-timezone-set-table">
-     <title>Time Zone Names for Setting <varname>timezone</></title>
+    <table id="datetime-timezone-full-names-table">
+     <title>Time Zone Names for date/time input values and for setting <varname>timezone</></title>
      <tgroup cols="1">
       <thead>
        <row>
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 506fd816ca0..78f998e782e 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -1,4 +1,4 @@
-<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.323 2006/06/19 16:13:01 tgl Exp $ -->
+<!-- $PostgreSQL: pgsql/doc/src/sgml/func.sgml,v 1.324 2006/07/06 01:46:37 momjian Exp $ -->
 
  <chapter id="functions">
   <title>Functions and Operators</title>
@@ -6099,7 +6099,7 @@ SELECT date_trunc('year', TIMESTAMP '2001-02-16 20:38:40');
     specified either as a text string (e.g., <literal>'PST'</literal>)
     or as an interval (e.g., <literal>INTERVAL '-08:00'</literal>).
     In the text case, the available zone names are those shown in either
-    <xref linkend="datetime-timezone-set-table"> or
+    <xref linkend="datetime-timezone-full-names-table"> or
     <xref linkend="datetime-timezone-input-table">.
    </para>
 
-- 
cgit v1.2.3