Re: DOC: fixes multiple errors in alter table doc

On Thu, Jan 22, 2026 at 5:33 PM Chao Li <li(dot)evan(dot)chao(at)gmail(dot)com> wrote:

>
>
> > On Jan 8, 2026, at 09:38, Chao Li <li(dot)evan(dot)chao(at)gmail(dot)com> wrote:
> >
> >
> >
> >> On Jan 8, 2026, at 07:13, Robert Treat <rob(at)xzilla(dot)net> wrote:
> >>
> >> On Sat, Jan 3, 2026 at 11:30 PM Chao Li <li(dot)evan(dot)chao(at)gmail(dot)com> wrote:
> >>> On Jan 2, 2026, at 10:54, Robert Treat <rob(at)xzilla(dot)net> wrote:
> >>> Hi Robert,
> >>>
> >>> Thanks you very much for your review.
> >>>
> >>>
> >>> On Thu, Dec 18, 2025 at 2:22 AM Chao Li <li(dot)evan(dot)chao(at)gmail(dot)com>
> wrote:
> >>> Hi Hacker,
> >> <snip>
> >>> 2. In sub-command details section, "ADD COLUMN [ IF NOT EXISTS ]”
> missed “[]" with “COLUMN”, which is misleading, because “COLUMN” 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 “alter column” sub-commands, "ALTER [ COLUMN ]” are
> omitted, which is also confusing, because none of other sub-commands 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. 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.
> >>>
> >>> That said, I understand your concern. The change did make the text
> longer and added noise. In v2, I’ve 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.
> >>>
> >>> So, v2’s scope is significantly reduced, only a fix for my original
> point 2 is retained.
> >>>
> >>
> >> Makes sense to me and seems like an improvement, so +1.
> >>
> >
> > 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/
>
> Bump. This is a tiny doc fix.
>

PFA v3: Rebased, and added reviewer and discussion information.

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