Suspected documentation error
The following documentation comment has been logged on the website:
Page: https://www.postgresql.org/docs/18/functions-formatting.html
Description:
Hello,
I'm just learning SQL/Postgres for the first time, so please forgive me if
this is an incorrect assumption.
I've just learnt through seeing the solution to an exercise using the
TO_CHAR function, that minutes are referred to as "mi" as opposed to "mm".
As such, whilst looking through this page
(https://www.postgresql.org/docs/current/functions-formatting.html) as shown
in the Udemy course I'm following, I noticed that the notes "OF" state
"time-zone offset from UTC (HH or HH:MM)", which I believe should be
"time-zone offset from UTC (HH or HH:MI)".
Hope this helps.
Thanks,
Phil
On Tue, May 5, 2026 at 3:02 PM PG Doc comments form <noreply@postgresql.org>
wrote:
As such, whilst looking through this page
(https://www.postgresql.org/docs/current/functions-formatting.html) as
shown
in the Udemy course I'm following, I noticed that the notes "OF" state
"time-zone offset from UTC (HH or HH:MM)", which I believe should be
"time-zone offset from UTC (HH or HH:MI)".
Technically interpreting either of those according to the format specifiers
co-located in that table is wrong. All HH and MM stand for here are hours
and minutes, trying to communicate fixed two-digits.
psql -c "SET LOCAL timezone = 'Pacific/Apia'; SELECT to_char(now(),
'YYYY-MM-DD HH24:MI:SS OF') AS plus13_apia;"
plus13_apia
-------------------------
2026-05-06 12:11:49 +13
(1 row)
HH is defined on the range 0-12 but here we see we get +13 (and it's easy
to also produce negative offsets).
That said, the way I'd fix this is:
TZH - time-zone hours offset from UTC , signed, two-digits, e.g., -04 or +05
TZM - time-zone minutes offset from UTC, unsigned two-digit (to append, not
add), e.g., 00 or 30
OF - TZH[:TZM] time-zone offset, but minutes are suppressed when zero.
e.g., -04 or +05:30
David J.
"David G. Johnston" <david.g.johnston@gmail.com> writes:
On Tue, May 5, 2026 at 3:02 PM PG Doc comments form <noreply@postgresql.org>
wrote:in the Udemy course I'm following, I noticed that the notes "OF" state
"time-zone offset from UTC (HH or HH:MM)", which I believe should be
"time-zone offset from UTC (HH or HH:MI)".
Technically interpreting either of those according to the format specifiers
co-located in that table is wrong.
Yeah; I think writing MI would make for more confusion not less, since
this specifier doesn't emit the same values that HH and MI refer to.
All HH and MM stand for here are hours
and minutes, trying to communicate fixed two-digits.
I'm inclined to try to fix it via formatting: change HH and MM to
lower case and wrap them in <replaceable> so they render in italics.
The other details are easily discovered by experiment, so I don't
feel a need to make the table entries any more verbose. Thoughts?
regards, tom lane
On Wed, May 6, 2026 at 6:52 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
"David G. Johnston" <david.g.johnston@gmail.com> writes:
On Tue, May 5, 2026 at 3:02 PM PG Doc comments form <
noreply@postgresql.org>
wrote:
in the Udemy course I'm following, I noticed that the notes "OF" state
"time-zone offset from UTC (HH or HH:MM)", which I believe should be
"time-zone offset from UTC (HH or HH:MI)".Technically interpreting either of those according to the format
specifiers
co-located in that table is wrong.
Yeah; I think writing MI would make for more confusion not less, since
this specifier doesn't emit the same values that HH and MI refer to.All HH and MM stand for here are hours
and minutes, trying to communicate fixed two-digits.I'm inclined to try to fix it via formatting: change HH and MM to
lower case and wrap them in <replaceable> so they render in italics.
The other details are easily discovered by experiment, so I don't
feel a need to make the table entries any more verbose. Thoughts?
This table doesn't seem to care about having "verbose" descriptions, e.g.,
"IDDD - day of ISO 8601 week-numbering year (001–371; day 1 of the year is
Monday of the first ISO week)"
Our documentation is considered good because we try to avoid making people
learn by experimentation.
And isn't replaceable usually something the user is expected to provide a
value for - not something the system populates?
David J.
"David G. Johnston" <david.g.johnston@gmail.com> writes:
On Wed, May 6, 2026 at 6:52 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
I'm inclined to try to fix it via formatting: change HH and MM to
lower case and wrap them in <replaceable> so they render in italics.
And isn't replaceable usually something the user is expected to provide a
value for - not something the system populates?
No, I think it just means "this word is not literally what you'd see
or type".
regards, tom lane
On Wed, May 6, 2026 at 10:13:03AM -0400, Tom Lane wrote:
"David G. Johnston" <david.g.johnston@gmail.com> writes:
On Wed, May 6, 2026 at 6:52 AM Tom Lane <tgl@sss.pgh.pa.us> wrote:
I'm inclined to try to fix it via formatting: change HH and MM to
lower case and wrap them in <replaceable> so they render in italics.And isn't replaceable usually something the user is expected to provide a
value for - not something the system populates?No, I think it just means "this word is not literally what you'd see
or type".
I came up with the attached patch. I think 'mm' is just too much like
months so I sent with 'mi', and the "replaceable" tag was already there.
--
Bruce Momjian <bruce@momjian.us> https://momjian.us
EDB https://enterprisedb.com
Do not let urgent matters crowd out time for investment in the future.