Обсуждение: CREATE/ALTER PUBLICATION improvements for syntax synopsis

During some recent reviews in this area, I noticed both CREATE/ALTER
PUBLICATION synopses say:

----------
where publication_object is one of:

    TABLE [ ONLY ] table_name [ * ] [ ( column_name [, ... ] ) ] [
WHERE ( expression ) ] [, ... ]
    TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]
----------

IMO it would be better to include another pair of { } preceding the
TABLE ellipsis:
a) for consistency with the second (TABLES IN SCHEMA) case
b) to help remove ambiguity, what part of the syntax the TABLE ellipsis is for

e.g.
----------
    TABLE { [ ONLY ] table_name [ * ] [ ( column_name [, ... ] ) ] [
WHERE ( expression ) ] } [, ... ]
    TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]
----------

I attached a v1 patch to do this.

Thoughts?

======
Kind Regards,
Peter Smith.
Fujitsu Australia

Added a CF entry [1] for this.

======
[1]  https://commitfest.postgresql.org/patch/6062/

Kind Regards,
Peter Smith.
Fujitsu Australia

A rebase was needed. Here is patch v2.

======
Kind Regards,
Peter Smith.
Fujitsu Australia

A rebase was needed. Here is patch v3.

======
Kind Regards,
Peter Smith.
Fujitsu Australia

On Fri, Nov 14, 2025 at 10:23 AM Peter Smith <smithpb2250@gmail.com> wrote:
>
> A rebase was needed. Here is patch v3.

Thanks for the patch! LGTM.

For example, in the CREATE PUBLICATION synopsis, the part that can be
repeated is "[ ONLY ] table_name ... [ WHERE ( expression ) ]" not just
the WHERE clause, so using curly brackets around that seems correct.

Regards,

--
Fujii Masao

> On Nov 14, 2025, at 15:47, Fujii Masao <masao.fujii@gmail.com> wrote:
>
> On Fri, Nov 14, 2025 at 10:23 AM Peter Smith <smithpb2250@gmail.com> wrote:
>>
>> A rebase was needed. Here is patch v3.
>
> Thanks for the patch! LGTM.
>
> For example, in the CREATE PUBLICATION synopsis, the part that can be
> repeated is "[ ONLY ] table_name ... [ WHERE ( expression ) ]" not just
> the WHERE clause, so using curly brackets around that seems correct.
>

I disagree. {…} means “choose exactly one of the following alternatives”, but not for grouping for repetition.

For example:

```
GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER | MAINTAIN }
[, ...] | ALL [ PRIVILEGES ] }
ON { [ TABLE ] table_name [, ...]
| ALL TABLES IN SCHEMA schema_name [, ...] }
TO role_specification [, ...] [ WITH GRANT OPTION ]
[ GRANTED BY role_specification ]
```

The two levels of {} are all for alternatives.

So, I think the correct way is like:

```
TABLE table_spec [, TABLE table_spec … ]
```

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

On Fri, Nov 14, 2025 at 7:02 PM Chao Li <li.evan.chao@gmail.com> wrote:
>
>
>
> > On Nov 14, 2025, at 15:47, Fujii Masao <masao.fujii@gmail.com> wrote:
> >
> > On Fri, Nov 14, 2025 at 10:23 AM Peter Smith <smithpb2250@gmail.com> wrote:
> >>
> >> A rebase was needed. Here is patch v3.
> >
> > Thanks for the patch! LGTM.
> >
> > For example, in the CREATE PUBLICATION synopsis, the part that can be
> > repeated is "[ ONLY ] table_name ... [ WHERE ( expression ) ]" not just
> > the WHERE clause, so using curly brackets around that seems correct.
> >
>
> I disagree. {…} means “choose exactly one of the following alternatives”, but not for grouping for repetition.
>
> For example:
>
> ```
> GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER | MAINTAIN }
> [, ...] | ALL [ PRIVILEGES ] }
> ON { [ TABLE ] table_name [, ...]
> | ALL TABLES IN SCHEMA schema_name [, ...] }
> TO role_specification [, ...] [ WITH GRANT OPTION ]
> [ GRANTED BY role_specification ]
> ```
>
> The two levels of {} are all for alternatives.
>
> So, I think the correct way is like:
>
> ```
> TABLE table_spec [, TABLE table_spec … ]
> ```
>

