Please add example

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 +