Content-Type: text/plain;
	charset=utf-8
Mime-Version: 1.0 (Mac OS X Mail 16.0 \(3826.700.81\))
Subject: Re: DOC: fixes multiple errors in alter table doc
From: Chao Li <li.evan.chao@gmail.com>
In-Reply-To: <CAJSLCQ10_gia2-GzQndwoM-n-v2DWz4LnAY5jyO2ZmNiE+56tA@mail.gmail.com>
Date: Thu, 8 Jan 2026 09:38:48 +0800
Cc: Postgres hackers <pgsql-hackers@lists.postgresql.org>
Content-Transfer-Encoding: quoted-printable
Message-Id: <E9FEE306-E00D-4ECA-97B0-219BE7AB5169@gmail.com>
References: <CAEoWx2n6ShLMOnjOtf63TjjgGbgiTVT5OMsSOFmbjGb6Xue1Bw@mail.gmail.com>
 <CABV9wwMPmo-dg=oV+NaJGa_==uo5+TTvk58aNtjVQZBtMcRVBw@mail.gmail.com>
 <CAEoWx2kkh5kCZwYOYaOVShjh3un2mJTGrcFZyhJXd320PHYfJw@mail.gmail.com>
 <CAJSLCQ10_gia2-GzQndwoM-n-v2DWz4LnAY5jyO2ZmNiE+56tA@mail.gmail.com>
To: Robert Treat <rob@xzilla.net>
Archived-At: <https://www.postgresql.org/message-id/E9FEE306-E00D-4ECA-97B0-219BE7AB5169%40gmail.com>
Precedence: bulk


> On Jan 8, 2026, at 07:13, Robert Treat <rob@xzilla.net> wrote:
>=20
> On Sat, Jan 3, 2026 at 11:30=E2=80=AFPM Chao Li =
<li.evan.chao@gmail.com> wrote:
>> On Jan 2, 2026, at 10:54, Robert Treat <rob@xzilla.net> wrote:
>> Hi Robert,
>>=20
>> Thanks you very much for your review.
>>=20
>>=20
>> 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, =
because =E2=80=9CCOLUMN=E2=80=9D is actually optional.
>>=20
>> 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.
>>=20
>> Thanks for confirming.
>>=20
>>=20
>> 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-commands omit their prefix part.
>>=20
>>=20
>> 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.
>>=20
>>=20
>> The confusion came from my own first-time reading of the =
documentation. Since 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 include the full sub-command form directly =
with the action descriptions.
>>=20
>> 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 change. As you pointed out, if we were to pursue this kind of =
consistency, it would need to be handled across other similar pages as =
well, which would be better done as a dedicated and more carefully =
scoped patch.
>>=20
>> So, v2=E2=80=99s scope is significantly reduced, only a fix for my =
original point 2 is retained.
>>=20
>=20
> Makes sense to me and seems like an improvement, so +1.
>=20

Hi Robert,

Thank you very much for your review. This is the CF entry =
https://commitfest.postgresql.org/patch/6328/, you may add you as a =
reviewer. And I just changed the status to Ready for Committer.

Best regards,
--
Chao Li (Evan)
HighGo Software Co., Ltd.
https://www.highgo.com/