Re: CREATE/ALTER PUBLICATION improvements for syntax synopsis - Mailing list pgsql-hackers

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