Add XML ID attributes to create_publication.sgml.

Amit Kapila · Amit Kapila · commit ed94e8563e03 · 2023-03-31T08:59:55.000+05:30
This commit adds XML ID attributes to all varlistentries in create_publication.sgml. This allows us to include links to refer to publication options, making documents more readable. Author: Kuroda Hayato Reviewed-by: Peter Smith, Amit Kapila Discussion: https://postgr.es/m/TYAPR01MB58668219FEA4EC231486A433F58E9@TYAPR01MB5866.jpnprd01.prod.outlook.com
diff --git a/doc/src/sgml/logical-replication.sgml b/doc/src/sgml/logical-replication.sgml
@@ -367,7 +367,8 @@ INSERT 0 3
 
     <para>
      Create publications for the tables. The publications <literal>pub2</literal>
-     and <literal>pub3a</literal> disallow some <literal>publish</literal>
+     and <literal>pub3a</literal> disallow some
+     <link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
      operations. The publication <literal>pub3b</literal> has a row filter (see
      <xref linkend="logical-replication-row-filter"/>).
 <programlisting>
@@ -801,11 +802,12 @@ ALTER SUBSCRIPTION
 
    <para>
     If the publication contains a partitioned table, the publication parameter
-    <literal>publish_via_partition_root</literal> determines which row filter
-    is used. If <literal>publish_via_partition_root</literal> is <literal>true</literal>,
-    the <emphasis>root partitioned table's</emphasis> row filter is used. Otherwise,
-    if <literal>publish_via_partition_root</literal> is <literal>false</literal>
-    (default), each <emphasis>partition's</emphasis> row filter is used.
+    <link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
+    determines which row filter is used. If <literal>publish_via_partition_root</literal>
+    is <literal>true</literal>, the <emphasis>root partitioned table's</emphasis>
+    row filter is used. Otherwise, if <literal>publish_via_partition_root</literal>
+    is <literal>false</literal> (default), each <emphasis>partition's</emphasis>
+    row filter is used.
    </para>
 
   </sect2>
@@ -829,8 +831,9 @@ ALTER SUBSCRIPTION
    <warning>
     <para>
      Because initial data synchronization does not take into account the
-     <literal>publish</literal> parameter when copying existing table data,
-     some rows may be copied that would not be replicated using DML. Refer to
+     <link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
+     parameter when copying existing table data, some rows may be copied that
+     would not be replicated using DML. Refer to
      <xref linkend="logical-replication-snapshot"/>, and see
      <xref linkend="logical-replication-subscription-examples"/> for examples.
     </para>
@@ -851,7 +854,8 @@ ALTER SUBSCRIPTION
 
    <para>
     If the subscription has several publications in which the same table has
-    been published with different row filters (for the same <literal>publish</literal>
+    been published with different row filters (for the same
+    <link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
     operation), those expressions get ORed together, so that rows satisfying
     <emphasis>any</emphasis> of the expressions will be replicated. This means all
     the other row filters for the same table become redundant if:
@@ -863,15 +867,17 @@ ALTER SUBSCRIPTION
      </listitem>
      <listitem>
       <para>
-       One of the publications was created using <literal>FOR ALL TABLES</literal>.
+       One of the publications was created using
+       <link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>.
        This clause does not allow row filters.
       </para>
      </listitem>
      <listitem>
       <para>
        One of the publications was created using
-       <literal>FOR TABLES IN SCHEMA</literal> and the table belongs to
-       the referred schema. This clause does not allow row filters.
+       <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
+       and the table belongs to the referred schema. This clause does not allow
+       row filters.
       </para>
      </listitem>
     </itemizedlist></para>
@@ -1136,9 +1142,9 @@ test_sub=# SELECT * FROM t1;
 
    <para>
     The following examples show how the publication parameter
-    <literal>publish_via_partition_root</literal> determines whether the row
-    filter of the parent or child table will be used in the case of partitioned
-    tables.
+    <link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
+    determines whether the row filter of the parent or child table will be used
+    in the case of partitioned tables.
    </para>
 
    <para>
@@ -1291,15 +1297,16 @@ test_sub=# SELECT * FROM child ORDER BY a;
 
   <para>
    Specifying a column list when the publication also publishes
-   <literal>FOR TABLES IN SCHEMA</literal> is not supported.
+   <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
+   is not supported.
   </para>
 
   <para>
    For partitioned tables, the publication parameter
-   <literal>publish_via_partition_root</literal> determines which column list
-   is used. If <literal>publish_via_partition_root</literal> is
-   <literal>true</literal>, the root partitioned table's column list is used.
-   Otherwise, if <literal>publish_via_partition_root</literal> is
+   <link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
+   determines which column list is used. If <literal>publish_via_partition_root</literal>
+   is <literal>true</literal>, the root partitioned table's column list is
+   used. Otherwise, if <literal>publish_via_partition_root</literal> is
    <literal>false</literal> (the default), each partition's column list is used.
   </para>
 
@@ -1610,7 +1617,9 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
      tables.)  Publications can also specify that changes are to be replicated
      using the identity and schema of the partitioned root table instead of
      that of the individual leaf partitions in which the changes actually
