Thread
-
Suspected documentation error
The Post Office <noreply@postgresql.org> — 2026-05-05T20:35:35Z
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
-
Re: Suspected documentation error
David G. Johnston <david.g.johnston@gmail.com> — 2026-05-05T23:27:42Z
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. -
Re: Suspected documentation error
Tom Lane <tgl@sss.pgh.pa.us> — 2026-05-06T13:52:02Z
"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
-
Re: Suspected documentation error
David G. Johnston <david.g.johnston@gmail.com> — 2026-05-06T14:07:59Z
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.
-
Re: Suspected documentation error
Tom Lane <tgl@sss.pgh.pa.us> — 2026-05-06T14:13:03Z
"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
-
Re: Suspected documentation error
Bruce Momjian <bruce@momjian.us> — 2026-05-14T15:30:15Z
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.