Received: from malur.postgresql.org ([217.196.149.56])
	by arkaria.postgresql.org with esmtps
 (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1oO77P-0004dM-Vp
	for pgsql-docs@arkaria.postgresql.org; Wed, 17 Aug 2022 00:41:11 +0000
Received: from localhost ([127.0.0.1] helo=malur.postgresql.org)
	by malur.postgresql.org with esmtp (Exim 4.92)
	(envelope-from <pgsql-docs-owner+archive@lists.postgresql.org>)
	id 1oO77O-0003tW-O8
	for pgsql-docs@arkaria.postgresql.org; Wed, 17 Aug 2022 00:41:10 +0000
Received: from magus.postgresql.org ([2a02:c0:301:0:ffff::29])
	by malur.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1oO77O-0003tN-GS
	for pgsql-docs@lists.postgresql.org; Wed, 17 Aug 2022 00:41:10 +0000
Received: from momjian.us ([72.94.173.45])
	by magus.postgresql.org with esmtps (TLS1.3:ECDHE_RSA_AES_256_GCM_SHA384:256)
	(Exim 4.92)
	(envelope-from <bruce@momjian.us>)
	id 1oO77L-0007BV-RK
	for pgsql-docs@lists.postgresql.org; Wed, 17 Aug 2022 00:41:10 +0000
Received: from bruce by momjian.us with local (Exim 4.94.2)
	(envelope-from <bruce@momjian.us>)
	id 1oO77J-00FeK4-Mx; Tue, 16 Aug 2022 20:41:05 -0400
Date: Tue, 16 Aug 2022 20:41:05 -0400
From: Bruce Momjian <bruce@momjian.us>
To: philippe.godfrin@nov.com, pgsql-docs@lists.postgresql.org
Subject: Re: set time zone
Message-ID: <Yvw5IaULlSZ97PCt@momjian.us>
References: <163888728952.1269.5167822676466793158@wrigleys.postgresql.org>
MIME-Version: 1.0
Content-Type: multipart/mixed; boundary="KJ+lKXNIo6AabLTT"
Content-Disposition: inline
In-Reply-To: <163888728952.1269.5167822676466793158@wrigleys.postgresql.org>
List-Id: <pgsql-docs.lists.postgresql.org>
List-Help: <https://lists.postgresql.org/manage/>
List-Subscribe: <https://lists.postgresql.org/manage/>
List-Post: <mailto:pgsql-docs@lists.postgresql.org>
List-Owner: <mailto:pgsql-docs-owner@lists.postgresql.org>
List-Archive: <https://www.postgresql.org/list/pgsql-docs>
Archived-At: 
 <https://www.postgresql.org/message-id/Yvw5IaULlSZ97PCt%40momjian.us>
Precedence: bulk


--KJ+lKXNIo6AabLTT
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline

On Tue, Dec  7, 2021 at 02:28:09PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/13/sql-set.html
> Description:
> 
> Documentation for the set time zone command can be clearer. What it says for
> v13:
> 
> TIME ZONE
> SET TIME ZONE value is an alias for SET timezone TO value. The syntax SET
> TIME ZONE allows special syntax for the time zone specification. Here are
> examples of valid values:
> 'PST8PDT'
> The time zone for Berkeley, California.
> <snip>
> See Section 8.5.3 for more information about time zones.
> 
> Issue #1. 
> There is an example of 'PST8PDT' but there is no explanation as to how to
> build that string to set the time zone. If you follow the recommendation to
> see Section 8.5.3, you encounter Issue #2...
> 
> Issue #2.
> Yes you can find more information about time zones in section 8.5.3, but you
> have to read carefully for this paragraph in Section 8.5.3, which explains
> how NOT to set the Time Zone
> 
> A time zone abbreviation, for example PST. Such a specification merely
> defines a particular offset from UTC, in contrast to full time zone names
> which can imply a set of daylight savings transition rules as well. The
> recognized abbreviations are listed in the pg_timezone_abbrevs view (see
> Section 51.91). You cannot set the configuration parameters TimeZone or
> log_timezone to a time zone abbreviation, but you can use abbreviations in
> date/time input values and with the AT TIME ZONE operator.
> 
> However the prior paragraph says this:
> 
> A full time zone name, for example America/New_York. The recognized time
> zone names are listed in the pg_timezone_names view (see Section 51.92).
> PostgreSQL uses the widely-used IANA time zone data for this purpose, so the
> same time zone names are also recognized by other software.
> 
> This is where you can find the correct name to use in the set time zone
> command.
> 
> SUGGESTION:
> 
> Change the documentation for the SET (SQL) command to read as follows, under
> the TIME ZONE section:
> 
> TIME ZONE
> ... syntax for the time zone specification. The time zone specification can
> be found in the pg_timezone_names view (see Section 51.92).

Actually, both pg_timezone_names values and POSIX-style time zone
specifications are supported by SET.  In the attached patch I mention
that time zone abbreviations are not supported, and then reference the
chapter.  I think that should help.

> Issue #3
> The syntax diagram shows this:
> 
> SET [ SESSION | LOCAL ] configuration_parameter { TO | = } { value | 'value'
> | DEFAULT }
> SET [ SESSION | LOCAL ] TIME ZONE { timezone | LOCAL | DEFAULT }
> 
> Good job, but - the "{ timezone" entry is not referred to. Below in the TIME
> ZONE Section it says this:
> TIME ZONE
> SET TIME ZONE value is an alias for SET timezone TO value.
> 
> The word "value" is highlighted but is not applicable to the syntax diagram
> above.
> 
> SUGGESTION
> 
> Change the syntax diagram to read:
> SET [ SESSION | LOCAL ] configuration_parameter { TO | = } { value | 'value'
> | DEFAULT }
> SET [ SESSION | LOCAL ] TIME ZONE { timezone_name | LOCAL | DEFAULT }
> 
> and the lower section to read:
> 
> TIME ZONE
> SET TIME ZONE timezone_name is an alias for SET timezone TO timezone_name.

I ended up changing the syntax from 'timezone' to 'value' and added
quoted and non-quoted syntax options, again in the attached patch.

Did I miss anything?

-- 
  Bruce Momjian  <bruce@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

  Indecision is a decision.  Inaction is an action.  Mark Batterson


--KJ+lKXNIo6AabLTT
Content-Type: text/x-diff; charset=us-ascii
Content-Disposition: attachment; filename="tz.diff"

diff --git a/doc/src/sgml/ref/set.sgml b/doc/src/sgml/ref/set.sgml
index 5878c61f9b..5459b29525 100644
--- a/doc/src/sgml/ref/set.sgml
+++ b/doc/src/sgml/ref/set.sgml
@@ -22,7 +22,7 @@ PostgreSQL documentation
  <refsynopsisdiv>
 <synopsis>
 SET [ SESSION | LOCAL ] <replaceable class="parameter">configuration_parameter</replaceable> { TO | = } { <replaceable class="parameter">value</replaceable> | '<replaceable class="parameter">value</replaceable>' | DEFAULT }
-SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="parameter">timezone</replaceable> | LOCAL | DEFAULT }
+SET [ SESSION | LOCAL ] TIME ZONE { <replaceable class="parameter">value</replaceable> | '<replaceable class="parameter">value</replaceable>' | LOCAL | DEFAULT }
 </synopsis>
  </refsynopsisdiv>
 
@@ -192,8 +192,8 @@ SELECT setseed(<replaceable>value</replaceable>);
     <varlistentry>
      <term><literal>TIME ZONE</literal></term>
      <listitem>
-      <para><literal>SET TIME ZONE <replaceable>value</replaceable></literal> is an alias
-       for <literal>SET timezone TO <replaceable>value</replaceable></literal>.  The
+      <para><literal>SET TIME ZONE '<replaceable>value</replaceable>'</literal> is an alias
+       for <literal>SET timezone TO '<replaceable>value</replaceable>'</literal>.  The
        syntax <literal>SET TIME ZONE</literal> allows special syntax
        for the time zone specification.  Here are examples of valid
        values:
@@ -254,7 +254,8 @@ SELECT setseed(<replaceable>value</replaceable>);
       </para>
 
       <para>
-       See <xref linkend="datatype-timezones"/> for more information
+       Time zone abbreviations are not supported by <command>SET</command>;
+       see <xref linkend="datatype-timezones"/> for more information
        about time zones.
       </para>
      </listitem>

--KJ+lKXNIo6AabLTT--