-     originate (see <link linkend="sql-createpublication"><command>CREATE PUBLICATION</command></link>).
+     originate (see
+     <link linkend="sql-createpublication-with-publish-via-partition-root"><literal>publish_via_partition_root</literal></link>
+     parameter of <command>CREATE PUBLICATION</command>).
     </para>
    </listitem>
   </itemizedlist>
@@ -1676,9 +1685,11 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
     </para>
     <note>
      <para>
-      The publication <literal>publish</literal> parameter only affects what
-      DML operations will be replicated. The initial data synchronization does
-      not take this parameter into account when copying the existing table data.
+      The publication
+      <link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
+      parameter only affects what DML operations will be replicated. The
+      initial data synchronization does not take this parameter into account
+      when copying the existing table data.
      </para>
     </note>
   </sect2>
@@ -1724,10 +1735,11 @@ CONTEXT:  processing remote data for replication origin "pg_16395" during "INSER
    and <literal>TRIGGER</literal> privilege on such tables to trusted roles.
    Moreover, if untrusted users can create tables, use only
    publications that list tables explicitly.  That is to say, create a
-   subscription <literal>FOR ALL TABLES</literal> or
-   <literal>FOR TABLES IN SCHEMA</literal> only when superusers trust
-   every user permitted to create a non-temp table on the publisher or the
-   subscriber.
+   subscription
+   <link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
+   or <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
+   only when superusers trust every user permitted to create a non-temp table
+   on the publisher or the subscriber.
   </para>
 
   <para>
diff --git a/doc/src/sgml/ref/alter_publication.sgml b/doc/src/sgml/ref/alter_publication.sgml
@@ -54,7 +54,8 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
    <literal>ALTER SUBSCRIPTION ... REFRESH PUBLICATION</literal> action on the
    subscribing side in order to become effective. Note also that
    <literal>DROP TABLES IN SCHEMA</literal> will not drop any schema tables
-   that were specified using <literal>FOR TABLE</literal>/
+   that were specified using
+   <link linkend="sql-createpublication-for-table"><literal>FOR TABLE</literal></link>/
    <literal>ADD TABLE</literal>, and the combination of <literal>DROP</literal>
    with a <literal>WHERE</literal> clause is not allowed.
   </para>
@@ -79,8 +80,9 @@ ALTER PUBLICATION <replaceable class="parameter">name</replaceable> RENAME TO <r
    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.
-   Also, the new owner of a <literal>FOR ALL TABLES</literal> or
-   <literal>FOR TABLES IN SCHEMA</literal>
+   Also, the new owner of a
+   <link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
+   or <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>
    publication must be a superuser. However, a superuser can
    change the ownership of a publication regardless of these restrictions.
   </para>
diff --git a/doc/src/sgml/ref/create_publication.sgml b/doc/src/sgml/ref/create_publication.sgml
@@ -54,7 +54,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
   <title>Parameters</title>
 
   <variablelist>
-   <varlistentry>
+   <varlistentry id="sql-createpublication-name">
     <term><replaceable class="parameter">name</replaceable></term>
     <listitem>
      <para>