Fair point. I've changed v4 to use a syntax similar to your suggestion:

But, instead of "TABLE <table_spec> [, <table_spec> ...]", I am just
using "TABLE <table_spec> [,...]". Maybe it is not strictly correct,
but AFAICT it is consistent with how [,...] is used elsewhere in this
and other synopses.
e.g. we don't say "<column_name> [, <column_name> ...]"

~~~

Actually, I had a couple of other changes in the pipeline for the
synopsis that I was going to post as separate patches, but since this
has become a larger change, it is probably more appropriate to address
them all at once instead of churning the same synopsis multiple times.

So, now this patch makes the following 3 changes:

#1.
My original change, to fix the [, ...] grouping to remove ambiguity.

#2
Now renames "all_publication_object" to "publication_all_objects".
This is a simple name change that does not affect anything. I felt
everything ought to have the prefix of the object it belongs to (e.g.
"publication_name", "publication_parameter", "table_name",
"schema_name", column_name" all follow this rule, but prefix "all_"
was the odd-one-out).

#3
Rearranged the synopsis order from general to detailed. Again, there
is no functional difference; I just felt it was better to use the
natural logical order: e.g.,  "publication_all_objects" >
"publication_object"

======
Kind Regards,
Peter Smith.
Fujitsu Australia

> On Nov 17, 2025, at 08:30, Peter Smith <smithpb2250@gmail.com> wrote:
>
> On Fri, Nov 14, 2025 at 7:02 PM Chao Li <li.evan.chao@gmail.com> wrote:
>>
>>
>>
>>> On Nov 14, 2025, at 15:47, Fujii Masao <masao.fujii@gmail.com> wrote:
>>>
>>> On Fri, Nov 14, 2025 at 10:23 AM Peter Smith <smithpb2250@gmail.com> wrote:
>>>>
>>>> A rebase was needed. Here is patch v3.
>>>
>>> Thanks for the patch! LGTM.
>>>
>>> For example, in the CREATE PUBLICATION synopsis, the part that can be
>>> repeated is "[ ONLY ] table_name ... [ WHERE ( expression ) ]" not just
>>> the WHERE clause, so using curly brackets around that seems correct.
>>>
>>
>> I disagree. {…} means “choose exactly one of the following alternatives”, but not for grouping for repetition.
>>
>> For example:
>>
>> ```
>> GRANT { { SELECT | INSERT | UPDATE | DELETE | TRUNCATE | REFERENCES | TRIGGER | MAINTAIN }
>> [, ...] | ALL [ PRIVILEGES ] }
>> ON { [ TABLE ] table_name [, ...]
>> | ALL TABLES IN SCHEMA schema_name [, ...] }
>> TO role_specification [, ...] [ WITH GRANT OPTION ]
>> [ GRANTED BY role_specification ]
>> ```
>>
>> The two levels of {} are all for alternatives.
>>
>> So, I think the correct way is like:
>>
>> ```
>> TABLE table_spec [, TABLE table_spec … ]
>> ```
>>
>
> Fair point. I've changed v4 to use a syntax similar to your suggestion:
>
> But, instead of "TABLE <table_spec> [, <table_spec> ...]", I am just
> using "TABLE <table_spec> [,...]". Maybe it is not strictly correct,
> but AFAICT it is consistent with how [,...] is used elsewhere in this
> and other synopses.
> e.g. we don't say "<column_name> [, <column_name> ...]"
>
> ~~~
>
> Actually, I had a couple of other changes in the pipeline for the
> synopsis that I was going to post as separate patches, but since this
> has become a larger change, it is probably more appropriate to address
> them all at once instead of churning the same synopsis multiple times.
>
> So, now this patch makes the following 3 changes:
>
> #1.
> My original change, to fix the [, ...] grouping to remove ambiguity.
>
> #2
> Now renames "all_publication_object" to "publication_all_objects".
> This is a simple name change that does not affect anything. I felt
> everything ought to have the prefix of the object it belongs to (e.g.
> "publication_name", "publication_parameter", "table_name",
> "schema_name", column_name" all follow this rule, but prefix "all_"
> was the odd-one-out).
>

