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

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