public inbox for [email protected]  

help / color / mirror / Atom feed

From: Chao Li <[email protected]>
To: Robert Treat <[email protected]>
Cc: Postgres hackers <[email protected]>
Subject: Re: DOC: fixes multiple errors in alter table doc
Date: Thu, 8 Jan 2026 09:38:48 +0800
Message-ID: <[email protected]> (raw)
In-Reply-To: <CAJSLCQ10_gia2-GzQndwoM-n-v2DWz4LnAY5jyO2ZmNiE+56tA@mail.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>



> On Jan 8, 2026, at 07:13, Robert Treat <[email protected]> wrote:
> 
> On Sat, Jan 3, 2026 at 11:30 PM Chao Li <[email protected]> wrote:
>> On Jan 2, 2026, at 10:54, Robert Treat <[email protected]> wrote:
>> Hi Robert,
>> 
>> Thanks you very much for your review.
>> 
>> 
>> On Thu, Dec 18, 2025 at 2:22 AM Chao Li <[email protected]> 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/

view thread (6+ messages)  latest in thread

reply

Reply instructions:

You may reply publicly to this message via plain-text email
using any one of the following methods:

* Reply to all the recipients using the --to and --cc options:
  reply via email

  To: [email protected]
  Cc: [email protected], [email protected], [email protected]
  Subject: Re: DOC: fixes multiple errors in alter table doc
  In-Reply-To: <[email protected]>

* Save the following mbox file, import it into your mail client,
  and reply-to-all from there: mbox

This inbox is served by agora; see mirroring instructions
for how to clone and mirror all data and code used for this inbox