I don’t like this renaming. Or at lease don’t use plural.

> #3
> Rearranged the synopsis order from general to detailed. Again, there
> is no functional difference; I just felt it was better to use the
> natural logical order: e.g.,  "publication_all_objects" >
> "publication_object"
>

I think PG doc usually place the most common form first. For publications, TABLE is used far more than TABLES IN
SCHEMA.For example, if you look at https://www.postgresql.org/docs/18/sql-grant.html, it doesn’t follow the
general->detailedrule. 

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

> On Nov 17, 2025, at 14:48, Chao Li <li.evan.chao@gmail.com> wrote:
>
>> #2
>> Now renames "all_publication_object" to "publication_all_objects".
>> This is a simple name change that does not affect anything. I felt
>> everything ought to have the prefix of the object it belongs to (e.g.
>> "publication_name", "publication_parameter", "table_name",
>> "schema_name", column_name" all follow this rule, but prefix "all_"
>> was the odd-one-out).
>>
>
> I don’t like this renaming. Or at lease don’t use plural.

I incidentally clicked on “Send” too quick. I’d add a few words on this.

Here, “all_public_object” refers to “ALL TABLES” or “ALL SEQUENCES”. In this context, the thing is “ALL” instead of
multipleobjects, that’s why I don’t like the renaming, or at lease the new name should not use plural. 

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

On Mon, Nov 17, 2025 at 5:49 PM Chao Li <li.evan.chao@gmail.com> wrote:
...
> > #1.
> > My original change, to fix the [, ...] grouping to remove ambiguity.
> >
> > #2
> > Now renames "all_publication_object" to "publication_all_objects".
> > This is a simple name change that does not affect anything. I felt
> > everything ought to have the prefix of the object it belongs to (e.g.
> > "publication_name", "publication_parameter", "table_name",
> > "schema_name", column_name" all follow this rule, but prefix "all_"
> > was the odd-one-out).
> >
>
> I don’t like this renaming. Or at lease don’t use plural.
>
> > #3
> > Rearranged the synopsis order from general to detailed. Again, there
> > is no functional difference; I just felt it was better to use the
> > natural logical order: e.g.,  "publication_all_objects" >
> > "publication_object"
> >
>
> I think PG doc usually place the most common form first. For publications, TABLE is used far more than TABLES IN
SCHEMA.For example, if you look at https://www.postgresql.org/docs/18/sql-grant.html, it doesn’t follow the
general->detailedrule. 
>

PSA v5 with some changes per your v4 review:

#1.
This is the original fix for the [, ...] grouping to remove ambiguity.

I also noticed a missing object for the ALTER DROP case, so I added
that as well. So now there are names:
- table_spec
- table_spec_drop

Got any better suggestions?

#2
Removed the plural -- now "publication_all_object"

#3
I didn't recognise that the synopsis was already in order of "common
usage", so I discarded my idea to reorder it.

======
Kind Regards,
Peter Smith.
Fujitsu Australia

> On Nov 18, 2025, at 13:31, Peter Smith <smithpb2250@gmail.com> wrote:
>
> On Mon, Nov 17, 2025 at 5:49 PM Chao Li <li.evan.chao@gmail.com> wrote:
> ...
>>> #1.
>>> My original change, to fix the [, ...] grouping to remove ambiguity.
>>>
>>> #2
>>> Now renames "all_publication_object" to "publication_all_objects".
>>> This is a simple name change that does not affect anything. I felt
>>> everything ought to have the prefix of the object it belongs to (e.g.
>>> "publication_name", "publication_parameter", "table_name",
>>> "schema_name", column_name" all follow this rule, but prefix "all_"
>>> was the odd-one-out).
>>>
>>
>> I don’t like this renaming. Or at lease don’t use plural.
>>
>>> #3
>>> Rearranged the synopsis order from general to detailed. Again, there
>>> is no functional difference; I just felt it was better to use the
>>> natural logical order: e.g.,  "publication_all_objects" >
>>> "publication_object"
>>>
>>
>> I think PG doc usually place the most common form first. For publications, TABLE is used far more than TABLES IN
SCHEMA.For example, if you look at https://www.postgresql.org/docs/18/sql-grant.html, it doesn’t follow the
general->detailedrule. 
>>
>
> PSA v5 with some changes per your v4 review:
>
> #1.
> This is the original fix for the [, ...] grouping to remove ambiguity.
>
> I also noticed a missing object for the ALTER DROP case, so I added
> that as well. So now there are names:
> - table_spec
> - table_spec_drop
>
> Got any better suggestions?
>
> #2
> Removed the plural -- now "publication_all_object"
>
> #3
> I didn't recognise that the synopsis was already in order of "common
> usage", so I discarded my idea to reorder it.
>

