public inbox for pgsql-docs@postgresql.org
help / color / mirror / Atom feedSuspected documentation error
6+ messages / 4 participants
[nested] [flat]
* Suspected documentation error
@ 2026-05-05 20:35 PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 6+ messages in thread
From: PG Doc comments form @ 2026-05-05 20:35 UTC (permalink / raw)
To: pgsql-docs@lists.postgresql.org; +Cc: scoobster17@gmail.com
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 23:27 David G. Johnston <david.g.johnston@gmail.com>
parent: PG Doc comments form <noreply@postgresql.org>
0 siblings, 1 reply; 6+ messages in thread
From: David G. Johnston @ 2026-05-05 23:27 UTC (permalink / raw)
To: scoobster17@gmail.com; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Suspected documentation error
@ 2026-05-06 13:52 Tom Lane <tgl@sss.pgh.pa.us>
parent: David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 6+ messages in thread
From: Tom Lane @ 2026-05-06 13:52 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: scoobster17@gmail.com; pgsql-docs@lists.postgresql.org
"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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Suspected documentation error
@ 2026-05-06 14:07 David G. Johnston <david.g.johnston@gmail.com>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 1 reply; 6+ messages in thread
From: David G. Johnston @ 2026-05-06 14:07 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: scoobster17@gmail.com; pgsql-docs@lists.postgresql.org
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.
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Suspected documentation error
@ 2026-05-06 14:13 Tom Lane <tgl@sss.pgh.pa.us>
parent: David G. Johnston <david.g.johnston@gmail.com>
0 siblings, 1 reply; 6+ messages in thread
From: Tom Lane @ 2026-05-06 14:13 UTC (permalink / raw)
To: David G. Johnston <david.g.johnston@gmail.com>; +Cc: scoobster17@gmail.com; pgsql-docs@lists.postgresql.org
"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
^ permalink raw reply [nested|flat] 6+ messages in thread
* Re: Suspected documentation error
@ 2026-05-14 15:30 Bruce Momjian <bruce@momjian.us>
parent: Tom Lane <tgl@sss.pgh.pa.us>
0 siblings, 0 replies; 6+ messages in thread
From: Bruce Momjian @ 2026-05-14 15:30 UTC (permalink / raw)
To: Tom Lane <tgl@sss.pgh.pa.us>; +Cc: David G. Johnston <david.g.johnston@gmail.com>; scoobster17@gmail.com; pgsql-docs@lists.postgresql.org
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.
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 <noreply@postgresql.org>
2026-05-05 23:27 ` David G. Johnston <david.g.johnston@gmail.com>
2026-05-06 13:52 ` Tom Lane <tgl@sss.pgh.pa.us>
2026-05-06 14:07 ` David G. Johnston <david.g.johnston@gmail.com>
2026-05-06 14:13 ` Tom Lane <tgl@sss.pgh.pa.us>
2026-05-14 15:30 ` Bruce Momjian <bruce@momjian.us>
This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox