From 241f9ef9d321aa2a4619c3ea978813332ccf601d Mon Sep 17 00:00:00 2001
From: Fujii Masao <fujii@postgresql.org>
Date: Wed, 22 Jul 2026 11:41:48 +0900
Subject: [PATCH v2] doc: Improve PUBLICATION ... EXCEPT documentation

Clarify that ALTER PUBLICATION SET ALL TABLES replaces or clears
the EXCEPT list, rather than adding entries to it.  Also note that
subscribers need ALTER SUBSCRIPTION ... REFRESH PUBLICATION
when the EXCEPT list changes.

While here, fix nearby wording and markup in the CREATE/ALTER PUBLICATION
reference pages.

Author: Fujii Masao <masao.fujii@gmail.com>
Reviewed-by: Peter Smith <smithpb2250@gmail.com>
Discussion: https://postgr.es/m/CAHGQGwEqRP9TwObgdXsMxgF04hPrVH7Y7dAspBHzE=2MYURw1g@mail.gmail.com
Backpatch-through: 19
---
 doc/src/sgml/ref/alter_publication.sgml  | 23 ++++++++++++-----------
 doc/src/sgml/ref/create_publication.sgml |  4 ++--
 2 files changed, 14 insertions(+), 13 deletions(-)

diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 52114a16a39..8f2c5ba03c3 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -79,13 +79,13 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
    <literal>SET ALL TABLES</literal> clause can transform an empty publication,
    or one defined for <literal>ALL SEQUENCES</literal> (or both
    <literal>ALL TABLES</literal> and <literal>ALL SEQUENCES</literal>), into
-   a publication defined for ALL TABLES. Likewise,
+   a publication defined for <literal>ALL TABLES</literal>. Likewise,
    <literal>SET ALL SEQUENCES</literal> can convert an empty publication, or
    one defined for <literal>ALL TABLES</literal> (or both
    <literal>ALL TABLES</literal> and <literal>ALL SEQUENCES</literal>), into a
    publication defined for <literal>ALL SEQUENCES</literal>. In addition,
-   <literal>SET ALL TABLES</literal> can be used to update the tables specified
-   in the <literal>EXCEPT</literal> clause of a
+   <literal>SET ALL TABLES</literal> can be used to replace or clear the table
+   list specified in the <literal>EXCEPT</literal> clause of a
    <literal>FOR ALL TABLES</literal> publication. If <literal>EXCEPT</literal>
    is specified with a list of tables, the existing exclusion list is replaced
    with the specified tables. If <literal>EXCEPT</literal> is omitted, the
@@ -97,15 +97,16 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
   </para>
 
   <para>
-   Note that adding tables/except tables/schemas to a publication that is
-   already subscribed to will require an
+   Note that adding, dropping, or setting tables or schemas in a publication
+   that is already subscribed to will require an
    <link linkend="sql-altersubscription-params-refresh-publication">
    <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal></link> action
    on the subscribing side in order to become effective. Likewise altering a
-   publication to set <literal>ALL TABLES</literal> or to set or unset
-   <literal>ALL SEQUENCES</literal> also requires the subscriber to refresh the
-   publication. Note also that <literal>DROP TABLES IN SCHEMA</literal> will
-   not drop any schema tables that were specified using
+   publication to set <literal>ALL TABLES</literal>, to change the
+   <literal>EXCEPT</literal> list, or to set or unset <literal>ALL
+   SEQUENCES</literal> also requires the subscriber to refresh the publication.
+   Note also that <literal>DROP TABLES IN SCHEMA</literal> will not drop any
+   schema tables that were specified using
    <link linkend="sql-createpublication-params-for-table"><literal>FOR TABLE</literal></link>/
    <literal>ADD TABLE</literal>.
   </para>
@@ -126,8 +127,8 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
    Adding a table to a publication additionally requires owning that table.
    The <literal>ADD TABLES IN SCHEMA</literal>,
    <literal>SET TABLES IN SCHEMA</literal>, <literal>SET ALL TABLES</literal>,
-   and <literal>SET ALL SEQUENCES</literal> to a publication requires the
-   invoking user to be a superuser.
+   and <literal>SET ALL SEQUENCES</literal> forms require the invoking user to
+   be a superuser.
    To alter the owner, you must be able to <literal>SET ROLE</literal> to the
    new owning role, and that role must have <literal>CREATE</literal>
    privilege on the database.
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
index 85cfcaddafa..026a3a22d6c 100644
--- a/doc/src/sgml/ref/create_publication.sgml
+++ b/doc/src/sgml/ref/create_publication.sgml
@@ -173,7 +173,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
      <para>
       Marks the publication as one that replicates changes for all tables in
       the database, including tables created in the future. Tables listed in
-      <literal>EXCEPT</literal> clause are excluded from the publication.
+      the <literal>EXCEPT</literal> clause are excluded from the publication.
      </para>
     </listitem>
    </varlistentry>
@@ -218,7 +218,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
       For partitioned tables, only the root partitioned table may be specified
       in <literal>EXCEPT</literal>. Doing so excludes the root table and
       all of its partitions from replication. The optional
-      <literal>ONLY</literal> and <literal>*</literal> has no effect for
+      <literal>ONLY</literal> and <literal>*</literal> have no effect for
       partitioned tables.
      </para>
      <para>
-- 
2.55.0