Re: Suspected documentation error

On Wed, May 6, 2026 at 6:52 AM Tom Lane <tgl(at)sss(dot)pgh(dot)pa(dot)us> wrote:

> "David G. Johnston" <david(dot)g(dot)johnston(at)gmail(dot)com> writes:
> > On Tue, May 5, 2026 at 3:02 PM PG Doc comments form <
> noreply(at)postgresql(dot)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.