public inbox for [email protected]help / color / mirror / Atom feed
Suspected documentation error 6+ messages / 4 participants [nested] [flat]
* Suspected documentation error @ 2026-05-05 20:35 PG Doc comments form <[email protected]> 2026-05-05 23:27 ` Re: Suspected documentation error David G. Johnston <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: PG Doc comments form @ 2026-05-05 20:35 UTC (permalink / raw) To: [email protected]; +Cc: [email protected] 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 ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Suspected documentation error 2026-05-05 20:35 Suspected documentation error PG Doc comments form <[email protected]> @ 2026-05-05 23:27 ` David G. Johnston <[email protected]> 2026-05-06 13:52 ` Re: Suspected documentation error Tom Lane <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: David G. Johnston @ 2026-05-05 23:27 UTC (permalink / raw) To: [email protected]; [email protected] On Tue, May 5, 2026 at 3:02 PM PG Doc comments form <[email protected]> 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. ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Suspected documentation error 2026-05-05 20:35 Suspected documentation error PG Doc comments form <[email protected]> 2026-05-05 23:27 ` Re: Suspected documentation error David G. Johnston <[email protected]> @ 2026-05-06 13:52 ` Tom Lane <[email protected]> 2026-05-06 14:07 ` Re: Suspected documentation error David G. Johnston <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: Tom Lane @ 2026-05-06 13:52 UTC (permalink / raw) To: David G. Johnston <[email protected]>; +Cc: [email protected]; [email protected] "David G. Johnston" <[email protected]> writes: > On Tue, May 5, 2026 at 3:02 PM PG Doc comments form <[email protected]> > 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 ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Suspected documentation error 2026-05-05 20:35 Suspected documentation error PG Doc comments form <[email protected]> 2026-05-05 23:27 ` Re: Suspected documentation error David G. Johnston <[email protected]> 2026-05-06 13:52 ` Re: Suspected documentation error Tom Lane <[email protected]> @ 2026-05-06 14:07 ` David G. Johnston <[email protected]> 2026-05-06 14:13 ` Re: Suspected documentation error Tom Lane <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: David G. Johnston @ 2026-05-06 14:07 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: [email protected]; [email protected] On Wed, May 6, 2026 at 6:52 AM Tom Lane <[email protected]> wrote: > "David G. Johnston" <[email protected]> writes: > > On Tue, May 5, 2026 at 3:02 PM PG Doc comments form < > [email protected]> > > 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. ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Suspected documentation error 2026-05-05 20:35 Suspected documentation error PG Doc comments form <[email protected]> 2026-05-05 23:27 ` Re: Suspected documentation error David G. Johnston <[email protected]> 2026-05-06 13:52 ` Re: Suspected documentation error Tom Lane <[email protected]> 2026-05-06 14:07 ` Re: Suspected documentation error David G. Johnston <[email protected]> @ 2026-05-06 14:13 ` Tom Lane <[email protected]> 2026-05-14 15:30 ` Re: Suspected documentation error Bruce Momjian <[email protected]> 0 siblings, 1 reply; 6+ messages in thread From: Tom Lane @ 2026-05-06 14:13 UTC (permalink / raw) To: David G. Johnston <[email protected]>; +Cc: [email protected]; [email protected] "David G. Johnston" <[email protected]> writes: > On Wed, May 6, 2026 at 6:52 AM Tom Lane <[email protected]> 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 ^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Suspected documentation error 2026-05-05 20:35 Suspected documentation error PG Doc comments form <[email protected]> 2026-05-05 23:27 ` Re: Suspected documentation error David G. Johnston <[email protected]> 2026-05-06 13:52 ` Re: Suspected documentation error Tom Lane <[email protected]> 2026-05-06 14:07 ` Re: Suspected documentation error David G. Johnston <[email protected]> 2026-05-06 14:13 ` Re: Suspected documentation error Tom Lane <[email protected]> @ 2026-05-14 15:30 ` Bruce Momjian <[email protected]> 0 siblings, 0 replies; 6+ messages in thread From: Bruce Momjian @ 2026-05-14 15:30 UTC (permalink / raw) To: Tom Lane <[email protected]>; +Cc: David G. Johnston <[email protected]>; [email protected]; [email protected] On Wed, May 6, 2026 at 10:13:03AM -0400, Tom Lane wrote: > "David G. Johnston" <[email protected]> writes: > > On Wed, May 6, 2026 at 6:52 AM Tom Lane <[email protected]> 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 <[email protected]> https://momjian.us EDB https://enterprisedb.com Do not let urgent matters crowd out time for investment in the future. Attachments: [text/x-diff] mi.diff (711B, 2-mi.diff) download | inline diff: diff --git a/doc/src/sgml/func/func-formatting.sgml b/doc/src/sgml/func/func-formatting.sgml index af9e2223998..e4edaf4f42c 100644 --- a/doc/src/sgml/func/func-formatting.sgml +++ b/doc/src/sgml/func/func-formatting.sgml @@ -424,8 +424,8 @@ </row> <row> <entry><literal>OF</literal></entry> - <entry>time-zone offset from UTC (<replaceable>HH</replaceable> - or <replaceable>HH</replaceable><literal>:</literal><replaceable>MM</replaceable>)</entry> + <entry>time-zone offset from UTC (<replaceable>hh</replaceable> + or <replaceable>hh</replaceable><literal>:</literal><replaceable>mi</replaceable>)</entry> </row> </tbody> </tgroup> ^ permalink raw reply [nested|flat] 6+ messages in thread
end of thread, other threads:[~2026-05-14 15:30 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed) -- links below jump to the message on this page -- 2026-05-05 20:35 Suspected documentation error PG Doc comments form <[email protected]> 2026-05-05 23:27 ` David G. Johnston <[email protected]> 2026-05-06 13:52 ` Tom Lane <[email protected]> 2026-05-06 14:07 ` David G. Johnston <[email protected]> 2026-05-06 14:13 ` Tom Lane <[email protected]> 2026-05-14 15:30 ` Bruce Momjian <[email protected]>
This inbox is served by agora; see mirroring instructions for how to clone and mirror all data and code used for this inbox