MIME-Version: 1.0
References: <177801333530.795.16999885814007014333@wrigleys.postgresql.org>
 <CAKFQuwYWhSxoCPf9RTVVgs96oU78rdh3Aj05s2PCppb1GscA8g@mail.gmail.com>
 <767365.1778075522@sss.pgh.pa.us>
In-Reply-To: <767365.1778075522@sss.pgh.pa.us>
From: "David G. Johnston" <david.g.johnston@gmail.com>
Date: Wed, 6 May 2026 07:07:59 -0700
Message-ID: 
 <CAKFQuwa8KbYmjwv1nw-=5JJ3Yks2GApX2GrcBNfOAgsZmwPBTQ@mail.gmail.com>
Subject: Re: Suspected documentation error
To: Tom Lane <tgl@sss.pgh.pa.us>
Cc: scoobster17@gmail.com, pgsql-docs@lists.postgresql.org
Content-Type: multipart/alternative; boundary="0000000000001e740d065126b38c"
Archived-At: 
 <https://www.postgresql.org/message-id/CAKFQuwa8KbYmjwv1nw-%3D5JJ3Yks2GApX2GrcBNfOAgsZmwPBTQ%40mail.gmail.com>
Precedence: bulk

--0000000000001e740d065126b38c
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

On Wed, May 6, 2026 at 6:52=E2=80=AFAM 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=E2=80=AFPM 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=E2=80=93371; 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.

--0000000000001e740d065126b38c
Content-Type: text/html; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable

<div dir=3D"ltr"><div dir=3D"ltr"><div class=3D"gmail_default" style=3D"fon=
t-family:arial,helvetica,sans-serif"><span style=3D"font-family:Arial,Helve=
tica,sans-serif">On Wed, May 6, 2026 at 6:52=E2=80=AFAM Tom Lane &lt;<a hre=
f=3D"mailto:tgl@sss.pgh.pa.us">tgl@sss.pgh.pa.us</a>&gt; wrote:</span></div=
></div><div class=3D"gmail_quote gmail_quote_container"><blockquote class=
=3D"gmail_quote" style=3D"margin:0px 0px 0px 0.8ex;border-left:1px solid rg=
b(204,204,204);padding-left:1ex">&quot;David G. Johnston&quot; &lt;<a href=
=3D"mailto:david.g.johnston@gmail.com" target=3D"_blank">david.g.johnston@g=
mail.com</a>&gt; writes:<br>
&gt; On Tue, May 5, 2026 at 3:02=E2=80=AFPM PG Doc comments form &lt;<a hre=
f=3D"mailto:noreply@postgresql.org" target=3D"_blank">noreply@postgresql.or=
g</a>&gt;<br>
&gt; wrote:<br>
&gt;&gt; in the Udemy course I&#39;m following, I noticed that the notes &q=
uot;OF&quot; state<br>
&gt;&gt; &quot;time-zone offset from UTC (HH or HH:MM)&quot;, which I belie=
ve should be<br>
&gt;&gt; &quot;time-zone offset from UTC (HH or HH:MI)&quot;.<br>
<br>
&gt; Technically interpreting either of those according to the format speci=
fiers<br>
&gt; co-located in that table is wrong.<br>
<br>
Yeah; I think writing MI would make for more confusion not less, since<br>
this specifier doesn&#39;t emit the same values that HH and MI refer to.<br=
>
<br>
&gt; All HH and MM stand for here are hours<br>
&gt; and minutes, trying to communicate fixed two-digits.<br>
<br>
I&#39;m inclined to try to fix it via formatting: change HH and MM to<br>
lower case and wrap them in &lt;replaceable&gt; so they render in italics.<=
br>
The other details are easily discovered by experiment, so I don&#39;t<br>
feel a need to make the table entries any more verbose.=C2=A0 Thoughts?<br>=
</blockquote><div><br></div><div class=3D"gmail_default" style=3D"font-fami=
ly:arial,helvetica,sans-serif">This table doesn&#39;t seem to care about ha=
ving &quot;verbose&quot; descriptions, e.g.,</div><div class=3D"gmail_defau=
lt" style=3D"font-family:arial,helvetica,sans-serif"><br>&quot;IDDD - day o=
f ISO 8601 week-numbering year (001=E2=80=93371; day 1 of the year is Monda=
y of the first ISO week)&quot;</div><div class=3D"gmail_default" style=3D"f=
ont-family:arial,helvetica,sans-serif"><br></div><div class=3D"gmail_defaul=
t" style=3D"font-family:arial,helvetica,sans-serif">Our documentation is co=
nsidered good because we try to avoid making people learn by experimentatio=
n.</div><div class=3D"gmail_default" style=3D"font-family:arial,helvetica,s=
ans-serif"><br></div><div class=3D"gmail_default" style=3D"font-family:aria=
l,helvetica,sans-serif">And isn&#39;t replaceable usually something the use=
r is expected to provide a value for - not something the system populates?<=
/div><div class=3D"gmail_default" style=3D"font-family:arial,helvetica,sans=
-serif"><br></div><div class=3D"gmail_default" style=3D"font-family:arial,h=
elvetica,sans-serif">David J.</div><div class=3D"gmail_default" style=3D"fo=
nt-family:arial,helvetica,sans-serif"><br></div></div></div>

--0000000000001e740d065126b38c--