doc: Fix ALTER PUBLICATION details

Some of the text was made nonsensical by commit
e9500240661c03750923e6f539bfa2d75cfaa32a.  Fix that and make some other
minor changes.

Reported-by: Jeff Janes <[email protected]>

2 files changed, 27 insertions, 10 deletions

diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
index 7b8f114f54..cc5d92f041 100644
--- a/doc/src/sgml/ref/alter_publication.sgml
+++ b/doc/src/sgml/ref/alter_publication.sgml
@@ -34,28 +34,40 @@ ALTER PUBLICATION <replaceable class="PARAMETER">name</replaceable> RENAME TO <r
   <title>Description</title>
 
   <para>
-   The first variant of this command listed in the synopsis can change
+   The command <command>ALTER PUBLICATION</command> can change the attributes
+   of a publication.
+  </para>
+
+  <para>
+   The first three variants change which tables are part of the publication.
+   The <literal>SET TABLE</literal> clause will replace the list of tables in
+   the publication with the specified one.  The <literal>ADD TABLE</literal>
+   and <literal>DROP TABLE</literal> clauses will add and remove one or more
+   tables from the publication.  Note that adding tables to a publication that
+   is already subscribed to will require a <literal>ALTER SUBSCRIPTION
+   ... REFRESH PUBLICATION</literal> action on the subscribing side in order
+   to become effective.
+  </para>
+
+  <para>
+   The fourth variant of this command listed in the synopsis can change
    all of the publication properties specified in
    <xref linkend="sql-createpublication">.  Properties not mentioned in the
    command retain their previous settings.
   </para>
 
   <para>
+   The remaining variants change the owner and the name of the publication.
+  </para>
+
+  <para>
+   You must own the publication to use <command>ALTER PUBLICATION</command>.
    To alter the owner, you must also be a direct or indirect member of the new
    owning role. The new owner must have <literal>CREATE</literal> privilege on
    the database.  Also, the new owner of a <literal>FOR ALL TABLES</literal>
    publication must be a superuser.  However, a superuser can change the
    ownership of a publication while circumventing these restrictions.
   </para>
-
-  <para>
-   The other variants of this command deal with the table membership of the
-   publication.  The <literal>SET TABLE</literal> clause will replace the
-   list of tables in the publication with the specified one.
-   The <literal>ADD TABLE</literal> and
-   <literal>DROP TABLE</literal> will add and remove one or more tables from
-   the publication.
-  </para>
  </refsect1>
 
  <refsect1>
@@ -147,6 +159,8 @@ ALTER PUBLICATION mypublication ADD TABLE users, departments;
   <simplelist type="inline">
    <member><xref linkend="sql-createpublication"></member>
    <member><xref linkend="sql-droppublication"></member>
+   <member><xref linkend="sql-createsubscription"></member>
+   <member><xref linkend="sql-altersubscription"></member>
   </simplelist>
  </refsect1>
 </refentry>
diff --git a/doc/src/sgml/ref/alter_subscription.sgml b/doc/src/sgml/ref/alter_subscription.sgml
index 113e32bfd0..a3471a0442 100644
--- a/doc/src/sgml/ref/alter_subscription.sgml
+++ b/doc/src/sgml/ref/alter_subscription.sgml
@@ -42,8 +42,11 @@ ALTER SUBSCRIPTION <replaceable class="PARAMETER">name</replaceable> RENAME TO <
   </para>
 
   <para>
+   You must own the subscription to use <command>ALTER SUBSCRIPTION</>.
    To alter the owner, you must also be a direct or indirect member of the
    new owning role. The new owner has to be a superuser.
+   (Currently, all subscription owners must be superusers, so the owner checks
+   will be bypassed in practice.  But this might change in the future.)
   </para>
  </refsect1>