Thanks for addressing the comments. V5 looks good to me.

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

On Tue, Nov 18, 2025 at 5:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
> Thanks for addressing the comments. V5 looks good to me.

Thanks both for the patch and review!

-<phrase>where <replaceable
class="parameter">all_publication_object</replaceable> is one
of:</phrase>
+    <phrase>where <replaceable
class="parameter">table_spec</replaceable> is:</phrase>
+
+        [ ONLY ] <replaceable
class="parameter">table_name</replaceable> [ * ] [ ( <replaceable
class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE (
<replaceable class="parameter">expression</replaceable> ) ]
+
+<phrase>where <replaceable
class="parameter">publication_all_object</replaceable> is one
of:</phrase>

In other documentation files (e.g., merge.sgml, analyze.sgml), the definitions
of each element are chained using "and". For example, in merge.sgml:

        where data_source is:
        ...
        and when_clause is:
        ...
        and merge_insert is:
        ...

I think create_publication.sgml and alter_publication.sgml should follow
the same style for consistency. For example, in create_publication.sgml
we would have:

        where publication_object
        ...
        and publication_all_object
        ...
        and table_spec
        ...

It seems better to put these sections in the same order that the elements
appear in the syntax. So I placed publication_all_object before table_spec
in the above example.


-<phrase>where <replaceable
class="parameter">all_publication_object</replaceable> is one
of:</phrase>
+    <phrase>where <replaceable
class="parameter">table_spec</replaceable> is:</phrase>

Regarding terminology: analyze.sgml uses table_and_columns for
a similar syntax, and personally I think table_and_columns is clearer than
table_spec.

Regards,

--
Fujii Masao

Hi Fuji-San.

Thanks for your suggestions!  I've attached a new patch v6 to incorporate them.

On Thu, Nov 20, 2025 at 4:50 AM Fujii Masao <masao.fujii@gmail.com> wrote:
>
> On Tue, Nov 18, 2025 at 5:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
> > Thanks for addressing the comments. V5 looks good to me.
>
> Thanks both for the patch and review!
>
> -<phrase>where <replaceable
> class="parameter">all_publication_object</replaceable> is one
> of:</phrase>
> +    <phrase>where <replaceable
> class="parameter">table_spec</replaceable> is:</phrase>
> +
> +        [ ONLY ] <replaceable
> class="parameter">table_name</replaceable> [ * ] [ ( <replaceable
> class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE (
> <replaceable class="parameter">expression</replaceable> ) ]
> +
> +<phrase>where <replaceable
> class="parameter">publication_all_object</replaceable> is one
> of:</phrase>
>
> In other documentation files (e.g., merge.sgml, analyze.sgml), the definitions
> of each element are chained using "and". For example, in merge.sgml:
>
>         where data_source is:
>         ...
>         and when_clause is:
>         ...
>         and merge_insert is:
>         ...
>
> I think create_publication.sgml and alter_publication.sgml should follow
> the same style for consistency. For example, in create_publication.sgml
> we would have:
>
>         where publication_object
>         ...
>         and publication_all_object
>         ...
>         and table_spec
>         ...

+1. I never noticed this before.

>
> It seems better to put these sections in the same order that the elements
> appear in the syntax. So I placed publication_all_object before table_spec
> in the above example.
>
>
> -<phrase>where <replaceable
> class="parameter">all_publication_object</replaceable> is one
> of:</phrase>
> +    <phrase>where <replaceable
> class="parameter">table_spec</replaceable> is:</phrase>
>

OK. Done in v6.

> Regarding terminology: analyze.sgml uses table_and_columns for
> a similar syntax, and personally I think table_and_columns is clearer than
> table_spec.
>

Thanks for the other example usages.

+1 for naming it as 'table_and_columns' to be the same as everywhere else.

Also, to match that, I renamed 'table_spec_drop' to 'table'.

======
Kind Regards,
Peter Smith.
Fujitsu Australia

> On Nov 20, 2025, at 06:18, Peter Smith <smithpb2250@gmail.com> wrote:
>
> Hi Fuji-San.
>
> Thanks for your suggestions!  I've attached a new patch v6 to incorporate them.
>
> On Thu, Nov 20, 2025 at 4:50 AM Fujii Masao <masao.fujii@gmail.com> wrote:
>>
>> On Tue, Nov 18, 2025 at 5:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
>>> Thanks for addressing the comments. V5 looks good to me.
>>
>> Thanks both for the patch and review!
>>
>> -<phrase>where <replaceable
>> class="parameter">all_publication_object</replaceable> is one
>> of:</phrase>
>> +    <phrase>where <replaceable
>> class="parameter">table_spec</replaceable> is:</phrase>
>> +
>> +        [ ONLY ] <replaceable
>> class="parameter">table_name</replaceable> [ * ] [ ( <replaceable
>> class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE (
>> <replaceable class="parameter">expression</replaceable> ) ]
>> +
>> +<phrase>where <replaceable
>> class="parameter">publication_all_object</replaceable> is one
>> of:</phrase>
>>
>> In other documentation files (e.g., merge.sgml, analyze.sgml), the definitions
>> of each element are chained using "and". For example, in merge.sgml:
>>
>>        where data_source is:
>>        ...
>>        and when_clause is:
>>        ...
>>        and merge_insert is:
>>        ...
>>
>> I think create_publication.sgml and alter_publication.sgml should follow
>> the same style for consistency. For example, in create_publication.sgml
>> we would have:
>>
>>        where publication_object
>>        ...
>>        and publication_all_object
>>        ...
>>        and table_spec
>>        ...
>
> +1. I never noticed this before.
>
>>
>> It seems better to put these sections in the same order that the elements
>> appear in the syntax. So I placed publication_all_object before table_spec
>> in the above example.
>>
>>
>> -<phrase>where <replaceable
>> class="parameter">all_publication_object</replaceable> is one
>> of:</phrase>
>> +    <phrase>where <replaceable
>> class="parameter">table_spec</replaceable> is:</phrase>
>>
>
> OK. Done in v6.
>
>> Regarding terminology: analyze.sgml uses table_and_columns for
>> a similar syntax, and personally I think table_and_columns is clearer than
>> table_spec.
>>
>
> Thanks for the other example usages.
>
> +1 for naming it as 'table_and_columns' to be the same as everywhere else.
>

+1 as well.

V6 looks better. However, there is a typo:

In alter_publication.sgml:
```
-    TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
+    TABLE  <replaceable class="parameter">table</replaceable> [, ... ]
     TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
```
<replaceable class="parameter">table</replaceable> should be <replaceable
class="parameter">table_and_columns</replaceable>.

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

On Thu, Nov 20, 2025 at 11:02 AM Chao Li <li.evan.chao@gmail.com> wrote:
>
>
>
> > On Nov 20, 2025, at 06:18, Peter Smith <smithpb2250@gmail.com> wrote:
> >
> > Hi Fuji-San.
> >
> > Thanks for your suggestions!  I've attached a new patch v6 to incorporate them.
> >
> > On Thu, Nov 20, 2025 at 4:50 AM Fujii Masao <masao.fujii@gmail.com> wrote:
> >>
> >> On Tue, Nov 18, 2025 at 5:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
> >>> Thanks for addressing the comments. V5 looks good to me.
> >>
> >> Thanks both for the patch and review!
> >>
> >> -<phrase>where <replaceable
> >> class="parameter">all_publication_object</replaceable> is one
> >> of:</phrase>
> >> +    <phrase>where <replaceable
> >> class="parameter">table_spec</replaceable> is:</phrase>
> >> +
> >> +        [ ONLY ] <replaceable
> >> class="parameter">table_name</replaceable> [ * ] [ ( <replaceable
> >> class="parameter">column_name</replaceable> [, ... ] ) ] [ WHERE (
> >> <replaceable class="parameter">expression</replaceable> ) ]
> >> +
> >> +<phrase>where <replaceable
> >> class="parameter">publication_all_object</replaceable> is one
> >> of:</phrase>
> >>
> >> In other documentation files (e.g., merge.sgml, analyze.sgml), the definitions
> >> of each element are chained using "and". For example, in merge.sgml:
> >>
> >>        where data_source is:
> >>        ...
> >>        and when_clause is:
> >>        ...
> >>        and merge_insert is:
> >>        ...
> >>
> >> I think create_publication.sgml and alter_publication.sgml should follow
> >> the same style for consistency. For example, in create_publication.sgml
> >> we would have:
> >>
> >>        where publication_object
> >>        ...
> >>        and publication_all_object
> >>        ...
> >>        and table_spec
> >>        ...
> >
> > +1. I never noticed this before.
> >
> >>
> >> It seems better to put these sections in the same order that the elements
> >> appear in the syntax. So I placed publication_all_object before table_spec
> >> in the above example.
> >>
> >>
> >> -<phrase>where <replaceable
> >> class="parameter">all_publication_object</replaceable> is one
> >> of:</phrase>
> >> +    <phrase>where <replaceable
> >> class="parameter">table_spec</replaceable> is:</phrase>
> >>
> >
> > OK. Done in v6.
> >
> >> Regarding terminology: analyze.sgml uses table_and_columns for
> >> a similar syntax, and personally I think table_and_columns is clearer than
> >> table_spec.
> >>
> >
> > Thanks for the other example usages.
> >
> > +1 for naming it as 'table_and_columns' to be the same as everywhere else.
> >
>
> +1 as well.
>
> V6 looks better. However, there is a typo:
>
> In alter_publication.sgml:
> ```
> -    TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
> +    TABLE  <replaceable class="parameter">table</replaceable> [, ... ]
>      TABLES IN SCHEMA { <replaceable class="parameter">schema_name</replaceable> | CURRENT_SCHEMA } [, ... ]
> ```
> <replaceable class="parameter">table</replaceable> should be <replaceable
class="parameter">table_and_columns</replaceable>.
>

I think 'table' is correct. It renders like:

------
where publication_object is one of:

    TABLE table_and_columns [, ... ]
    TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]

and publication_drop_object is one of:

    TABLE  table [, ... ]
    TABLES IN SCHEMA { schema_name | CURRENT_SCHEMA } [, ... ]

and table_and_columns is:

    [ ONLY ] table_name [ * ] [ ( column_name [, ... ] ) ] [ WHERE (
expression ) ]

and table is:

    [ ONLY ] table_name [ * ]
------

The publication_drop_object cannot use 'table_and_columns' because the
columns/where-clause are not allowed for DROP. That difference was the
whole reason for making publication_drop_object in the first place.

Or is there some other typo I am missing?

======
Kind Regards,
Peter Smith.
Fujitsu Australia

On Thu, Nov 20, 2025 at 9:02 AM Chao Li <li.evan.chao@gmail.com> wrote:
> V6 looks better.

+1. Thanks for updating the patch!

+<phrase>and <replaceable class="parameter">table</replaceable> is:</phrase>
+
+    [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]

I have one question: in lock.sgml and truncate.sgml, the syntax
"[ ONLY ] name [ * ] [, ... ]" seems shown as acceptable (though
I'm not entirely sure it's actually valid). If that form is allowed,
then this change may not be necessary?

Regards,

--
Fujii Masao

On Thu, Nov 20, 2025 at 12:03 PM Fujii Masao <masao.fujii@gmail.com> wrote:
>
> On Thu, Nov 20, 2025 at 9:02 AM Chao Li <li.evan.chao@gmail.com> wrote:
> > V6 looks better.
>
> +1. Thanks for updating the patch!
>
> +<phrase>and <replaceable class="parameter">table</replaceable> is:</phrase>
> +
> +    [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
>
> I have one question: in lock.sgml and truncate.sgml, the syntax
> "[ ONLY ] name [ * ] [, ... ]" seems shown as acceptable (though
> I'm not entirely sure it's actually valid). If that form is allowed,
> then this change may not be necessary?
>

I think if this were strict BNF rules, then the bindings of the "..."
are not correct. I think the Postgres documentation is a bit loose
with the rules (e.g. your TRUNCATE example is deemed acceptable)

A user might also wonder if "ONLY a,b" means the same as "ONLY a", "ONLY b"?

But, in the interest of not bloating the ALTER PUBLICATION synopsis
too much, and still being consistent with what seems accepted by
existing PG docs, I am happy to remove that extra  'table' replacement
class. Maybe it's a bit ambiguous, but it seems mostly harmless.

Thoughts?

======
Kind Regards,
Peter Smith.
Fujitsu Australia

> On Nov 20, 2025, at 09:41, Peter Smith <smithpb2250@gmail.com> wrote:
>
> On Thu, Nov 20, 2025 at 12:03 PM Fujii Masao <masao.fujii@gmail.com> wrote:
>>
>> On Thu, Nov 20, 2025 at 9:02 AM Chao Li <li.evan.chao@gmail.com> wrote:
>>> V6 looks better.
>>
>> +1. Thanks for updating the patch!
>>
>> +<phrase>and <replaceable class="parameter">table</replaceable> is:</phrase>
>> +
>> +    [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
>>
>> I have one question: in lock.sgml and truncate.sgml, the syntax
>> "[ ONLY ] name [ * ] [, ... ]" seems shown as acceptable (though
>> I'm not entirely sure it's actually valid). If that form is allowed,
>> then this change may not be necessary?
>>
>
> I think if this were strict BNF rules, then the bindings of the "..."
> are not correct. I think the Postgres documentation is a bit loose
> with the rules (e.g. your TRUNCATE example is deemed acceptable)
>
> A user might also wonder if "ONLY a,b" means the same as "ONLY a", "ONLY b"?
>
> But, in the interest of not bloating the ALTER PUBLICATION synopsis
> too much, and still being consistent with what seems accepted by
> existing PG docs, I am happy to remove that extra  'table' replacement
> class. Maybe it's a bit ambiguous, but it seems mostly harmless.
>
> Thoughts?
>

I think the new code of publication_drop_object has changed the original meaning.

Old code:
```
-    TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
```

Means the drop clause can be:
```
ALTER PUBLICATION DROP TABLE ONLY t1*, TABLE ONLY t2*
```

Now, the new code:
```
+    TABLE  <replaceable class="parameter">table</replaceable> [, … ]
<phrase>and <replaceable class="parameter">table</replaceable> is:</phrase>
+
+    [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
```

Changes the meaning to:
```
ALTER PUBLICATION DROP TABLE ONLY t1*, ONLY t2*
```

So, I think we should keep the old code.

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

On Thu, Nov 20, 2025 at 2:06 PM Chao Li <li.evan.chao@gmail.com> wrote:
>
>
>
> > On Nov 20, 2025, at 09:41, Peter Smith <smithpb2250@gmail.com> wrote:
> >
> > On Thu, Nov 20, 2025 at 12:03 PM Fujii Masao <masao.fujii@gmail.com> wrote:
> >>
> >> On Thu, Nov 20, 2025 at 9:02 AM Chao Li <li.evan.chao@gmail.com> wrote:
> >>> V6 looks better.
> >>
> >> +1. Thanks for updating the patch!
> >>
> >> +<phrase>and <replaceable class="parameter">table</replaceable> is:</phrase>
> >> +
> >> +    [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
> >>
> >> I have one question: in lock.sgml and truncate.sgml, the syntax
> >> "[ ONLY ] name [ * ] [, ... ]" seems shown as acceptable (though
> >> I'm not entirely sure it's actually valid). If that form is allowed,
> >> then this change may not be necessary?
> >>
> >
> > I think if this were strict BNF rules, then the bindings of the "..."
> > are not correct. I think the Postgres documentation is a bit loose
> > with the rules (e.g. your TRUNCATE example is deemed acceptable)
> >
> > A user might also wonder if "ONLY a,b" means the same as "ONLY a", "ONLY b"?
> >
> > But, in the interest of not bloating the ALTER PUBLICATION synopsis
> > too much, and still being consistent with what seems accepted by
> > existing PG docs, I am happy to remove that extra  'table' replacement
> > class. Maybe it's a bit ambiguous, but it seems mostly harmless.
> >
> > Thoughts?
> >
>
> I think the new code of publication_drop_object has changed the original meaning.
>
> Old code:
> ```
> -    TABLE [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ] [, ... ]
> ```
>
> Means the drop clause can be:
> ```
> ALTER PUBLICATION DROP TABLE ONLY t1*, TABLE ONLY t2*
> ```
>
> Now, the new code:
> ```
> +    TABLE  <replaceable class="parameter">table</replaceable> [, … ]
> <phrase>and <replaceable class="parameter">table</replaceable> is:</phrase>
> +
> +    [ ONLY ] <replaceable class="parameter">table_name</replaceable> [ * ]
> ```
>
> Changes the meaning to:
> ```
> ALTER PUBLICATION DROP TABLE ONLY t1*, ONLY t2*
> ```
>

There are 2 sets of ellipses:
Here: "publication_drop_object [, ...]"
And here "TABLE  <replaceable class="parameter">table</replaceable> [, … ]"

So I think there is no change of meaning. AFAICT all variations are
possible, same as they always were. It just depends which way you
squint at the syntax -- e.g. are you conceptually expanding another
"publication_drop_objecr"  replacement or expanding another "table"
replacement.

> So, I think we should keep the old code.

Anyway, I am happy to go back to the old code. I'll post another patch
later to do that.

======
Kind Regards,
Peter Smith.
Fujitsu Australia

I've reverted the ALTER 'publication_drop_object' part to be the same
as master (i.e. removed the v6 'table' replacement) after Fujii-San
showed [1] that the original synopsis style is present on some other
documentation pages.

PSS new patch v7.

======
[1] https://www.postgresql.org/message-id/CAHGQGwHOQJCG-THQ1iBE7rTncjYXmXa7TSfDZn5RP%2BjM35wnsQ%40mail.gmail.com

Kind Regards,
Peter Smith.
Fujitsu Australia

> On Nov 21, 2025, at 05:08, Peter Smith <smithpb2250@gmail.com> wrote:
>
> I've reverted the ALTER 'publication_drop_object' part to be the same
> as master (i.e. removed the v6 'table' replacement) after Fujii-San
> showed [1] that the original synopsis style is present on some other
> documentation pages.
>
> PSS new patch v7.
>
> ======
> [1] https://www.postgresql.org/message-id/CAHGQGwHOQJCG-THQ1iBE7rTncjYXmXa7TSfDZn5RP%2BjM35wnsQ%40mail.gmail.com
>
> Kind Regards,
> Peter Smith.
> Fujitsu Australia
> <v7-0001-Fix-synopsis.patch>

I rendered the html pages with v7 patched. LGTM.

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

On Fri, Nov 21, 2025 at 3:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
>
>
>
> > On Nov 21, 2025, at 05:08, Peter Smith <smithpb2250@gmail.com> wrote:
> >
> > I've reverted the ALTER 'publication_drop_object' part to be the same
> > as master (i.e. removed the v6 'table' replacement) after Fujii-San
> > showed [1] that the original synopsis style is present on some other
> > documentation pages.
> >
> > PSS new patch v7.

Thanks for updating the patch! LGTM.

One question: do we want to backpatch this? If so, to which versions?
If we decide to backpatch, it would be helpful if you could provide versions
of the patch that apply cleanly to those older branches.


> I rendered the html pages with v7 patched. LGTM.

+1

Regards,


--
Fujii Masao

> On Nov 25, 2025, at 18:42, Fujii Masao <masao.fujii@gmail.com> wrote:
>
> On Fri, Nov 21, 2025 at 3:27 PM Chao Li <li.evan.chao@gmail.com> wrote:
>>
>>
>>
>>> On Nov 21, 2025, at 05:08, Peter Smith <smithpb2250@gmail.com> wrote:
>>>
>>> I've reverted the ALTER 'publication_drop_object' part to be the same
>>> as master (i.e. removed the v6 'table' replacement) after Fujii-San
>>> showed [1] that the original synopsis style is present on some other
>>> documentation pages.
>>>
>>> PSS new patch v7.
>
> Thanks for updating the patch! LGTM.
>
> One question: do we want to backpatch this? If so, to which versions?
> If we decide to backpatch, it would be helpful if you could provide versions
> of the patch that apply cleanly to those older branches.
>

I just checked the docs version by version, looks like the back-port can go down to 15.

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