MIME-Version: 1.0
References: <CAEoWx2n6ShLMOnjOtf63TjjgGbgiTVT5OMsSOFmbjGb6Xue1Bw@mail.gmail.com>
 <CABV9wwMPmo-dg=oV+NaJGa_==uo5+TTvk58aNtjVQZBtMcRVBw@mail.gmail.com> <CAEoWx2kkh5kCZwYOYaOVShjh3un2mJTGrcFZyhJXd320PHYfJw@mail.gmail.com>
In-Reply-To: <CAEoWx2kkh5kCZwYOYaOVShjh3un2mJTGrcFZyhJXd320PHYfJw@mail.gmail.com>
From: Robert Treat <rob@xzilla.net>
Date: Wed, 7 Jan 2026 18:13:33 -0500
Message-ID: <CAJSLCQ10_gia2-GzQndwoM-n-v2DWz4LnAY5jyO2ZmNiE+56tA@mail.gmail.com>
Subject: Re: DOC: fixes multiple errors in alter table doc
To: Chao Li <li.evan.chao@gmail.com>
Cc: Postgres hackers <pgsql-hackers@lists.postgresql.org>
Content-Type: text/plain; charset="UTF-8"
Content-Transfer-Encoding: quoted-printable
Archived-At: <https://www.postgresql.org/message-id/CAJSLCQ10_gia2-GzQndwoM-n-v2DWz4LnAY5jyO2ZmNiE%2B56tA%40mail.gmail.com>
Precedence: bulk

On Sat, Jan 3, 2026 at 11:30=E2=80=AFPM Chao Li <li.evan.chao@gmail.com> wr=
ote:
> On Jan 2, 2026, at 10:54, Robert Treat <rob@xzilla.net> wrote:
> Hi Robert,
>
> Thanks you very much for your review.
>
>
> On Thu, Dec 18, 2025 at 2:22=E2=80=AFAM Chao Li <li.evan.chao@gmail.com> =
wrote:
> Hi Hacker,
<snip>
> 2. In sub-command details section, "ADD COLUMN [ IF NOT EXISTS ]=E2=80=9D=
 missed =E2=80=9C[]" with =E2=80=9CCOLUMN=E2=80=9D, which is misleading, be=
cause =E2=80=9CCOLUMN=E2=80=9D is actually optional.
>
> Seems technically correct and potentially useful, and I see you
> handled this for the DROP COLUMN variant as well, so I could see a +1
> on this one.
>
> Thanks for confirming.
>
>
> 3. For all =E2=80=9Calter column=E2=80=9D sub-commands, "ALTER [ COLUMN ]=
=E2=80=9D are omitted, which is also confusing, because none of other sub-c=
ommands omit their prefix part.
>
>
> Hmm... I'm curious what you find confusing about this. Is the
> confusion in trying to find or understand the information presented,
> or confusing as to why it isn't all documented the same way? The
> downside of your "fix" is that this introduces a lot of extra text
> that is more or less noise, especially for folks trying to skim the
> documents looking for very specific command references.  And while I
> agree that we aren't 100% consistent on this within the ALTER TABLE
> subcommands, we use this same mixed pattern of omission on other pages
> (see ALTER TYPE for instance). If we were to insist on making this
> consistent here, I think we'd probably need to look at other pages as
> well and evaluate or update them too. I'm not sure that would be an
> improvement though.
>
>
> The confusion came from my own first-time reading of the documentation. S=
ince the page is quite long, when I was reading the action descriptions and=
 wanted to confirm the exact sub-command syntax, I often had to scroll back=
 up to the syntax section. That led me to think it might be helpful to incl=
ude the full sub-command form directly with the action descriptions.
>
> That said, I understand your concern. The change did make the text longer=
 and added noise. In v2, I=E2=80=99ve therefore reverted that broader chang=
e. As you pointed out, if we were to pursue this kind of consistency, it wo=
uld need to be handled across other similar pages as well, which would be b=
etter done as a dedicated and more carefully scoped patch.
>
> So, v2=E2=80=99s scope is significantly reduced, only a fix for my origin=
al point 2 is retained.
>

Makes sense to me and seems like an improvement, so +1.


Robert Treat
https://xzilla.net