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  <br...@momjian.us>        https://momjian.us
  EDB                                      https://enterprisedb.com

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

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>

Reply via email to