From 06dc1ffd24096f7c71d1abeaa9e96fec4db9313d Mon Sep 17 00:00:00 2001
From: Bruce Momjian <bruce@momjian.us>
Date: Tue, 18 Feb 2025 15:51:31 -0500
Subject: [PATCH] doc: add example of sign mismatch with POSIX/ISO-8601 time
 zones

Author: Laurenz Albe

Discussion: https://postgr.es/m/eb4d1e15c6822c1937be1491118500dd9201492f.camel@cybertec.at
---
 doc/src/sgml/datatype.sgml | 8 ++++++++
 doc/src/sgml/func.sgml     | 9 +++++++--
 2 files changed, 15 insertions(+), 2 deletions(-)

diff --git a/doc/src/sgml/datatype.sgml b/doc/src/sgml/datatype.sgml
index b20241feb50..87679dc4a11 100644
--- a/doc/src/sgml/datatype.sgml
+++ b/doc/src/sgml/datatype.sgml
@@ -2682,6 +2682,14 @@ TIMESTAMP WITH TIME ZONE '2004-10-19 10:23:54+02'
      savings was nominally in effect on that date.
     </para>
 
+    <note>
+     <para>
+      The sign in POSIX-style time zone specifications has the opposite meaning
+      of the sign in ISO-8601 datetime values.  For example, the POSIX time zone
+      for <literal>2014-06-04 12:00+04</literal> would be UTC-4.
+     </para>
+    </note>
+
     <para>
      To complicate matters, some jurisdictions have used the same timezone
      abbreviation to mean different UTC offsets at different times; for
diff --git a/doc/src/sgml/func.sgml b/doc/src/sgml/func.sgml
index 7efc81936ab..2548a57df31 100644
--- a/doc/src/sgml/func.sgml
+++ b/doc/src/sgml/func.sgml
@@ -11006,6 +11006,8 @@ SELECT TIMESTAMP '2001-02-16 20:38:40' AT TIME ZONE 'Asia/Tokyo' AT TIME ZONE 'A
 <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 05:38:40</computeroutput>
 SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT LOCAL;
 <lineannotation>Result: </lineannotation><computeroutput>2001-02-16 17:38:40</computeroutput>
+SELECT TIMESTAMP WITH TIME ZONE '2001-02-16 20:38:40-05' AT TIME ZONE '+05';
+<lineannotation>Result: </lineannotation><computeroutput>2001-02-16 20:38:40</computeroutput>
 SELECT TIME WITH TIME ZONE '20:38:40-05' AT LOCAL;
 <lineannotation>Result: </lineannotation><computeroutput>17:38:40</computeroutput>
 </screen>
@@ -11018,11 +11020,14 @@ SELECT TIME WITH TIME ZONE '20:38:40-05' AT LOCAL;
     Tokyo time to Chicago time.  The fourth example shifts the time stamp
     with time zone value to the time zone currently specified by the
     <varname>TimeZone</varname> setting and returns the value without a
-    time zone.
+    time zone.  The fifth example demonstrates that the sign in a POSIX-style
+    time zone specification has the opposite meaning of the sign in an
+    ISO-8601 datetime literal, as described in <xref linkend="datatype-timezones"/>
+    and <xref linkend="datetime-appendix"/>.
    </para>
 
    <para>
-    The fifth example is a cautionary tale. Due to the fact that there is no
+    The sixth example is a cautionary tale. Due to the fact that there is no
     date associated with the input value, the conversion is made using the
     current date of the session. Therefore, this static example may show a wrong
     result depending on the time of the year it is viewed because
-- 
2.30.2