@@ -63,7 +63,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createpublication-for-table">
     <term><literal>FOR TABLE</literal></term>
     <listitem>
      <para>
@@ -117,7 +117,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createpublication-for-all-tables">
     <term><literal>FOR ALL TABLES</literal></term>
     <listitem>
      <para>
@@ -127,7 +127,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createpublication-for-tables-in-schema">
     <term><literal>FOR TABLES IN SCHEMA</literal></term>
     <listitem>
      <para>
@@ -158,15 +158,15 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
     </listitem>
    </varlistentry>
 
-   <varlistentry>
+   <varlistentry id="sql-createpublication-with">
     <term><literal>WITH ( <replaceable class="parameter">publication_parameter</replaceable> [= <replaceable class="parameter">value</replaceable>] [, ... ] )</literal></term>
     <listitem>
      <para>
       This clause specifies optional parameters for a publication.  The
       following parameters are supported:
 
       <variablelist>
-       <varlistentry>
+       <varlistentry id="sql-createpublication-with-publish">
         <term><literal>publish</literal> (<type>string</type>)</term>
         <listitem>
          <para>
@@ -188,7 +188,7 @@ CREATE PUBLICATION <replaceable class="parameter">name</replaceable>
         </listitem>
        </varlistentry>
 
-       <varlistentry>
+       <varlistentry id="sql-createpublication-with-publish-via-partition-root">
         <term><literal>publish_via_partition_root</literal> (<type>boolean</type>)</term>
         <listitem>
          <para>
diff --git a/doc/src/sgml/ref/create_subscription.sgml b/doc/src/sgml/ref/create_subscription.sgml
@@ -438,16 +438,18 @@ CREATE SUBSCRIPTION <replaceable class="parameter">subscription_name</replaceabl
    the case of different <literal>WHERE</literal> clauses, if one of the
    publications has no <literal>WHERE</literal> clause (referring to that
    publish operation) or the publication is declared as
-   <literal>FOR ALL TABLES</literal> or
-   <literal>FOR TABLES IN SCHEMA</literal>, rows are always published
-   regardless of the definition of the other expressions.
-   If the subscriber is a <productname>PostgreSQL</productname> version before
-   15, then any row filtering is ignored during the initial data synchronization
-   phase. For this case, the user might want to consider deleting any initially
-   copied data that would be incompatible with subsequent filtering.
-   Because initial data synchronization does not take into account the publication
-   <literal>publish</literal> parameter when copying existing table data, some rows
-   may be copied that would not be replicated using DML. See
+   <link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
+   or <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
+   rows are always published regardless of the definition of the other
+   expressions. If the subscriber is a <productname>PostgreSQL</productname>
+   version before 15, then any row filtering is ignored during the initial data
+   synchronization phase. For this case, the user might want to consider
+   deleting any initially copied data that would be incompatible with
+   subsequent filtering. Because initial data synchronization does not take
+   into account the publication
+   <link linkend="sql-createpublication-with-publish"><literal>publish</literal></link>
+   parameter when copying existing table data, some rows may be copied that
+   would not be replicated using DML. See
    <xref linkend="logical-replication-subscription-examples"/> for examples.
   </para>
 
diff --git a/doc/src/sgml/system-views.sgml b/doc/src/sgml/system-views.sgml
@@ -2145,9 +2145,10 @@ SELECT * FROM pg_locks pl LEFT JOIN pg_prepared_xacts ppx
    information about the mapping between publications and information of
    tables they contain.  Unlike the underlying catalog
    <link linkend="catalog-pg-publication-rel"><structname>pg_publication_rel</structname></link>,
-   this view expands publications defined as <literal>FOR ALL TABLES</literal>
-   and <literal>FOR TABLES IN SCHEMA</literal>, so for such publications
-   there will be a row for each eligible table.
+   this view expands publications defined as
+   <link linkend="sql-createpublication-for-all-tables"><literal>FOR ALL TABLES</literal></link>
+   and <link linkend="sql-createpublication-for-tables-in-schema"><literal>FOR TABLES IN SCHEMA</literal></link>,
+   so for such publications there will be a row for each eligible table.
   </para>
 
   <table>
