Date: Fri, 27 Sep 2019 13:13:32 -0400
From: Bruce Momjian <bruce@momjian.us>
To: lancetcampbell@gmail.com, pgsql-docs@lists.postgresql.org
Subject: Re: Please add example
Message-ID: <20190927171332.GH31412@momjian.us>
References: <156769910245.1126.4395971697026118289@wrigleys.postgresql.org>
MIME-Version: 1.0
Content-Type: text/plain; charset=us-ascii
Content-Disposition: inline
In-Reply-To: <156769910245.1126.4395971697026118289@wrigleys.postgresql.org>
User-Agent: Mutt/1.10.1 (2018-07-13)
Precedence: bulk

On Thu, Sep  5, 2019 at 03:58:22PM +0000, PG Doc comments form wrote:
> The following documentation comment has been logged on the website:
> 
> Page: https://www.postgresql.org/docs/11/functions-formatting.html
> Description:
> 
> On this screen:
> https://www.postgresql.org/docs/11/functions-formatting.html
> 
> Please consider adding this as an example:
> to_char( (now()-INTERVAL '10 minutes') AT TIME ZONE
> 'UTC','YYYY-MM-DD"T"HH24:MI')
> 
> Output: 2019-09-05T15:43
> 
> Why:
> This will demonstrate not only formatting but how to deal with converting
> your local timestamp to other timestamps and how to get times relative to
> the current time.  This is extremely helpful as a way to deal with so many
> external system that need UTC time zones like AWS while your database uses
> local time zones.  
> 
> This example would have totally changed how I would have dealt with many
> issues in my software.  But since the example did not exist I had no idea I
> could have went down this path.  

I did improve the AT TIME ZONE docs in 2018:

	commit dd6073f22a
	Author: Bruce Momjian <bruce@momjian.us>
	Date:   Tue Sep 4 22:34:07 2018 -0400
	
	    docs:  improve AT TIME ZONE description
	
	    The previous description was unclear.  Also add a third example, change
	    use of time zone acronyms to more verbose descriptions, and add a
	    mention that using 'time' with AT TIME ZONE uses the current time zone
	    rules.
	
	    Backpatch-through: 9.3

and you can see the results here:

    https://www.postgresql.org/docs/11/functions-datetime.html#FUNCTIONS-DATETIME-ZONECONVERT

I am not sure it helps to try to show AT TIME ZONE behavior in the
to_char docs.

-- 
  Bruce Momjian  <bruce@momjian.us>        http://momjian.us
  EnterpriseDB                             http://enterprisedb.com

+ As you are, so once was I.  As I am, so you will be. +
+                      Ancient Roman grave inscription +